Skip to content
AZ Labs
storefront

Services

Grocery Data API

Compare current prices across four South African retailers. Use the API in your own tools, or open the AZ Labs Groceries workspace to chat, plan a basket and review your shopping history.

Developer quickstart

Live in three lines

Every request is authenticated with a standard bearer key from your dashboard — the same keys the AI Gateway uses. No SDK, no setup, no card.

GET/api/v1/grocery/search?q={query}&store={pnp|checkers|woolworths|makro|all}&limit={1-20}

Live catalogue search with prices, was-prices, promotions, images, product links and stock state.

GET/api/v1/grocery/compare?q={query}&limit={1-10}

Size-normalized side-by-side comparison with cheapest-store detection, saving, and the products that could not be matched.

GET/api/v1/grocery/products?store={pnp|checkers|woolworths|makro}&id={productId}

Direct single-product lookup by store barcode or catalogue code.

GET/api/v1/grocery/stores

List supported supermarket retailers, branch codes, regions, and capability flags. Does not use quota.

curl "https://azlabs.ai/api/v1/grocery/compare?q=clover+full+cream+milk+2l&limit=1" \
  -H "Authorization: Bearer sk-azl-live-..."

Response

{
  "query": "clover full cream milk 2l",
  "matches": [
    {
      "size": "2000ml",
      "name": "Clover Full Cream Milk Fresh 2L",
      "offers": [
        {
          "store": "pnp",
          "storeName": "Pick n Pay Claremont",
          "productId": "000000000000203686_EA",
          "name": "Clover Full Cream Milk Fresh 2L",
          "price": 29.99,
          "priceFormatted": "R29.99",
          "inStock": true,
          "stockState": "in_stock",
          "promotions": []
        },
        {
          "store": "checkers",
          "storeName": "Checkers Sixty60",
          "productId": "5d3af63bf434cf8420737dd6",
          "name": "Clover Fresh Full Cream Milk 2L",
          "price": 37.99,
          "priceFormatted": "R37.99",
          "inStock": true,
          "stockState": "in_stock",
          "promotions": [
            "Now R29.99"
          ]
        }
      ],
      "cheapestStores": [
        "pnp"
      ],
      "saving": 8
    }
  ],
  "unmatched": {
    "pnp": [],
    "checkers": [],
    "woolworths": [
      {
        "store": "woolworths",
        "storeName": "Woolworths",
        "productId": "20011697",
        "name": "Fresh Full Cream Milk 2 L",
        "price": 38.99,
        "priceFormatted": "R38.99",
        "oldPrice": null,
        "oldPriceFormatted": null,
        "inStock": false,
        "stockState": "unknown",
        "promotions": [],
        "imageUrl": "https://assets.woolworthsstatic.co.za/Fresh-Full-Cream-Milk-2-L-20011697.jpg?V=Q83t&o=eyJidWNrZXQiOiJ3dy1vbmxpbmUtaW1hZ2UtcmVzaXplIiwia2V5IjoiaW1hZ2VzL2VsYXN0aWNlcmEvcHJvZHVjdHMvaGVyby8yMDIzLTA5LTIwLzIwMDExNjk3X2hlcm8uanBnIn0&",
        "url": "https://www.woolworths.co.za/prod/Food/Milk-Dairy-Eggs/Milk/Fresh-Full-Cream-Milk-2-L/_/A-20011697"
      }
    ],
    "makro": [
      {
        "store": "makro",
        "storeName": "Makro",
        "productId": "MLKHFXJTMV3AMYRY",
        "name": "Clover Full Cream Long Life Milk, Plain Flavour 6 x 1 L",
        "price": 97.95,
        "priceFormatted": "R97.95",
        "oldPrice": null,
        "oldPriceFormatted": null,
        "inStock": true,
        "promotions": [],
        "imageUrl": "https://www.makro.co.za/asset/rukmini/fccp/400/400/ng-fkpublic-ui-user-fbbe/milk/2/u/l/-original-imah9zzrfjzgwnme.jpeg?q=80",
        "url": "https://www.makro.co.za/clover-full-cream-long-life-milk-plain-flavour/p/itma7f0b28c4e120?pid=MLKHFXJTMV3AMYRY"
      }
    ]
  },
  "errors": {}
}

Interactive demo

Every field, on screen

