BasketWatch

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

Takes no parameters.

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", "lidl". Leave it out to search all five. limit: how many results to return in total (default 10). Returns the matching product rows: store, SKU id, name, brand, price, unit_price (€/kg or €/L), pack_size, category_path, url. Matches on the name only: no ingredient, nutrition or offer filters, and no price sorting.

Find where a product is cheapest right now. Matches the same product at Aldi, Tesco, SuperValu, Dunnes Stores and Lidl and returns each store's current price side by side, with unit prices, offers and member prices (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus). To list the products most stores stock, leave out query and set min_stores, e.g. min_stores=5 for every product matched at all five. Free: no BasketWatch account needed. Args: query: the product, e.g. "heinz ketchup" or "kerrygold butter 454g". Optional when min_stores is given. limit: how many matched products to return (default 5, max 50). min_stores: only products matched at at least this many stores, 2 to 5, with or without query. Returns {"as_of", "query", "matches": [{"product", "pack", "prices": {store: {name, price, unit_price, unit_basis, offer_text, was_price, clubcard_price, url}}, "cheapest_store"}]}. A store missing from "prices" does not stock that product.

Raw per-store search results for a product name at all five 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 many matches per store (default 5).

Find the products carrying one or more barcodes (GTIN, EAN or UPC) at Aldi, Tesco, SuperValu, Dunnes Stores and Lidl 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"). store: optionally restrict to one of "aldi", "tesco", "supervalu", "dunnes" or "lidl". Use "lidl" for retailer-local Lidl codes. include_copy: also return ingredients and per-100g nutrition where the retailer publishes them. lidl_store_id: optionally select an Irish Lidl store such as "IE0239"; prices and store observations then refer to that store. Returns {"products": [...], "not_found": [...], "invalid": [...]}. Each product row carries store, matched_barcodes, name, brand, pack_size, price and its full barcodes list. One credit per barcode found, however many retailers stock it; codes with no match cost nothing. Lidl results not linked to a catalogue product have id=null, catalog_linked=false and dated store observations; ingredients, pack size and nutrition are not inferred.

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, Dunnes member offers or Lidl Plus prices (scan the Lidl Plus app at the till). Args: store: one of "tesco", "supervalu", "dunnes", "lidl". (Aldi doesn't publish multibuy promos so isn't supported here.) limit: how many promotional rows to return (default 25).

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" | "lidl". 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" | "lidl". 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" | "lidl". 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" | "lidl". 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 Aldi, Tesco, SuperValu and Dunnes Stores since May 2026 and at Lidl since 17 October 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 (as returned in product results; an Aldi id has no store prefix, and "aldi:" in front of one is accepted) or a query; with a query, the closest matching products are looked up first. A range returns one row per product per day, and each row costs one credit; with from_date equal to to_date, one day's price is returned. Every product gets the same days. When products x days would pass the row limit, the range is shortened to its most recent days for all of them and note says so; ids with no price in the range are listed in not_found. Args: product_ids: e.g. ["tesco:300793546", "dunnes:100873410", "000000000000387044"], up to 50; each id's store is taken from it. query: product name words, used when no product_ids are given. store: aldi, tesco, supervalu, dunnes or lidl, to narrow a query. Leave it out to look in all five. from_date: first day, YYYY-MM-DD. Defaults to 30 days before to_date. to_date: last day, YYYY-MM-DD. Defaults to today. limit: most rows to return in total (default and maximum 200). with_nutrition_and_ingredients: true adds nutrition_per_100 to every row and the ingredients list on each product's first day and on any day it changed. Days before 16 October 2026 have none. Returns rows (id, name, store, scrape_date, price, unit_price, unit_basis, clubcard_price, offer_text, was_price), the days covered, not_found, note.

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 item numbers (skus with store, as printed on its receipts), or by name (query). ingredients_incomplete marks an ingredient list on record that is cut short, which cannot show that an ingredient is absent. Results carry a note that nutrition and ingredients are for information only. Each product returned costs one credit. Args: query: product name words, e.g. "kellogg's corn flakes". product_ids: e.g. ["tesco:300793546", "dunnes:100873410"], up to 50. skus: the store's own item numbers, e.g. ["100873410"], up to 50; needs store. An Aldi article number can return several variants. store: aldi, tesco, supervalu, dunnes or lidl: required with skus, narrows a query; leave out for all five. limit: most products to return for a query (default 5, max 50).

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 nutrition, ingredients, ingredient count, country of origin where stated and today's price. Fibre and saturated fat are not recorded. Ingredient words. exclude_ingredients are ingredients a product is free of; include_ingredients ones it contains. These words are expanded to the label terms they cover: palm oil, nuts (includes peanuts), peanuts, gluten, milk (dairy), eggs, soya, sesame, mustard, celery, fish, crustaceans, molluscs, shellfish, sulphites, lupin, gelatine, alcohol, added sugar, sweeteners, pork, meat, vegetarian (meat, fish, gelatine and other animal-derived ingredients) and vegan (vegetarian plus milk, eggs, honey and other animal products). Any other word is matched as written, e.g. "coconut" or "oats". With no store, results alternate across the stores (each store's best match, then each store's next), and matched_by_store gives each store's full count. A product whose ingredient list or nutrition is not on record, or whose ingredient list on record is incomplete, is left out, never assumed to pass: left_out_unknown counts them, left_out_by_reason gives the reasons, and caveats lists known gaps (Aldi's own ingredient lists are often cut short, so an Aldi product is offered as free from something only when its full list comes from the same barcode at Tesco, SuperValu or Dunnes). Claims printed in a product's NAME, such as "gluten free", "lactose free", "alcohol free" or "vegan", are matched through query; exclude_ingredients also checks the ingredients. Alcohol st

Price a whole shopping list, or every line of a grocery receipt (up to 100 lines in one call), at Aldi, Tesco, SuperValu, Dunnes Stores and Lidl: 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 size, e.g. "avonmore fresh milk 2l"; receipt abbreviations such as "AVNMR FRSH MLK 2L" match poorly) and optionally sku (the retailer's item number as printed on its receipts; the name is used when the number is not found), barcode, store, quantity, and paid (the line total, which gives the saving against what was paid). Irish product names say "low fat milk" for what the UK calls "semi skimmed". Bags, deposits, discounts and totals are not products. Returns, per line, the match and matched_by (sku, barcode or name), the cheapest store and price, a cheaper alternative with its pack size and, for a receipt, price_at_store_bought; then each store's total with its items_missing, cheapest_complete_store, mix_and_match_total and not_found. Prices are each retailer's online shelf price from the overnight collection; in-store prices can differ. Member prices (Tesco Clubcard, Lidl Plus) are reported separately. Each matched item costs one credit; items not found are free. Args: items: e.g. [{"sku": "100685955", "name": "dunnes baked beans", "quantity": 2, "paid": 1.30}, {"name": "brennans wholemeal bread"}]. store: the receipt's supermarket (aldi, tesco, supervalu, dunnes or lidl), used for any line that does not name its own.

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 (Lidl's since 17 October 2026). Up to 100 lines per call; each line takes name, sku (the retailer's printed item number, with the line's words in name), barcode, store and quantity. change_pct is the change in what the basket cost (promotions included); shelf_change_pct is regular prices only, so the gap between the two is promotions starting or ending, not price rises. biggest_rises and biggest_falls list the lines that moved most; pack_changed marks a product whose pack size changed, confirmed over three days of records (a smaller pack at the same price is a hidden rise). Lines in not_compared were not found, or not sold on one of the dates. Each product compared costs one credit. Args: items: e.g. [{"sku": "100858349", "quantity": 2}, {"name": "brennans wholemeal bread"}]. from_date: the earlier date, YYYY-MM-DD, e.g. "2026-08-06". to_date: the later date, YYYY-MM-DD; defaults to today. store: the receipt's supermarket (aldi, tesco, supervalu, dunnes or lidl).

How a whole category's prices moved between two dates, in one call: the biggest regular-price rises and falls, promotions starting and ending, member price changes (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus) 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 regular price; promotion_started and promotion_ended are changes in what was paid while the regular price stayed the same (a product at 18 euro on promotion and 23 euro after is a promotion ending, not a 27.8% price rise); loyalty_change is a member price moving; pack_change is the same product in a different pack size, confirmed over three days of records (a smaller pack at the same price is a hidden rise); was_price_change is an offer running at both dates while only its "was" price moved, kept out of the shelf figures because nobody paid it. Averages are geometric, so a half-price offer starting and ending cancel out; average_member_paid_change_pct uses member prices where they apply. Each mover returned costs one credit; the summaries are free. Args: from_date: the earlier date, YYYY-MM-DD (prices recorded since May 2026). to_date: the later date, YYYY-MM-DD; defaults to today. group: a kind of product: beer, cider, wine, spirits, alcohol, or any product type such as breakfast cereal, butter, coffee, crisps, nappies. Narrower words work too ("vodka", "red wine"). query: product or brand words, with or without group (e.g. "guinness"). category: an aisle name to narrow by. store: aldi, tesco, supervalu, dunnes or lidl; leave out for all five. kinds: which lists to return (default all seven). rank_by: "pct" (default) or "eur". limit: most products per list (default 10, m

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

Takes no parameters.