How a kind of product's prices moved
price_movementsHow 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"from_date": "<from_date>"
},
"name": "price_movements"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 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'). | |
| kinds | No | Which lists to return. Left out: all seven. | |
| limit | No | Most products in each list (default 10, at most 50). | |
| query | No | Product or brand words, with or without group, e.g. 'guinness'. | |
| store | No | One shop to look in only that one: aldi, tesco, supervalu, dunnes or lidl. Leave it out for all five. | |
| rank_by | No | Rank each list by the percentage change (pct, the default) or the change in euro (eur). | pct |
| to_date | No | The later date, YYYY-MM-DD. Left out: today. | |
| category | No | An aisle name to narrow by. | |
| from_date | Yes | The earlier date, YYYY-MM-DD (prices are kept since May 2026). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| movers | No | ||
| credits | No | What this answer cost the person's BasketWatch account and what is left. Missing on a free answer | |
| summary | No | Over EVERY product compared, not only those listed | |
| to_date | No | ||
| from_date | No | ||
| summary_by_store | No |