API Reference — BasketWatch Irish Grocery Price API

Authentication

Send your key on every request as an X-API-Key header (preferred) or an ?api_key= query parameter. Keys are issued per subscriber on the €199/month API plan. Keep yours private.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/products?limit=5"

No key, capped sample. Unauthenticated requests return the first 50 rows so you can evaluate the data shape; a valid key returns the full set.

Conventions

One path shape: per store. Every dataset is /api/{store}/<dataset>, where {store} is aldi, tesco, supervalu or dunnes — the same path shape for all four. A few datasets are specific to one retailer (promotions and out-of-stock, specialbuys); these are flagged on the cards below.
CSV. Append .csv to any dataset for a CSV download (e.g. /api/dunnes/products.csv), ready for Excel, Power Query or pandas.
Snapshot date. Every response includes scrape_date (the nightly snapshot the values come from).
Money. Prices are euro decimals; unit_price is per kg or per litre with unit_basis naming the unit.
Pagination. limit + offset page large results; q free-text filters name/brand; on=YYYY-MM-DD targets a snapshot day where supported.

Stores: alditescosupervaludunnes

Catalogue & search

GET /api/{store}/products

Full catalogue with the current shelf price per SKU. Add ?q= to filter, ?limit=&offset= to page.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/products?limit=1"

Response

[
  {
    "id": "tesco:320395135",
    "name": "Biona Organic Rye Sesame Crispbread 200g",
    "brand": "BIONA",
    "category_path": "Food Cupboard > Crackers, Rice Cakes & Breadsticks",
    "url": "https://www.tesco.ie/shop/en-IE/products/320395135",
    "pack_size": "200g",
    "first_seen": "2026-05-27",
    "last_seen": "2026-06-29",
    "scrape_date": "2026-06-29",
    "price": 2.75,
    "unit_price": 13.75,
    "unit_basis": "1 KG",
    "clubcard_price": null,
    "offer_text": null,
    "available": 1,
    "removed": 0
  }
]

GET /api/{store}/products/count

Fast catalogue size for a store, without returning rows.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/dunnes/products/count"

Response

{ "total": 15069 }

GET /api/product/{product_id}

A single product: current price, unit price, pack, plus its full price history.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/product/tesco:320395135"

Response

{
  "product": {
    "id": "tesco:320395135",
    "name": "Biona Organic Rye Sesame Crispbread 200g",
    "brand": "BIONA",
    "url": "https://www.tesco.ie/shop/en-IE/products/320395135",
    "image_url": "https://digitalcontent.api.tesco.com/v2/media/ghs/.../1014470272.jpeg",
    "category_path": "Food Cupboard > Crackers, Rice Cakes & Breadsticks",
    "pack_size": "200g",
    "pack_qty": 200.0,
    "pack_unit": "G",
    "first_seen": "2026-05-27",
    "last_seen": "2026-06-29",
    "description": "Organic Rye Sesame Crispbread"
  },
  "history": [
    { "scrape_date": "2026-05-27", "price": 2.79 },
    { "scrape_date": "2026-06-29", "price": 2.75 }
  ]
}

GET /api/compare?q={query}

Cross-retailer comparison: each matched product with its price and unit price in every store that stocks it, plus how many stores it spans (coverage).

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/compare?q=heinz%20ketchup"

Response

{
  "as_of": "2026-06-29",
  "matches": [
    {
      "match_id": 561961,
      "brand": "Heinz",
      "pack": "910g",
      "category": "Food Cupboard",
      "display_name": "Heinz Tomato Ketchup 910g",
      "coverage": 4,
      "stores": {
        "aldi": {
          "id": "000000000000336799",
          "name": "Tomato Ketchup 910g",
          "price": 3.99,
          "unit_price": 4.38,
          "unit_basis": "1 KG",
          "was_price": null,
          "clubcard_price": null,
          "scrape_date": "2026-06-29"
        },
        "tesco": {
          "id": "tesco:254722768",
          "name": "Heinz Top Down Squeezy Tomato Ketchup 910g",
          "price": 5.50,
          "unit_price": 6.04,
          "unit_basis": "1 KG",
          "was_price": null,
          "clubcard_price": 4.50,
          "scrape_date": "2026-06-29"
        },
        "supervalu": {
          "id": "supervalu:1003041000",
          "name": "Heinz Tomato Ketchup (910 g)",
          "price": 5.50,
          "unit_price": 6.04,
          "unit_basis": "1 KG",
          "was_price": null,
          "clubcard_price": null,
          "scrape_date": "2026-06-29"
        },
        "dunnes": {
          "id": "dunnes:100684285",
          "name": "Heinz Tomato Ketchup 910g",
          "price": 5.50,
          "unit_price": 6.04,
          "unit_basis": "1 KG",
          "was_price": null,
          "clubcard_price": null,
          "scrape_date": "2026-06-29"
        }
      }
    }
  ]
}

