BasketWatch

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.

list_products

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 many matches per store (default 5).

compare_price_across_stores

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.) limit: how many promotional rows to return (default 25).

get_promotions

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

status

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.

removed_products

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 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 ingredient lists are often cut short, so Aldi products are not offered as free from anything). 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 strength is recorded for most SuperValu and Dunnes drinks but few at Tesco and Aldi; "alcohol free" and "0.0" in query match drinks named that way. Answers come from the ingredient lists and nutrition the retailers publish. "Free from" means none of the listed ingredients names it; not every "may contain" warning is covered. Results carry a note that this is information only. Each product returned costs one credit. Args: query: product words, e.g. "biscuits", "crisps", "dark chocolate". Needed unless category is given. store: aldi, tesco, supervalu or dunnes. Leave out to search all four. category: an aisle name to narrow by, e.g. "Breakfast Cereals". exclude_ingredients: ingredients a product has to be free of, e.g. ["palm oil"], ["nuts", "sesame"], ["vegan"]. include_ingredients: e.g. ["oats"]. max_sugar_g, max_salt_g, max_fat_g, max_carbs_g, min_protein_g: grams per 100g or 100ml, e.g. max_sugar_g=5. max_kcal: kilocalories per 100g or 100ml. max_abv, min_abv: alcohol by volume, percent. max_ingredients: at most this many listed ingredients, e.g. 5. A compound ingredient's own bracketed list counts as one. on_offer: only products on promotion or with a Clubcard price. sort_by: price, unit_price (per kg or litre), sugar, salt, fat, carbs, protein, kcal, abv or ingredients (fewest first). Products that are the kind of thing searched for rank ahead of name-only matches (name_match_only), so "chocolate" sorted by price does not lead with chocolate-flavour popcorn. descending: true for highest first, e.g. most protein. limit: most products to return (default 10, max 50).

find_products

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"). store: optionally restrict to one of "aldi", "tesco", "supervalu", "dunnes". include_copy: also return ingredients and per-100g nutrition where the retailer publishes them. 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.

lookup_barcode

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.

newly_added_products

Nutrition per 100g or 100ml (energy, fat, carbohydrate, sugars, protein, salt), the ingredients list as printed (allergens included), how many ingredients it lists, 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 or dunnes: required with skus, narrows a query; leave out for all four. limit: most products to return for a query (default 5, max 50).

get_product_details

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 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. Tesco Clubcard prices 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 or dunnes), used for any line that does not name its own.

price_basket