Switch endpoints, change the query, store and limit, and see exactly what comes back: the rendered result with every field labelled, next to the raw JSON. The data is a real catalogue snapshot with product photos and retailer logos; the comparison runs on the same matching engine as the live API.

  • Was-price and promotions

    oldPrice, oldPriceFormatted and promotions[] on every product.

  • Three-state stock

    stockState is in_stock, out_of_stock or unknown, so a missing signal is never guessed.

  • Honest comparison

    Only confirmed in-stock offers set cheapestStores and saving. Unpaired products are returned, not hidden.

  • Partial results

    If one retailer fails the rest still return, and errors tells you which one and why.

GET/api/v1/grocery/compare?q=koo baked beans 410g&limit=3

200 OKX-AZL-RateLimit-Remaining: 247

query koo baked beans 410g · matches 2

Koo Baked Beans in Tomato Sauce 400 g

size 400g

cheapestStores Pick n Pay

saving R1.00

Koo Baked Beans In Tomato Sauce 400g
Pick n Payin_stockcheapest

Koo Baked Beans In Tomato Sauce 400g

productId 000000000000967788_EA · storeName Pick n Pay Claremont

R16.99

price 16.99 · inStock true

KOO Baked Beans in Tomato Sauce 400g
Checkersin_stock

KOO Baked Beans in Tomato Sauce 400g

productId 5d3af641f434cf8420738055 · storeName Checkers Sixty60

R17.99

price 17.99 · inStock true

Koo Baked Beans in Tomato Sauce 400 g
Woolworthsunknownexcluded from cheapest · stock not confirmed

productId 6009522310363 · storeName Woolworths

R17.99

price 17.99 · inStock false

Koo Baked Beans in Tomato Sauce 215 g

size 215g

cheapestStores Checkers

saving null

KOO Baked Beans in Tomato Sauce 215g
Checkersin_stockcheapest

KOO Baked Beans in Tomato Sauce 215g

productId 5fd79c16d8f8b5818644788b · storeName Checkers Sixty60

R14.99

price 14.99 · inStock true

Koo Baked Beans in Tomato Sauce 215 g
Woolworthsunknownexcluded from cheapest · stock not confirmed

productId 6009522306120 · storeName Woolworths

R15.99

price 15.99 · inStock false

Offer thumbnails come from the matching product in /search; compare offers themselves do not carry imageUrl.

unmatched

Products that could not be confidently paired across stores (different pack size, brand or form) come back grouped by store, in full, rather than being force-matched.

Pick n Payunmatched.pnp
Checkersunmatched.checkers
Pot O' Gold Baked Beans In Tomato Sauce 410g
Checkers

Pot O' Gold Baked Beans In Tomato Sauce 410g

5d3af641f434cf842073804d

R15.99

in_stockurl: null
Buy 2 For R29
Woolworthsunmatched.woolworths

errors: {} — every store answered

API reference

Response fields, errors and headers

All prices are in ZAR. Responses are live and never cached. This is public catalogue data only, never personal purchase history.

GET /api/v1/grocery/search?q={query}&store={slug|all}&limit={1-20}

Live catalogue search. Stores are queried in parallel, and one store failing does not fail the request.

Response

FieldTypeDescription
querystringThe trimmed search term.
storesstring[]Retailer slugs that were queried.
productsGroceryProduct[]Results from every queried store (see Product below).
errorsRecord<string, string>Per-store failure messages, keyed by slug. Empty when every store answered.

Product

FieldTypeDescription
storestringRetailer slug: "pnp", "checkers", "woolworths" or "makro".
storeNamestringRetailer display name, e.g. "Pick n Pay".
productIdstringProduct identity as the retailer uses it (barcode or catalogue code). Pass it to /products.
namestringProduct name including pack size.
pricenumber | nullCurrent price in ZAR, or null when the retailer did not expose one.
priceFormattedstringDisplay price such as "R18.99". Empty string when price is null.
oldPricenumber | nullPre-promotion price when the retailer exposes one.
oldPriceFormattedstring | nullDisplay form of oldPrice.
inStockbooleanCompatibility flag. True only when stock is confirmed available.
stockState"in_stock" | "out_of_stock" | "unknown"Preferred stock signal. May be absent on older clients; fall back to inStock. "unknown" is never inferred from a price (Woolworths exposes price, not stock).
promotionsstring[]Short promotion labels, e.g. "Buy 2 For R42". Empty array when none.
imageUrlstring | nullProduct image URL when the retailer provides one.
urlstring | nullDeep link to the retailer product page, when available.