GET /api/aldi/specialbuys

Aldi Specialbuys, the rotating middle-aisle range: active lines grouped by category, plus recently ended and newly listed buys. Aldi-only.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/aldi/specialbuys?limit=1"

Response

{
  "active_by_category": [
    { "category_path": "SpecialBuys > Clothing", "count": 54, "avg_price": 6.63 }
  ],
  "recently_ended": [
    { "id": "000000000708833001", "name": "Bottle with Carabiner", "brand": "CROFTON", "category_path": "SpecialBuys > Kitchen", "last_seen": "2026-06-26", "last_price": 3.99 }
  ],
  "newly_listed": [
    { "id": "000000000738367001", "name": "Adult Fiction", "brand": "HACHETTE", "category_path": "SpecialBuys > Hobbies and Crafts", "first_seen": "2026-06-28", "launch_price": 3.99 }
  ]
}

Changes & lifecycle

GET /api/{store}/changes

Day-over-day movements in three separate buckets: shelf-price increases / decreases, promotion changes (started / ended / changed), and loyalty-price changes. The loyalty bucket (clubcard_changes) reflects each retailer's own scheme — Tesco Clubcard, SuperValu Real Rewards; Dunnes and Aldi have no loyalty pricing, so it stays empty. Each response covers a single retailer (the example below is Tesco). Accepts ?on=YYYY-MM-DD.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/changes"

Response

{
  "date": "2026-06-29",
  "prev_date": "2026-06-28",
  "shelf_increases": [
    {
      "id": "tesco:254656789",
      "name": "Flora Original Spread 500g",
      "brand": "FLORA",
      "category_path": "Fresh Food > Butter, Spreads & Margarine",
      "url": "https://www.tesco.ie/shop/en-IE/products/254656789",
      "pack_size": "500g",
      "prev_price": 2.50,
      "price_now": 2.75,
      "delta": 0.25,
      "pct": 10.0,
      "promo": null
    }
  ],
  "shelf_decreases": [],
  "promotions": [
    {
      "id": "tesco:317990690",
      "name": "Cuisine de France Lye Pretzel 85g",
      "brand": "CUISINE DE FRANCE",
      "kind": "started",
      "offer_now": "Any 3 for €3 Clubcard Price",
      "was_price": null,
      "shelf_price": 1.75
    }
  ],
  "clubcard_changes": [
    {
      "id": "tesco:313603753",
      "name": "Garnier Ambre Solaire Bronze Oil 150ml",
      "brand": "GARNIER",
      "kind": "added",
      "clubcard_now": 8.50,
      "clubcard_prev": null,
      "shelf_price": 17.00,
      "offer_text": "€8.50 Half Price Clubcard Price"
    }
  ]
}

GET /api/{store}/new-products

Newly listed SKUs first seen in the latest snapshot.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/new-products"

Response

[
  { "id": "tesco:324436415", "name": "Adams Polishes Detail Spray 473ml", "brand": "ADAM'S POLISHES", "category_path": "Home & Living > DIY & Car Care", "first_seen": "2026-06-29", "launch_price": 13.00 }
]

GET /api/{store}/removed

Delisted SKUs absent from the latest snapshot (two-snapshot confirmed).

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/dunnes/removed"

Response

[
  { "id": "dunnes:100221987", "name": "Dunnes My Family Fabric Conditioner 3L", "brand": "Dunnes Stores", "category_path": "Dunnes > Household & Cleaning > Laundry", "first_seen": "2026-05-30", "last_seen": "2026-06-27", "last_price": 3.50 }
]

GET /api/tesco/out-of-stock

