Data Market

Report the account's plan, remaining quota and trial status. Call this when the user asks how much they have left, and before proposing a large analysis so you can warn them if the balance will not cover it. This endpoint is not billed and does not consume quota.

account_balance

Compare two specific stores item by item, with the price gap on each product. Setting `position='above'` answers 'which of my products are more expensive than theirs' in a single call — far cheaper than exporting both assortments and diffing them. Billed by volume, roughly 2 quota units per page.

compare_to_competitor

Find brands in the catalogue and how many products each one has. Use this to resolve a brand name before calling `products_by_brand` or `stores_by_brand`, which need the brand spelled exactly as stored. Costs 1 quota unit.

list_brands

List every department and category in the catalogue, with product counts. Call this before using the `department` or `category` filter on any other tool: those filters match stored values exactly, so a guessed label silently returns nothing. Cheap (1 quota unit) and stable — the taxonomy rarely changes.

list_departments

List monitored supermarkets and, crucially, their store_id. This is the entry point for every store-level analysis: `store_assortment`, `store_competitors`, `store_competitiveness`, `store_price_position`, `pricing_opportunities` and `compare_to_competitor` all require a store_id, and none of them accept a store name. Start here whenever the user names a retailer. Costs 1 quota unit.

list_stores

Track how a product's price moved over time, market-wide and per store. Answers 'is this getting more expensive' and 'when did the competition drop their price'. The market series carries the median, minimum and maximum per period with outliers already excluded. The window caps at 180 days upstream, with history starting in April 2026, so a request for more is served the widest window available. Costs 1 quota unit.

price_history

List repricing opportunities, ranked by how far each item sits from the market. The most directly actionable tool in this server: it answers 'what should I reprice this week' in one call, splitting products into margin upside, competitive risk, and comfortably positioned. Billed by volume, roughly 2 quota units per page.

pricing_opportunities

Show one product's price and stock across every monitored store. This is the direct answer to 'how much does X cost and where is it cheapest'. Returns market-wide statistics plus the per-store breakdown — by default every store carrying the product, since the cost is a flat 1 unit no matter how many. Filter by `state` or `city` when the user only cares about one region, or set `store_limit` to rank a shortlist; there is no need to paginate by state to see full coverage.

product_by_ean

List a brand's products with price dispersion and availability per item. `cv_percent` is the coefficient of variation: high values mean the same product sells at very different prices across stores, which is where pricing action usually is. The brand name must match exactly — resolve it with `list_brands`. Costs 1 quota unit per page.

products_by_brand

Browse the product catalogue with price and availability aggregates. Use this to find products matching a description and to read their EANs, which `product_by_ean` and `price_history` require. Brand, category and department are exact matches — resolve them with `list_brands` and `list_departments` first. Costs 1 quota unit per page.

search_catalog