Error codes

Errors use one shape: { "error": { "code", "message" } }

  • 400
    missing_query

    The "q" parameter is empty or absent (search, compare).

  • 400
    missing_parameter

    The "id" parameter is missing (products).

  • 400
    invalid_store

    store must be "pnp", "checkers", "woolworths", "makro" or "all" (search only).

  • 401
    invalid_api_key

    The bearer key is missing, malformed or revoked.

  • 403
    product_access_required

    The key's account does not have the Grocery Data API enabled.

  • 404
    not_found

    No product with that id at that store (products).

  • 429
    daily_limit_reached

    The key used its daily allowance; it resets at 00:00 UTC.

  • 502
    upstream_error

    The retailer catalogue failed (products). Search and compare report this per store in errors instead.

Response headers

  • X-AZL-RateLimit-Limit

    Daily request allowance for the key.

  • X-AZL-RateLimit-Remaining

    Requests left today, including on 429 responses.

  • X-AZL-Quota-Remaining

    Same remaining count, returned on successful search, compare and products calls.

  • Cache-Control: no-store

    Every response is live; do not cache it.

Overview

What is Grocery Data API?

Compare current prices across four South African retailers. Use the API in your own tools, or open the AZ Labs Groceries workspace to chat, plan a basket and review your shopping history. Our team works with you to map the highest-value workflow, shape the business rules, connect the right systems, and launch a solution that can be measured against real outcomes from day one.

schedule

24/7 Availability

Always-on service

savings

90% Cost Reduction

Compared to manual

rocket_launch

Setup in 2 Weeks

Rapid deployment

Commercial outcomes

What this usually improves

4 live
Stores covered
JSON
Response format
One key
Auth

Capabilities

Key capabilities

storefront

Four retailers, one query

Search Pick n Pay, Checkers, Woolworths and Makro together. Comparisons match product identity and pack size, with prices and availability kept visible.

currency_exchange

Live ZAR Pricing

Current shelf prices, promotions, and pre-promotion reference prices in South African Rand, refreshed from the live storefront catalogues.

inventory_2

Stock Awareness

Availability can be confirmed or unknown. Woolworths catalogue pricing does not prove local or Dash stock, and delivery availability must be checked for your address.

straighten

Size-Normalized Matching

Units such as 0.5L and 500ml are normalized before matching. Brands, flavours and pack counts stay separate so different products do not become claimed savings.

key

One Key, Same Dashboard

Uses the same sk-azl-live- API keys as the AI Gateway. Generate a key from your dashboard and point any HTTP client at the endpoint.

code

Plain REST + JSON

No SDK required. GET endpoints return clean JSON you can consume from any language, including AI agents and serverless functions.

Applications

Use cases

compare_arrows

Price Comparison Apps

Build a shopping app or site that shows users which store has the best price for every item, with live stock confidence.

smart_toy

AI Shopping Agents

Give an agent a tool that checks real prices before it answers “where should I buy this?” — grounded in live data, not guesses.

bar_chart

Market & Spend Research

Track catalogue prices over time for budgeting tools, inflation analysis, or internal purchasing decisions.

Integrations

Common system touchpoints

cURLPythonNode.jsOpenAI SDK toolsAny HTTP client

Our Process

How it works

forum1

Consultation

Understand your goals and requirements

design_services2

Design

Architect the optimal solution

code3

Development

Build and test your AI solution

rocket_launch4

Launch

Deploy, monitor, and optimize

Frequently asked questions

Which stores does the Grocery API cover?

Live catalogue data for Pick n Pay, Checkers (Sixty60), Woolworths, and Makro with regional and national coverage.

Is this real-time data?

Each request queries the live storefront catalogues at call time. Prices, promotions and stock reflect what the stores are showing right now.

How is this different from Open Food Facts?

Open Food Facts covers barcode nutrition data with crowd-submitted prices. This API delivers verified live ZAR shelf prices, stock flags and promotions across four South African supermarket chains, with size-normalized comparison.

Do I need a card to try it?

No. The free tier includes a daily request allowance per key with no card required, and the same dashboard you already use for the AI Gateway.

Can I use it from an AI agent?

Yes. The endpoints return plain JSON and can be registered as a tool in OpenAI-compatible tool calling, LangChain, or any agent framework.

Ready to get started?

Book a free consultation to discuss how grocery data api can transform your business operations.