Present-but-unavailable lines (the retailer's availability flag), distinct from removed. Tesco only — Tesco's catalogue exposes a per-SKU availability flag; the other retailers don't.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/out-of-stock"

Response

{
  "date": "2026-06-29",
  "count": 882,
  "items": [
    { "id": "tesco:317208754", "name": "Sheep Hill Sauvignon Blanc 75cl", "brand": "A GABB FAMILY WINE", "category_path": "Drinks > Wine", "url": "https://www.tesco.ie/shop/en-IE/products/317208754", "pack_size": "75cl", "price": 18.00, "clubcard_price": 9.00 }
  ]
}

GET /api/{store}/shrinkflation

Pack-size reductions: same product, smaller pack, with the old and new size and the effective unit-price change. Returns an empty array until a pack-size reduction is detected; the example below shows the shape.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/shrinkflation"

Response

[
  {
    "id": "tesco:250114433",
    "name": "Cadbury Dairy Milk",
    "brand": "CADBURY",
    "category_path": "Food Cupboard > Confectionery",
    "pack_size": "180g",
    "start_date": "2026-04-01",
    "end_date": "2026-06-29",
    "start_price": 2.50,
    "end_price": 2.50,
    "start_pack_qty": 200.0,
    "start_pack_unit": "G",
    "end_pack_qty": 180.0,
    "end_pack_unit": "G",
    "pack_shrink_pct": 10.0,
    "start_unit_price": 12.50,
    "end_unit_price": 13.89,
    "unit_basis": "1 KG",
    "unit_price_pct": 11.1,
    "headline_pct": 11.1
  }
]

GET /api/{store}/volatile

Most volatile SKUs: products whose price has changed most often over the tracked window.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/supervalu/volatile"

Response

[
  { "id": "supervalu:1500119003", "name": "Coca-Cola 1.75L", "brand": "Coca-Cola", "category_path": "Drinks > Minerals", "distinct_prices": 4, "observations": 24, "min_price": 1.85, "max_price": 2.95, "avg_price": 2.31, "range_pct": 59.5 }
]

Promotions

GET /api/{store}/promotions

Live deals: products on offer, with was-price, offer text and loyalty pricing (Clubcard / Real Rewards). Not available for Aldi (everyday-low-price).

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/dunnes/promotions"

Response

[
  {
    "id": "dunnes:100827389",
    "name": "Vanish Oxi Action Stain Remover Spray 500ml",
    "brand": "Vanish",
    "category_path": "Dunnes > Household & Cleaning > Laundry",
    "url": "https://www.dunnesstoresgrocery.com/sm/delivery/rsid/520/product/100827389",
    "pack_size": "500ml",
    "last_seen": "2026-06-29",
    "scrape_date": "2026-06-29",
    "price": 5.00,
    "unit_price": 10.00,
    "unit_basis": "1 L",
    "offer_text": "SAVE €2.50",
    "was_price": 7.50,
    "offer_valid": "2026-06-16 23:00:00Z - 2026-07-21 22:59:59Z",
    "clubcard_price": null
  }
]

Analytics

GET /api/{store}/kpis

Headline numbers for the latest snapshot: catalogue size, active SKUs today vs yesterday, promotion share, out-of-stock count, average price, price moves and new lines.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/kpis"

Response

{
  "total_products": 21056,
  "active_today": 20518,
  "active_yesterday": 20473,
  "active_delta": 45,
  "on_promo_today": 7473,
  "promo_pct_today": 36.4,
  "out_of_stock_today": 882,
  "avg_price_today": 7.28,
  "avg_price_yesterday": 7.26,
  "prices_up_today": 0,
  "prices_down_today": 0,
  "new_today": 29
}

GET /api/{store}/category-index

Per-category average price over time, with the SKU count behind each point — the series behind the dashboard graphs.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/category-index"

Response

{
  "Food Cupboard": [
    { "date": "2026-05-27", "avg_price": 3.51, "n": 4333 },
    { "date": "2026-06-29", "avg_price": 3.52, "n": 4385 }
  ],
  "Drinks": [
    { "date": "2026-05-27", "avg_price": 11.17, "n": 1452 }
  ]
}

GET /api/{store}/category-summary

Per-department roll-up: SKU count, average price and price churn, with the retailer browse URL.

Request

curl -H "X-API-Key: YOUR_KEY" \
  "https://basketwatchireland.com/api/tesco/category-summary"

Response

[
  { "category": "Food Cupboard", "sku_count": 4385, "avg_price": 3.52, "changed": 0, "changed_pct": 0.0, "price_delta_pct": 0.0, "url": "https://www.tesco.ie/shop/en-IE/browse/food-cupboard/all" }
]

Errors, limits & freshness

Status	Meaning
`200`	OK. JSON body (or CSV for `.csv` paths).
`401`	Missing or invalid key on an endpoint that requires one.
`404`	Unknown store, dataset or product id.
`429`	Rate limit exceeded — back off and retry.

Freshness. Data refreshes nightly across all four retailers; every response carries scrape_date so you always know the snapshot you are reading.

Beyond the API

Need historical back-catalogue, scheduled bulk CSV exports, or a natural-language / agent interface? An Agent & MCP endpoint is available, and bespoke historical pulls are available on request. Talk to us — or get an API key to start.