BasketWatch

A freshness snapshot per supermarket: products tracked, products on promotion, the last collection date and the status of the most recent run.

Search products by name across one or all Irish supermarkets. Args: query: words to match in product names, case-insensitive (e.g. "heinz baked beans", "kerrygold butter", "pringles"). store: optionally filter to one of "aldi", "tesco", "supervalu", "dunnes". Leave it out to search all four. limit: how many results to return in total (default 10

Find where a product is cheapest right now. Matches the same product at Aldi, Tesco, SuperValu and Dunnes Stores and returns each store's current price side by side, with unit prices, offers and Tesco Clubcard prices. Free: no BasketWatch account needed. Args: query: the product, e.g. "heinz ketchup" or "kerrygold butter 454g". limit: how many matched products to r

Raw per-store search results for a product name at all four supermarkets: every matching line at each store, including other pack sizes, without matching the same product across stores. Returns a dict keyed by store, with up to `limit_per_store` matching products per store. Args: query: product-name substring (e.g. "heinz baked beans 415g"). limit_per_store: how ma

Find the products carrying one or more barcodes (GTIN, EAN or UPC) across all four Irish supermarkets in one call. Codes are accepted exactly as printed: leading zeros, spaces and hyphens are ignored. Needs a signed-in BasketWatch account. Args: codes: one barcode, or up to 100 separated by commas (e.g. "5000127014084" or "5000127014084,5000157024671").

List products currently on promotion at a given supermarket. Returns offer label (e.g. "3 for €5", "SAVE €0.75"), was-price, validity window, and where applicable Tesco Clubcard prices, SuperValu Real Rewards prices or Dunnes member offers. Args: store: one of "tesco", "supervalu", "dunnes". (Aldi doesn't publish multibuy promos so isn't supported here.)

Price movements at one supermarket between the latest nightly snapshot and the previous one: shelf price rises and falls with old price, new price and % change, and promotions starting or ending listed separately (an offer ending is not a price rise). Args: store: "aldi" | "tesco" | "supervalu" | "dunnes". limit: how many movers to return (default 25).

Products newly listed at a supermarket within a configurable lookback window: range additions and new launches. Args: store: "aldi" | "tesco" | "supervalu" | "dunnes". days_back: how many days back to look (default 7 = since last scrape). limit: how many new products to return.

Products that have disappeared from a supermarket's catalogue in the given lookback window: delistings and range cuts. Args: store: "aldi" | "tesco" | "supervalu" | "dunnes". days_back: how many days back to consider (default 7). limit: how many removed products to return.

Page through a supermarket's full catalogue, with no search terms or filters. Args: store: "aldi" | "tesco" | "supervalu" | "dunnes". limit: page size (default 100, max 200). offset: pagination offset.

A product's recorded daily prices over a date range. BasketWatch has kept every night's price at all four supermarkets since May 2026, and, with with_nutrition_and_ingredients, each day's nutrition per 100g or 100ml and ingredients list as the retailer's own data stated them, kept since 16 October 2026: for questions like "has the sugar in Frosties changed". Takes product ids

Nutrition per 100g or 100ml (energy, fat, carbohydrate, sugars, protein, salt), the ingredients list as printed (allergens included), how many ingredients it lists, country of origin, alcohol strength, pack size, description and today's price, for particular products. Products are looked up by product id (store-prefixed, as returned in product results), by the retailer's own i

Find products that meet ingredient, nutrition, alcohol or offer conditions, optionally sorted. For questions like "biscuits without palm oil", "nut-free snacks at Tesco", "vegan chocolate", "cereal with the least sugar", "high protein yoghurt", "bread with the fewest ingredients", "alcohol-free beer", "low salt soup" or "cheapest olive oil at Aldi". Every product comes with its

Price a whole shopping list, or every line of a grocery receipt (up to 100 lines in one call), at Aldi, Tesco, SuperValu and Dunnes Stores: each item matched to the same product at every store, the cheapest store for each item, each store's basket total, and a cheaper product of the same kind (often own-label) where one exists. Each line takes name (plain words with brand and

How the cost of the same basket changed between two dates, at the store it was bought from: each product's price on both dates, whether it was on promotion, the basket total on each date, and the products that moved it. BasketWatch has recorded every product's price every night since May 2026. Up to 100 lines per call; each line takes name, sku (the retailer's printed item numb

How a whole category's prices moved between two dates, in one call: the biggest regular-price rises and falls, promotions starting and ending, Tesco Clubcard price changes and pack-size changes, kept apart, with a summary over every product compared (average and median shelf change, counts of rises and falls) overall and per store. shelf_rise and shelf_fall are changes to the

How many BasketWatch credits the signed-in account has left, and when they expire. Free to call. One credit is one record returned.