Publix APIpublix.com ↗
Search Publix products, retrieve pricing and promotions, browse weekly ad deals, find store locations, and get category data via a structured JSON API.
What is the Publix API?
The Publix API covers 7 endpoints that expose product catalog data, store locations, weekly ad deals, and search suggestions from Publix grocery stores. Use search_products to query the full catalog with pricing, sale status, and image URLs, or call get_weekly_ad to pull all active promotional deals for a specific store — including savings amounts, department tags, and promotion date ranges.
curl -X POST 'https://api.parse.bot/scraper/311a0a1a-57d6-41d3-b87d-b2cc0de89ded/search_products' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"limit": "5",
"query": "milk",
"offset": "0",
"store_number": "1425"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace publix-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Publix SDK — meal planning, product search, store deals."""
from parse_apis.Publix_Grocery_Store_API import Publix, ProductNotFound
publix = Publix()
# Search for products to plan meals around
for product in publix.products.search(query="chicken breast", limit=5):
print(product.title, product.price_line, product.size_description)
# Get typeahead suggestions for quick ingredient lookup
suggestion = publix.products.suggest(query="organ")
for text in suggestion.text_suggestions:
print(text)
for ps in suggestion.product_suggestions:
print(ps.title, ps.base_product_id)
# Find nearby stores
for store in publix.stores.search(query="33134", limit=3):
print(store.name, store.address.city, store.address.zip)
# Check weekly ad deals at a specific store
miami_store = publix.store(store_number="1425")
for deal in miami_store.weekly_ad(limit=5):
print(deal.title, deal.savings, deal.department)
# Browse sub sandwich deals
for sub in miami_store.sub_deals(limit=3):
print(sub.title, sub.price_line, sub.saving_line)
# Drill into a product for full details
first_product = publix.products.search(query="milk", limit=1).first()
if first_product:
try:
detailed = first_product.refresh()
print(detailed.title, detailed.title_brand, detailed.size_description)
except ProductNotFound as exc:
print(f"Product removed: {exc}")
# Browse category tree for meal planning inspiration
for category in publix.categories.list(limit=5):
print(category.name, category.display_name)
print("exercised: products.search / products.suggest / stores.search / store.weekly_ad / store.sub_deals / product.refresh / categories.list")
Full-text search over the Publix product catalog via GraphQL. Returns product listings with pricing, promotions, brand, taxonomy, and image URLs. Supports pagination via offset/limit. Results are store-specific when a store_number is provided.
| Param | Type | Description |
|---|---|---|
| limit | integer | Max results to return per request. |
| queryrequired | string | Search keyword (e.g. 'milk', 'organic bread'). |
| offset | integer | Number of results to skip for pagination. |
| store_number | string | Publix store number for store-specific pricing. Defaults to '1425'. |
{
"type": "object",
"fields": {
"total": "integer total number of matching products",
"products": "array of product objects with baseProductId, itemCode, title, sizeDescription, priceLine, onSale, savingLine, promoMsg, promoType, promoTotalSavings, imageUrls, titleBrand, fauxTaxonomy, nutritionalDescriptionObject"
},
"sample": {
"data": {
"total": 168,
"products": [
{
"title": "Publix Milk, Whole",
"onSale": false,
"itemCode": 70800,
"promoMsg": null,
"imageUrls": {
"large": {
"a": "https://images.publixcdn.com/pct/images/products/70000/070800-600x600-A.jpg"
},
"small": {
"a": "https://images.publixcdn.com/pct/images/products/70000/070800-75x75-A.jpg"
}
},
"priceLine": null,
"promoType": null,
"savingLine": null,
"titleBrand": "Publix",
"fauxTaxonomy": [
"Dairy/Milk and Milk Alternatives"
],
"baseProductId": "RIO-PCI-113569",
"sizeDescription": "1 gal (3.78L)",
"promoTotalSavings": 0
}
]
},
"status": "success"
}
}About the Publix API
Product Search and Details
search_products accepts a keyword query plus an optional store_number and returns an array of product objects including priceLine, onSale, savingLine, sizeDescription, and imageUrls. Results are paginated via limit and offset. When you need full ingredient data, get_product_details accepts either a baseProductId or itemCode (both available from search results) and returns a ingredients field alongside priceLine, onSale, and sizeDescription. Note that ingredients may be an empty string for products where that data is unavailable.
Deals and Weekly Ads
get_weekly_ad retrieves all active weekly ad promotions for a given store_number, returning Title, Description, Savings, Department, Brand, ImageUrl, WA_StartDate, and WA_EndDate per deal. Setting page_size to 0 returns the full deal set in a single response. The specialized get_sub_sandwich_deals endpoint narrows results to sub sandwich items currently on promotion, returning priceLine, savingLine, promoMsg, and promoTotalSavings for each matching item.
Stores and Categories
find_stores takes a city name, a city, state string, or a 5-digit US zip code and returns store objects with storeNumber, address, phoneNumbers, hours, departments, services, latitude, longitude, and distance. The get_all_categories endpoint returns a flat list of category objects — each with a UUID ID, Name, and DisplayName — representing the full Publix catalog taxonomy, optionally scoped to a specific store.
Search Suggestions
get_suggestions provides typeahead support: submit a partial keyword (e.g. 'chick') and receive both TextSuggestions (string completions) and ProductSuggestions (preview objects with title, itemCode, and imageUrls). This is useful for building autocomplete interfaces or validating search terms before issuing a full search_products call.
The Publix API is a managed, monitored endpoint for publix.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when publix.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official publix.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track weekly Publix sale prices for specific product categories using get_weekly_ad and filtering by Department
- Build a grocery price comparison tool using priceLine and onSale fields from search_products across multiple store numbers
- Power a store locator feature by querying find_stores with zip codes and mapping results using latitude/longitude fields
- Check ingredient lists for allergen screening using the ingredients field returned by get_product_details
- Monitor sub sandwich promotions automatically with get_sub_sandwich_deals to alert users when deals go live
- Build a category-browsing UI for the Publix catalog using the UUID-keyed category tree from get_all_categories
- Implement search autocomplete using TextSuggestions and ProductSuggestions from get_suggestions
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.