# Heureka API scraper — Czech & Slovak price comparison: search products, read the full product record with Heureka's parameter sheet, and get every shop's offer (price, shop score, stock, delivery) for one product on heureka.cz / heureka.sk. Prices in CZK or EUR. No account, no browser.

> Search Heureka by keyword and get the matching products: Heureka product id and address, title, image, the PRICE BAND across all shops (both ends when Heureka prints both — see `price_kind`), how many shops sell it, the customer score and review count, the category, and how many colour/size variants the card lists. Feed the returned `product` or `url` straight into `product/offers` or `product/detail` to get every shop's price for that product. Check `row_type` first: only rows with row_type 'product' carry an address, and the other three kinds return `product` as null rather than a handle that would not work.
> ReefAPI engine `heureka` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/heureka/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/heureka/v1/search — 1 credit
Search Heureka by keyword and get the matching products: Heureka product id and address, title, image, the PRICE BAND across all shops (both ends when Heureka prints both — see `price_kind`), how many shops sell it, the customer score and review count, the category, and how many colour/size variants the card lists. Feed the returned `product` or `url` straight into `product/offers` or `product/detail` to get every shop's price for that product. Check `row_type` first: only rows with row_type 'product' carry an address, and the other three kinds return `product` as null rather than a handle that would not work.

**Parameters:**
- `query` (string, required) — What to look for on Heureka. Czech (or Slovak, with market=sk) keywords match best, but brands and model numbers work directly — 'iphone 15', 'bosch vrtacka', 'dyson v15'. Heureka matches loosely, so a two-word query also returns accessories for the product, not only the product.
- `page` (integer, optional, default 1) — Result page, 1-BASED (1, 2, 3…). 24 products per page. Heureka publishes no result total, so `total_results` is null by design; `last_page` in the response is the highest page its own pager offers, and `meta.pagination.has_more` tells you whether to ask for the next one.
- `sort` (enum, optional, default "relevance") — Result ordering. Only orderings heureka.cz actually honours are accepted; anything else is rejected rather than silently ignored, so you never receive a relevance list believing it was sorted. [one of: relevance, price_asc, price_desc, most_reviewed]
- `market` (enum, optional, default "cz") — Which Heureka storefront to read. The two are separate catalogues with separate shops and currencies: a product URL from one market is not valid in the other. [one of: cz, sk]

**Returns:** results[]{row_type ('product' = a Heureka product page with a shop comparison behind it, the only kind with a usable `product` address | 'shop_offer' = a single merchant's listing with no product page, so `product` and `offer_count` are null | 'promoted' = a promoted product whose link is a signed click-through, so it has a price, a score and an offer_count but no address Heureka publishes, and `product` is null | 'article' = an editorial guide, not an offer), product_id, product_uuid, product (category/slug shorthand), title, url, image, price_min, price_max, price_min_display, price_max_display, price_display, price_kind ('band' = both ends real | 'from' = price_max is null because Heureka printed only a floor | 'exact' = one offer, min == max), price_is_single_offer, currency, offer_count (how many shops sell it), offer_count_display, rating_percent (Heureka's 0-100 score), rating (the same score as 0-5 stars), rating_scale, review_count, category, category_url, variant_count_listed, badges[]}, count, product_count, shop_offer_count, unreadable_tiles, query_heading, last_page, total_results (ALWAYS null — Heureka publishes no result count), market, currency (meta.pagination for paging)

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

### POST https://api.reefapi.com/heureka/v1/product/detail — 1 credit
The full Heureka product record for one product address: title, brand, description, image gallery, the price BAND across all shops (price_min and price_max, both from Heureka's own AggregateOffer) with its offer count, the customer score and review count, the category breadcrumb with URLs, the complete Heureka parameter sheet, and the sibling variants of the product.

**Parameters:**
- `product` (string, required) — The product address, either as the full Heureka URL (https://mobilni-telefony.heureka.cz/apple-iphone-15-128gb-black/) or as the 'category/slug' shorthand (mobilni-telefony/apple-iphone-15-128gb-black). Every `search` row hands you both, as `url` and `product`. A bare slug is not accepted: www.heureka.cz/<slug>/ answers 404 — the category subdomain is part of the address, and guessing it would return a confident wrong product.
- `market` (enum, optional, default "cz") — Which Heureka storefront to read. The two are separate catalogues with separate shops and currencies: a product URL from one market is not valid in the other. [one of: cz, sk]

**Returns:** product{product (shorthand), title, url, brand, description, category, breadcrumb[]{name, url}, images[], price_min, price_max, price_min_display, price_max_display, price_kind, currency, offer_count, availability, rating_percent, rating (0-5), rating_scale, rating_count, review_count, specs[]{name, value}, variants[]{name, url}}

**Example request body:**
```json
{
  "product": "mobilni-telefony/apple-iphone-15-128gb-black"
}
```

### POST https://api.reefapi.com/heureka/v1/product/offers — 2 credits
Every shop offer Heureka lists for one product — the price comparison itself. One row per merchant: shop name, Heureka shop score and how many ratings it rests on, the price (numeric and formatted), the stock line, the delivery line and whether delivery is free, the merchant's own listing title, and a working click-through. Rows are de-duplicated (Heureka repeats promoted offers above the list) and ordered cheapest first, with the product's own price band alongside.

**Parameters:**
- `product` (string, required) — The product address, either as the full Heureka URL (https://mobilni-telefony.heureka.cz/apple-iphone-15-128gb-black/) or as the 'category/slug' shorthand (mobilni-telefony/apple-iphone-15-128gb-black). Every `search` row hands you both, as `url` and `product`. A bare slug is not accepted: www.heureka.cz/<slug>/ answers 404 — the category subdomain is part of the address, and guessing it would return a confident wrong product.
- `market` (enum, optional, default "cz") — Which Heureka storefront to read. The two are separate catalogues with separate shops and currencies: a product URL from one market is not valid in the other. [one of: cz, sk]

**Returns:** product{product, title, url, brand, price_min, price_max, currency, offer_count (Heureka's own published count), rating, review_count} + offers[]{position, offer_id, seller{name, domain, rating_percent, rating (0-5, null for a shop Heureka has not scored), rating_scale, rating_count, logo}, price, price_display, currency, availability, delivery, free_delivery, offer_title, offer_url} + count, cheapest, most_expensive, offer_count_published

**Example request body:**
```json
{
  "product": "mobilni-telefony/apple-iphone-15-128gb-black"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=heureka
- Human docs page: https://reefapi.com/docs/heureka
- Overview page: https://reefapi.com/heureka-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
