BasketWatch
Irish grocery prices at Aldi, Tesco, SuperValu and Dunnes: compare, baskets, offers, history
我該用這個嗎
品質與安全性
根據工具定義與協定合規性的自動化分析。
上下文成本
這是每次將伺服器的工具載入模型上下文時所消耗的約略 token 數量。數量越高，可用於其他工作的注意力就越少。
安裝
一鍵安裝
將以下內容加入你的 `claude_desktop_config.json` 檔案：
{
"mcpServers": {
"basketwatch": {
"url": "https://basketwatchireland.com/mcp"
}
}
}遠端端點
https://basketwatchireland.com/mcpstreamable-http它能做什麼
工具清單
工具（17）
🟢status
A freshness snapshot per supermarket: products tracked, products on promotion, the last collection date and the status of the most recent run.
輸入結構描述
{
"type": "object",
"properties": {},
"title": "statusArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Status"
},
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "As Of"
},
"stores": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/$defs/StoreFreshness"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Stores"
}
},
"$defs": {
"StoreFreshness": {
"additionalProperties": true,
"properties": {
"products": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Products"
},
"on_promotion": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "On Promotion"
},
"last_scrape_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Scrape Date"
},
"last_run_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Run Status"
}
},
"title": "StoreFreshness",
"type": "object"
}
},
"additionalProperties": true,
"title": "Freshness"
}🟢search_products(query, store, limit)
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). 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.
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"title": "Query",
"type": "string"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "search_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/Product"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"Product": {
"additionalProperties": true,
"properties": {
"id": {
"description": "Stable per-retailer product id, e.g. tesco:12345",
"title": "Id",
"type": "string"
},
"name": {
"description": "Product name as the retailer lists it",
"title": "Name",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price per kg or per litre",
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"category_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category Path"
},
"scrape_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot date, YYYY-MM-DD",
"title": "Scrape Date"
}
},
"required": [
"id",
"name"
],
"title": "Product",
"type": "object"
}
},
"title": "search_productsOutput"
}🟢compare_prices(query, limit)
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 return (default 5, max 20). 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. One product per call.
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"title": "Query",
"type": "string"
},
"limit": {
"default": 5,
"title": "Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "compare_pricesArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Price date, YYYY-MM-DD",
"title": "As Of"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"matches": {
"items": {
"$ref": "#/$defs/ComparedProduct"
},
"title": "Matches",
"type": "array"
}
},
"$defs": {
"ComparedProduct": {
"additionalProperties": true,
"properties": {
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The matched product",
"title": "Product"
},
"pack": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack"
},
"prices": {
"additionalProperties": {
"$ref": "#/$defs/StorePrice"
},
"description": "Keyed by store (aldi, tesco, supervalu, dunnes); a store missing here does not stock this product",
"title": "Prices",
"type": "object"
},
"cheapest_store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Lowest shelf price",
"title": "Cheapest Store"
}
},
"title": "ComparedProduct",
"type": "object"
},
"StorePrice": {
"additionalProperties": true,
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "This store's product id",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The product as this store lists it",
"title": "Name"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"was_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Was Price"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price, Tesco only",
"title": "Clubcard Price"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
}
},
"title": "StorePrice",
"type": "object"
}
},
"additionalProperties": true,
"title": "Comparison"
}🟢compare_price_across_stores(query, limit_per_store)
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).
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"title": "Query",
"type": "string"
},
"limit_per_store": {
"default": 5,
"title": "Limit Per Store",
"type": "integer"
}
},
"required": [
"query"
],
"title": "compare_price_across_storesArguments"
}🟢lookup_barcode(codes, store, include_copy)
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.
輸入結構描述
{
"type": "object",
"properties": {
"codes": {
"title": "Codes",
"type": "string"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"include_copy": {
"default": false,
"title": "Include Copy",
"type": "boolean"
}
},
"required": [
"codes"
],
"title": "lookup_barcodeArguments"
}🟢get_promotions(store, limit)
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).
輸入結構描述
{
"type": "object",
"properties": {
"store": {
"title": "Store",
"type": "string"
},
"limit": {
"default": 25,
"title": "Limit",
"type": "integer"
}
},
"required": [
"store"
],
"title": "get_promotionsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/Promotion"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"Promotion": {
"additionalProperties": true,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price while on promotion",
"title": "Price"
},
"was_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price before the promotion",
"title": "Was Price"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Offer label as displayed",
"title": "Offer Text"
},
"offer_valid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Validity window in the retailer's own wording",
"title": "Offer Valid"
}
},
"required": [
"id",
"name"
],
"title": "Promotion",
"type": "object"
}
},
"title": "get_promotionsOutput"
}🟢recent_price_changes(store, limit)
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).
輸入結構描述
{
"type": "object",
"properties": {
"store": {
"title": "Store",
"type": "string"
},
"limit": {
"default": 25,
"title": "Limit",
"type": "integer"
}
},
"required": [
"store"
],
"title": "recent_price_changesArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot being reported",
"title": "Date"
},
"prev_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot compared against",
"title": "Prev Date"
},
"shelf_increases": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/PriceChange"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Increases"
},
"shelf_decreases": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/PriceChange"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Decreases"
},
"promotions": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/PriceChange"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Offers starting or ending, not shelf moves",
"title": "Promotions"
},
"clubcard_changes": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/PriceChange"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Loyalty-card price changes, Tesco only",
"title": "Clubcard Changes"
},
"shelf_increases_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Increases Total"
},
"shelf_decreases_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Decreases Total"
},
"promotions_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Promotions Total"
},
"clubcard_changes_total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Clubcard Changes Total"
}
},
"$defs": {
"PriceChange": {
"additionalProperties": true,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"price_now": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Price Now"
},
"prev_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Prev Price"
},
"pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Percentage change, signed",
"title": "Pct"
}
},
"required": [
"id",
"name"
],
"title": "PriceChange",
"type": "object"
}
},
"additionalProperties": true,
"description": "The /changes payload.\n\nShelf moves, promotions and loyalty-card changes are deliberately SEPARATE\nbuckets, not one blended list: an expiring offer is not a price rise, and\nmerging them turns a price report into a promotions calendar.",
"title": "PriceChanges"
}🟢newly_added_products(store, days_back, limit)
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.
輸入結構描述
{
"type": "object",
"properties": {
"store": {
"title": "Store",
"type": "string"
},
"days_back": {
"default": 7,
"title": "Days Back",
"type": "integer"
},
"limit": {
"default": 25,
"title": "Limit",
"type": "integer"
}
},
"required": [
"store"
],
"title": "newly_added_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/Product"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"Product": {
"additionalProperties": true,
"properties": {
"id": {
"description": "Stable per-retailer product id, e.g. tesco:12345",
"title": "Id",
"type": "string"
},
"name": {
"description": "Product name as the retailer lists it",
"title": "Name",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price per kg or per litre",
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"category_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category Path"
},
"scrape_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot date, YYYY-MM-DD",
"title": "Scrape Date"
}
},
"required": [
"id",
"name"
],
"title": "Product",
"type": "object"
}
},
"title": "newly_added_productsOutput"
}🟢removed_products(store, days_back, limit)
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.
輸入結構描述
{
"type": "object",
"properties": {
"store": {
"title": "Store",
"type": "string"
},
"days_back": {
"default": 7,
"title": "Days Back",
"type": "integer"
},
"limit": {
"default": 25,
"title": "Limit",
"type": "integer"
}
},
"required": [
"store"
],
"title": "removed_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/Product"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"Product": {
"additionalProperties": true,
"properties": {
"id": {
"description": "Stable per-retailer product id, e.g. tesco:12345",
"title": "Id",
"type": "string"
},
"name": {
"description": "Product name as the retailer lists it",
"title": "Name",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price per kg or per litre",
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"category_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category Path"
},
"scrape_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot date, YYYY-MM-DD",
"title": "Scrape Date"
}
},
"required": [
"id",
"name"
],
"title": "Product",
"type": "object"
}
},
"title": "removed_productsOutput"
}🟢list_products(store, limit, offset)
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.
輸入結構描述
{
"type": "object",
"properties": {
"store": {
"title": "Store",
"type": "string"
},
"limit": {
"default": 100,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
}
},
"required": [
"store"
],
"title": "list_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/Product"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"Product": {
"additionalProperties": true,
"properties": {
"id": {
"description": "Stable per-retailer product id, e.g. tesco:12345",
"title": "Id",
"type": "string"
},
"name": {
"description": "Product name as the retailer lists it",
"title": "Name",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price per kg or per litre",
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"category_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category Path"
},
"scrape_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Snapshot date, YYYY-MM-DD",
"title": "Scrape Date"
}
},
"required": [
"id",
"name"
],
"title": "Product",
"type": "object"
}
},
"title": "list_productsOutput"
}🟢get_price_history(product_ids, query, store, from_date, to_date, ...)
A product's recorded daily prices over a date range. BasketWatch has kept every night's price at all four supermarkets since May 2026. Takes product ids (store-prefixed, as returned in product results) 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. Args: product_ids: e.g. ["tesco:300793546", "dunnes:100873410"]; each id's store is taken from the id. query: product name words, used when no product_ids are given. store: aldi, tesco, supervalu or dunnes, to narrow a query. Leave it out to look in all four. 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 60). Returns one row per product per day: id, name, store, scrape_date, price, unit_price, unit_basis, clubcard_price, offer_text, was_price.
輸入結構描述
{
"type": "object",
"properties": {
"product_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Product Ids"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"from_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "From Date"
},
"to_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Date"
},
"limit": {
"default": 60,
"title": "Limit",
"type": "integer"
}
},
"title": "get_price_historyArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"result": {
"items": {
"$ref": "#/$defs/PricePoint"
},
"title": "Result",
"type": "array"
}
},
"required": [
"result"
],
"$defs": {
"PricePoint": {
"additionalProperties": true,
"properties": {
"id": {
"description": "Per-retailer product id, e.g. tesco:12345",
"title": "Id",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"scrape_date": {
"description": "The day this price was recorded, YYYY-MM-DD",
"title": "Scrape Date",
"type": "string"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro that day",
"title": "Price"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Basis"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price that day",
"title": "Clubcard Price"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"was_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Was Price"
}
},
"required": [
"id",
"scrape_date"
],
"title": "PricePoint",
"type": "object"
}
},
"title": "get_price_historyOutput"
}🟢get_product_details(query, product_ids, skus, store, limit)
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).
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"product_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Product Ids"
},
"skus": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Skus"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"limit": {
"default": 5,
"title": "Limit",
"type": "integer"
}
},
"title": "get_product_detailsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"note": {
"title": "Note",
"type": "string"
},
"products": {
"items": {
"$ref": "#/$defs/ProductDetail"
},
"title": "Products",
"type": "array"
}
},
"required": [
"note"
],
"$defs": {
"Nutrition": {
"additionalProperties": true,
"properties": {
"energy_kj": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy Kj"
},
"energy_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy Kcal"
},
"fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat G"
},
"carbohydrate_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Carbohydrate G"
},
"sugars_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Sugars G"
},
"protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Protein G"
},
"salt_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Salt G"
}
},
"title": "Nutrition",
"type": "object"
},
"ProductDetail": {
"additionalProperties": true,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"name": {
"title": "Name",
"type": "string"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Today's shelf price in euro",
"title": "Price"
},
"pack_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack Size"
},
"ingredients": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "As printed, allergens included",
"title": "Ingredients"
},
"ingredients_incomplete": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when the list on record appears cut short, so it is not the full list and cannot show that something is absent",
"title": "Ingredients Incomplete"
},
"ingredient_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "How many ingredients the label lists (a compound ingredient's own bracketed list counts as one); missing when it cannot be told reliably",
"title": "Ingredient Count"
},
"nutrition_per_100": {
"anyOf": [
{
"$ref": "#/$defs/Nutrition"
},
{
"type": "null"
}
],
"default": null,
"description": "Per 100g, or per 100ml for drinks"
},
"nutrition_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Where the nutrition values came from",
"title": "Nutrition Source"
},
"alcohol_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Alcohol by volume, percent",
"title": "Alcohol Abv"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
}
},
"required": [
"id",
"name"
],
"title": "ProductDetail",
"type": "object"
}
},
"additionalProperties": true,
"title": "ProductDetails"
}🟢find_products(query, store, category, exclude_ingredients, include_ingredients, ...)
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).
輸入結構描述
{
"type": "object",
"properties": {
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
},
"exclude_ingredients": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Exclude Ingredients"
},
"include_ingredients": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Include Ingredients"
},
"max_sugar_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Sugar G"
},
"max_salt_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Salt G"
},
"max_fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Fat G"
},
"max_carbs_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Carbs G"
},
"min_protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Protein G"
},
"max_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Kcal"
},
"max_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Abv"
},
"min_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Abv"
},
"max_ingredients": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Ingredients"
},
"on_offer": {
"default": false,
"title": "On Offer",
"type": "boolean"
},
"sort_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sort By"
},
"descending": {
"default": false,
"title": "Descending",
"type": "boolean"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
}
},
"title": "find_productsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"note": {
"title": "Note",
"type": "string"
},
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Price date, YYYY-MM-DD",
"title": "As Of"
},
"matched": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Products that passed every filter",
"title": "Matched"
},
"considered": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Products the search looked at",
"title": "Considered"
},
"matched_by_store": {
"additionalProperties": {
"type": "integer"
},
"description": "How many products passed at each store (more than are returned)",
"title": "Matched By Store",
"type": "object"
},
"left_out_unknown": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Left out because the ingredients, nutrition or value a filter or sort needs is not on record for them, or the ingredient list is incomplete",
"title": "Left Out Unknown"
},
"left_out_by_reason": {
"additionalProperties": {
"type": "integer"
},
"description": "Why products were left out, with counts",
"title": "Left Out By Reason",
"type": "object"
},
"left_out_by_store": {
"additionalProperties": {
"type": "integer"
},
"title": "Left Out By Store",
"type": "object"
},
"caveats": {
"description": "Limits of this answer: pass them on",
"items": {
"type": "string"
},
"title": "Caveats",
"type": "array"
},
"products": {
"items": {
"$ref": "#/$defs/FoundProduct"
},
"title": "Products",
"type": "array"
}
},
"required": [
"note"
],
"$defs": {
"FoundProduct": {
"additionalProperties": true,
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"name": {
"title": "Name",
"type": "string"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"pack_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack Size"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Today's shelf price in euro",
"title": "Price"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The unit unit_price is measured in",
"title": "Unit Basis"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price, Tesco only",
"title": "Clubcard Price"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"nutrition_per_100": {
"anyOf": [
{
"$ref": "#/$defs/Nutrition"
},
{
"type": "null"
}
],
"default": null,
"description": "Per 100g, or per 100ml for drinks"
},
"alcohol_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Alcohol by volume, percent",
"title": "Alcohol Abv"
},
"ingredients": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "As printed; very long lists are shortened",
"title": "Ingredients"
},
"ingredients_incomplete": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when the list on record appears cut short",
"title": "Ingredients Incomplete"
},
"ingredient_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "How many ingredients the label lists (a compound ingredient's own bracketed list counts as one)",
"title": "Ingredient Count"
},
"name_match_only": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when only the name matched the search, not the kind of product: chocolate popcorn for 'chocolate'. Sorted results list these last",
"title": "Name Match Only"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
}
},
"required": [
"id",
"name"
],
"title": "FoundProduct",
"type": "object"
},
"Nutrition": {
"additionalProperties": true,
"properties": {
"energy_kj": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy Kj"
},
"energy_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Energy Kcal"
},
"fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Fat G"
},
"carbohydrate_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Carbohydrate G"
},
"sugars_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Sugars G"
},
"protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Protein G"
},
"salt_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Salt G"
}
},
"title": "Nutrition",
"type": "object"
}
},
"additionalProperties": true,
"title": "FoundProducts"
}🟢price_basket(items, store)
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.
輸入結構描述
{
"type": "object",
"properties": {
"items": {
"items": {
"$ref": "#/$defs/BasketItem"
},
"title": "Items",
"type": "array"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
}
},
"required": [
"items"
],
"$defs": {
"BasketItem": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Brand, product and size in plain words, e.g. 'avonmore fresh milk 2l'",
"title": "Name"
},
"sku": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The retailer's own item number printed on the receipt line, when there is one",
"title": "Sku"
},
"barcode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The product's barcode (EAN), when known",
"title": "Barcode"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "aldi, tesco, supervalu or dunnes; defaults to the basket's store",
"title": "Store"
},
"quantity": {
"default": 1,
"description": "How many were bought",
"title": "Quantity",
"type": "number"
},
"paid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "The line total printed on the receipt, in euro",
"title": "Paid"
}
},
"title": "BasketItem",
"type": "object"
}
},
"title": "price_basketArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"as_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Price date, YYYY-MM-DD",
"title": "As Of"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
},
"items": {
"items": {
"$ref": "#/$defs/BasketLine"
},
"title": "Items",
"type": "array"
},
"not_found": {
"description": "Items with no match",
"items": {
"type": "string"
},
"title": "Not Found",
"type": "array"
},
"totals_by_store": {
"additionalProperties": {
"$ref": "#/$defs/StoreTotal"
},
"title": "Totals By Store",
"type": "object"
},
"cheapest_complete_store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The cheapest store among those stocking every matched item",
"title": "Cheapest Complete Store"
},
"mix_and_match_total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Each item bought at its cheapest store",
"title": "Mix And Match Total"
},
"with_alternatives_total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "As mix_and_match_total, taking each cheaper alternative where there is one",
"title": "With Alternatives Total"
},
"tesco_clubcard_total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco total using Clubcard prices where Tesco has one",
"title": "Tesco Clubcard Total"
},
"paid_total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Paid Total"
},
"saving_vs_paid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Saving Vs Paid"
}
},
"$defs": {
"BasketAlternative": {
"additionalProperties": true,
"properties": {
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Product"
},
"pack": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Price"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Basis"
}
},
"title": "BasketAlternative",
"type": "object"
},
"BasketLine": {
"additionalProperties": true,
"properties": {
"item": {
"title": "Item",
"type": "string"
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Quantity"
},
"searched_as": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The words that found the match",
"title": "Searched As"
},
"matched": {
"$ref": "#/$defs/BasketMatch"
},
"cheapest_alternative": {
"anyOf": [
{
"$ref": "#/$defs/BasketAlternative"
},
{
"type": "null"
}
],
"default": null,
"description": "A cheaper product of the same kind, often own-label, where there is one"
},
"paid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Paid"
},
"saving_vs_paid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "What was paid minus the cheapest price for the same quantity",
"title": "Saving Vs Paid"
}
},
"required": [
"item",
"matched"
],
"title": "BasketLine",
"type": "object"
},
"BasketMatch": {
"additionalProperties": true,
"properties": {
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Product"
},
"pack": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack"
},
"prices": {
"additionalProperties": {
"$ref": "#/$defs/BasketStorePrice"
},
"description": "Keyed by store; a store missing here does not stock this product",
"title": "Prices",
"type": "object"
},
"cheapest_store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Cheapest Store"
},
"cheapest_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Cheapest Price"
}
},
"title": "BasketMatch",
"type": "object"
},
"BasketStorePrice": {
"additionalProperties": true,
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The product as this store lists it",
"title": "Name"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Shelf price in euro",
"title": "Price"
},
"unit_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Price"
},
"unit_basis": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Unit Basis"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price, Tesco only",
"title": "Clubcard Price"
}
},
"title": "BasketStorePrice",
"type": "object"
},
"StoreTotal": {
"additionalProperties": true,
"properties": {
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
},
"items_priced": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Items Priced"
},
"items_missing": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Matched items this store does not stock",
"title": "Items Missing"
}
},
"title": "StoreTotal",
"type": "object"
}
},
"additionalProperties": true,
"title": "Basket"
}🟢price_basket_over_time(items, from_date, to_date, store)
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 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 or dunnes).
輸入結構描述
{
"type": "object",
"properties": {
"items": {
"items": {
"$ref": "#/$defs/BasketItem"
},
"title": "Items",
"type": "array"
},
"from_date": {
"title": "From Date",
"type": "string"
},
"to_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Date"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
}
},
"required": [
"items",
"from_date"
],
"$defs": {
"BasketItem": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Brand, product and size in plain words, e.g. 'avonmore fresh milk 2l'",
"title": "Name"
},
"sku": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The retailer's own item number printed on the receipt line, when there is one",
"title": "Sku"
},
"barcode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The product's barcode (EAN), when known",
"title": "Barcode"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "aldi, tesco, supervalu or dunnes; defaults to the basket's store",
"title": "Store"
},
"quantity": {
"default": 1,
"description": "How many were bought",
"title": "Quantity",
"type": "number"
},
"paid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "The line total printed on the receipt, in euro",
"title": "Paid"
}
},
"title": "BasketItem",
"type": "object"
}
},
"title": "price_basket_over_timeArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"from_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "From Date"
},
"to_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Date"
},
"items": {
"items": {
"$ref": "#/$defs/LineOverTime"
},
"title": "Items",
"type": "array"
},
"not_compared": {
"description": "Lines not found, or not sold on one date",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Not Compared",
"type": "array"
},
"total_then": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Then"
},
"total_now": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Now"
},
"change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "total_now minus total_then, euro",
"title": "Change"
},
"change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Change Pct"
},
"shelf_total_then": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Total Then"
},
"shelf_total_now": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Total Now"
},
"shelf_change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Change in regular prices only: real price moves, without promotions",
"title": "Shelf Change Pct"
},
"biggest_rises": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Biggest Rises",
"type": "array"
},
"biggest_falls": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Biggest Falls",
"type": "array"
},
"items_unchanged": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Items Unchanged"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
}
},
"$defs": {
"LineOverTime": {
"additionalProperties": true,
"properties": {
"item": {
"title": "Item",
"type": "string"
},
"quantity": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Quantity"
},
"matched_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "sku, barcode or name",
"title": "Matched By"
},
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Product"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"then": {
"anyOf": [
{
"$ref": "#/$defs/PriceOnDate"
},
{
"type": "null"
}
],
"default": null
},
"now": {
"anyOf": [
{
"$ref": "#/$defs/PriceOnDate"
},
{
"type": "null"
}
],
"default": null
},
"change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Price change per unit, euro",
"title": "Change"
},
"change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Change Pct"
},
"line_change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Change for the quantity bought, euro",
"title": "Line Change"
},
"shelf_change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Regular-price change per unit, euro",
"title": "Shelf Change"
},
"pack_changed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "The pack size changed between the dates",
"title": "Pack Changed"
}
},
"required": [
"item"
],
"title": "LineOverTime",
"type": "object"
},
"PriceOnDate": {
"additionalProperties": true,
"properties": {
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The day this price was recorded (the latest record on or before the date asked)",
"title": "Date"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "What it cost that day, promotions included",
"title": "Price"
},
"shelf_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Its regular price that day, without promotions",
"title": "Shelf Price"
},
"on_promotion": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "On Promotion"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price, Tesco only",
"title": "Clubcard Price"
},
"pack": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack"
}
},
"title": "PriceOnDate",
"type": "object"
}
},
"additionalProperties": true,
"title": "BasketOverTime"
}🟢price_movements(from_date, to_date, group, query, category, ...)
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 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 Clubcard 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). on_promotion_both_dates marks a shelf change in the label's "was" price while the offer price paid did not move. 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 or dunnes; leave out for all four. kinds: which lists to return (default all six). rank_by: "pct" (default) or "eur". limit: most products per list (default 10, max 50).
輸入結構描述
{
"type": "object",
"properties": {
"from_date": {
"title": "From Date",
"type": "string"
},
"to_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Date"
},
"group": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Group"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"kinds": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Kinds"
},
"rank_by": {
"default": "pct",
"title": "Rank By",
"type": "string"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
}
},
"required": [
"from_date"
],
"title": "price_movementsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"from_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "From Date"
},
"to_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "To Date"
},
"summary": {
"additionalProperties": true,
"description": "Over EVERY product compared, not only those listed",
"title": "Summary",
"type": "object"
},
"summary_by_store": {
"additionalProperties": true,
"title": "Summary By Store",
"type": "object"
},
"movers": {
"items": {
"$ref": "#/$defs/Mover"
},
"title": "Movers",
"type": "array"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Note"
}
},
"$defs": {
"Mover": {
"additionalProperties": true,
"properties": {
"kind": {
"description": "shelf_rise, shelf_fall, promotion_started, promotion_ended, loyalty_change or pack_change",
"title": "Kind",
"type": "string"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Id"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name"
},
"brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Brand"
},
"then": {
"anyOf": [
{
"$ref": "#/$defs/PriceOnDate"
},
{
"type": "null"
}
],
"default": null
},
"now": {
"anyOf": [
{
"$ref": "#/$defs/PriceOnDate"
},
{
"type": "null"
}
],
"default": null
},
"shelf_change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Regular-price change, euro",
"title": "Shelf Change"
},
"shelf_change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Shelf Change Pct"
},
"paid_change": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Change in what it cost, promotions included",
"title": "Paid Change"
},
"paid_change_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Paid Change Pct"
},
"pack_changed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack Changed"
},
"on_promotion_both_dates": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "An offer ran at both dates: a shelf change here is the label's regular ('was') price moving while shoppers paid the offer price",
"title": "On Promotion Both Dates"
}
},
"required": [
"kind"
],
"title": "Mover",
"type": "object"
},
"PriceOnDate": {
"additionalProperties": true,
"properties": {
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The day this price was recorded (the latest record on or before the date asked)",
"title": "Date"
},
"price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "What it cost that day, promotions included",
"title": "Price"
},
"shelf_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Its regular price that day, without promotions",
"title": "Shelf Price"
},
"on_promotion": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "On Promotion"
},
"offer_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Offer Text"
},
"clubcard_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Tesco Clubcard price, Tesco only",
"title": "Clubcard Price"
},
"pack": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Pack"
}
},
"title": "PriceOnDate",
"type": "object"
}
},
"additionalProperties": true,
"title": "Movements"
}🟢check_credits
How many BasketWatch credits the signed-in account has left. Free to call. One credit is one record returned.
輸入結構描述
{
"type": "object",
"properties": {},
"title": "check_creditsArguments"
}輸出結構描述
{
"type": "object",
"properties": {
"plan": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Plan"
},
"metered": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True when the account pays per record from credits",
"title": "Metered"
},
"credits_remaining": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "One credit is one record returned",
"title": "Credits Remaining"
}
},
"additionalProperties": true,
"title": "CreditBalance"
}社群
證據