The unified categories with Dutch display names, product counts and group. Call this before pp_search to turn a user's word ("zuivel", "brood") into a valid category slug. Cheap, and worth it before a search that would otherwise return nothing.

Every current deal for one brand, e.g. Coca-Cola or Ahold. Brand matching follows the capitalisation in the source data, so keep the brand as the user wrote it and do not normalise it.

Deals for one promotion mechanic, passed as a keyword such as 1+1, 2+2 or korting. The type values used by promotion_type elsewhere are the internal names (percentage, multi_buy, one_plus_one, volume, limited, starting).

The most recently started offers, capped at 30 rows.

The deals users click most often, capped at 30 rows.

Aggregate stats: total products, retailer count, biggest discount, last update. One cheap call to check that the data is fresh before reporting anything about "this week".

Top deals grouped per brand, optionally narrowed to one or more retailers. min_savings defaults to 10%; raise it to cut the noise. Pass retailer as an array to scope the lists to specific chains.

Facet counts per retailer, promotion status and category. Pass q (and optionally category) to get the counts for one specific search — useful to show what a filter would still return, or to check whether a category exists before searching it.

Check that the PrijsProfeet API is reachable. Call this when another tool returns 5xx to tell an outage apart from a bad request.

Current rate-limit usage and account info for the configured API key. Requires a valid partner key, so it fails with 401 when the server is running without one.

List products with filters, newest extraction first. Use pp_search when the user named a product; use this when you need to enumerate by retailer, folder, promo group or validity window. promo_group_id returns every product in one shared action — read that field off a product to get the rest of its group. min_valid_from / max_valid_from (YYYY-MM-DD) bound the date the promotion starts.

Full detail for one product, including EAN, folder, promo group and dietary labels. product_id is the product_id field from any search or list result.

Server-side backtested price forecast for one product ("Profeet voorspelt"). A product with no forecast is not an error: the call returns HTTP 200 with a null forecast, and the reason arrives in the X-Forecast-Reason header. Report it as "no forecast available" rather than retrying.

Every product in one promotional folder (a single actie). folder_id is the folder_id field on a product. page_size may go up to 1000 here, but a big page is expensive in context and in rate limit — ask for what the question needs.

Everything currently on offer, newest first. Use pp_list_products with is_promotional=true instead when you also need a filter.

Every product from one retailer, paginated. Takes a retailer slug (albert_heijn, jumbo, aldi, lidl, ekoplaza, plus, dekamarkt, hoogvliet, vomar, dirk), not a display name.

Search products with the term inside the URL path. This is the older sibling of pp_search: same data, fewer filters, no sorting. Prefer pp_search for new work.

Search supermarket offers across the 10 Dutch chains (Albert Heijn, Aldi, DekaMarkt, Dirk, Ekoplaza, Hoogvliet, Jumbo, Lidl, PLUS, Vomar). Omit q or pass * to browse the whole catalogue.

How to read a row: promotion_status decides what the price means. active = on offer right now, upcoming = starts next week, shelf = the regular price, historical = the last price seen, up to 60 days old. Taking the lowest price across rows can therefore return a price nobody is charging today — filter on promotion_status (or leave current_only-style filtering to the caller) before quoting a best price.

Retailer slugs: albert_heijn, jumbo, aldi, lidl, ekoplaza, plus, dekamarkt, hoogvliet, vomar, dirk. Category slugs are not free text: call pp_get_categories first to map the user's word to a slug. Keep page_size modest; page through rather than asking for 100 rows when a question needs 3.

Availability per calendar month, newest first. Answers "was the API down last Tuesday?" with a number instead of a guess.

Request a free API key for an email address. A one-click link is mailed out; the key itself is never in the response. The response is deliberately identical whether or not that address already has a key, so a success here never confirms someone is a customer. Capped at 5 requests per hour per IP. This has a real-world side effect — it emails a stranger. Only call it when the user has explicitly asked for it in this conversation.