BasketWatch

The biggest saving comes first, against the usual price or the price it
typically sold at, whichever is less, so a product that is usually on
offer does not lead. By that saving, the shops take turns among deals
that save alike, so one shop does not fill the top of the list, and no
deal comes ahead of one that saves more than twice as much. Every
promotion on sale is judged, so this covers them all, and offset reaches
every deal. Covers food, drinks, alcohol, household, baby and pet
products unless another aisle is named. Tobacco, infant formula and
medicines are never included.

Args:
    query: words in the product's name or brand, e.g. "heinz" or
        "baileys": a product or a brand, never an aisle (few wines have
        the word wine in their name).
    category: an aisle or shelf, e.g. "frozen", "household" or
        "toiletries". "alcohol" is every drink above 0.5% ABV at the
        five chains, low-alcohol ones included. "alcohol free" is the
        drinks of 0.5% ABV or less: by the strength on record, by a name
        that says alcohol free, non-alcoholic, 0.0 or de-alcoholised, or,
        with no strength on record, by a shelf that says so (a shop's
        shared "low and no" shelf alone does not count); "low and no"
        adds the low-alcohol drinks on those shelves. The drinks aisles
        are "wine", "beer", "cider", "spirits" (liqueurs included),
        "liqueurs" and "premixes" (alcopops and canned cocktails), or a
        list such as "beer and cider". Together they hold all of
        "alcohol" but a drink whose shelf, name, type and strength place
        it in none of them, such as a beer shelved only under a shop's
        whole drinks department with only its brand for a name. "drinks"
        is every drink, alcohol included; "soft drinks" leaves alcohol
        out.
    store: one of "aldi", "tesco", "supervalu", "dunnes", "lidl". Leave it
        out for all five.
    limit: how many deals to return in one page (default 20, max 200).
    offset: how many deals to skip, for the next page (default 0).

Returns {"as_of", "note", "total", "deals"}. total counts every deal for
this search, across all pages. Each deal has name, store, pack,
you_pay, regular_price, saving_eur, saving_pct, card_needed, buy_quantity,
offer_ends, url and category, and the record behind it: kind, lowest_since,
low_before, low_before_date, offer_start, run_start, days_on_offer,
started_today, cut_today, yesterday_price, back_after_days, typical_price,
offer_share and abv. started_today is true only for an offer that began on
the collection day; an offer running for weeks whose price fell that day
has cut_today instead, and offer_start says since when it has been on
offer. One credit per deal returned.

Args:
    query: product-name substring (e.g. "heinz baked beans 415g").
    limit_per_store: how many matches per store (default 5).

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,
offer_ends, clubcard_price, url}}, "cheapest_store"}]}. A store missing from "prices" did not have that product in its online range today and may still sell it in store: say "not found online", not that the store lacks it. offer_ends is the last day an
offer applies (Irish time): say when an offer ends, as online orders are
priced for the delivery or collection day.

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 strength is recorded for most SuperValu, Dunnes and
Tesco drinks but few at Aldi or Lidl; "alcohol free" and "0.0" in query
match drinks named that way.

Answers come from the ingredient lists and nutrition the retailers publish.
Where a retailer gives no list, it may come from the same barcode at another
retailer or from Open Food Facts (ingredients_source); an Open Food Facts
list is never used to show a product is free from something.
"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, dunnes or lidl. Leave out to search all five.
    category: an aisle or shelf to narrow by, e.g. "Breakfast Cereals"
        or "Kefir". A store with no aisle or shelf of that name is searched
        by product name instead, and caveats say so.
    exclude_ingredients: ingredients a product has to be free of, e.g.
        ["palm oil"], ["nuts", "sesame"], ["vegan"]. A product whose
        allergy advice says it contains or may contain one is left out
        too, and counted in left_out_may_contain.
    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.
    max_additives: at most this many additives in the product's whole
        ingredient list, e.g. 0 for none: each E-number or additive by name
        once (preservatives, emulsifiers, raising agents, acidity regulators,
        thickeners, colours and the like); flavourings, vitamins, minerals and
        colouring foods are not additives. A list that is cut short or comes
        from Open Food Facts is left out as unknown, unless what it shows is
        already too many.
    on_offer: only products on promotion or with a member price
        (Tesco Clubcard, SuperValu Real Rewards, Lidl Plus).
    origin: country of origin, e.g. "Ireland" (or "Irish"); several may be
        given comma-separated. A product matches only when every country its
        label states is one asked for: "Made in Ireland" with "EU chicken" is
        not Irish chicken, and is counted in left_out_partly_from_origin.
        Northern Ireland answers for Ireland (one island, one Bord Bia
        scheme), not the other way round. Products with no stated origin are
        counted in left_out_unknown, not returned. A provenance word in the
        query works too: "Irish honey" searches honey from Ireland.
    sort_by: price, unit_price (per kg or litre), sugar, salt, fat, carbs,
        protein, kcal, abv, ingredients or additives (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). When a search excludes an allergen, every product carries allergy_check. Show that line with every product you mention, word for word.

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.

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).

Returns offer label (e.g. "3 for €5", "SAVE €0.75"), was-price,
validity window, offer_ends (the last day the offer applies, Irish
time), 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 in one page (default 25,
        max 200).
    offset: how many rows to skip, for the next page (default 0). A page
        shorter than limit is the last one.

Args:
    store: "aldi" | "tesco" | "supervalu" | "dunnes" | "lidl".
    limit: page size (default 100, max 200).
    offset: pagination offset.

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".
    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.

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.

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.

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).

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, max 50).

Args:
    store: "aldi" | "tesco" | "supervalu" | "dunnes" | "lidl".
    limit: how many movers to return (default 25).

Args:
    store: "aldi" | "tesco" | "supervalu" | "dunnes" | "lidl".
    days_back: how many days back to consider (default 7).
    limit: how many removed products to return.

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.