Heureka API & Scraper: parameters and responses
This is the reference for the 3 Heureka endpoints under /heureka/v1 (search, product/detail and product/offers) and their 5 parameters. Each endpoint lists its parameters, required or optional, with allowed values and defaults, and comes with a cURL, Python and JavaScript call; every response uses the same { ok, data, meta, error } envelope.
Heureka API returns live Heureka data as clean JSON for heureka The primary endpoint, search, returns matching records including row type, the only kind with a usable product address shop offer a single merchants listing with no product page, so product and offer count are null promoted a promoted product whose link is a signed clickthrough, so it has a price and a score and an offer count but no address heureka publishes.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
Developers reach for it when they need to track product listings, prices, availability, variants and reviews without maintaining one-off scraping code or separate API contracts. If you were about to build or fix a Heureka scraper, this API is the maintained alternative — it returns the same data as clean JSON, with the proxies, rotation and anti-bot handling already solved. This page covers the live example, request shape, response shape and available actions: search, product/detail, product/offers. Every request uses the same ReefAPI envelope, one API key and one shared credit pool, so it fits alongside the rest of your data stack.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/heureka/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "iphone 15"
}
}{
"ok": true,
"meta": {
"api": "heureka",
"endpoint": "search",
"mode": "live",
"latency_ms": 13486.4,
"record_count": 15,
"bytes": 3020291,
"cache_hit": false,
"market": "cz",
"pagination": {
"page": 1,
"page_size": 24,
"has_more": false,
"total": null
},
"charged_credits": 1,
"version": "0.1.0",
"request_id": "52d612dc8739473d",
"queue_ms": 1.1,
"fetched_at": "2026-11-03T17:32:18.187Z"
},
"data": {
"results": [
{
"row_type": "product",
"product_id": "1187320213",
"product_uuid": "b12174f4-79b4-576a-8106-bb8d8d82af0a",
"product": "mobilni-telefony/apple-iphone-15-128gb-black",
"title": "Apple iPhone 15 128GB Black",
"url": "https://mobilni-telefony.heureka.cz/apple-iphone-15-128gb-black/",
"image": "https://img-cdn.heureka.group/v1/p/b12174f4-79b4-576a-8106-bb8d8d82af0a.jpg?width=400&height=400",
"offer_count": 17,
"offer_count_display": "v 17 obchodech",
"rating_percent": 93,
"rating": 4.65,
"rating_scale": "0-100 (Heureka's own scale); `rating` is the same score as 0-5 stars",
"review_count": 233,
"category": null,
"category_url": null,
"variant_count_listed": null,
"badges": [
"Top 16"
],
"price_min": 15859,
"price_max": 22400,
"price_min_display": "15 859 Kč",
"price_max_display": "22 400 Kč",
"price_display": "15 859 – 22 400 Kč",
"price_kind": "band",
"price_is_single_offer": false,
"currency": "CZK"
},
{
"row_type": "product",
"product_id": "1339935574",
"product_uuid": "59b0414d-a3d5-59b0-af87-18afee1e1470",
"product": "mobilni-telefony/apple-iphone-15-128gb-blue",
"title": "Apple iPhone 15 128GB Blue",
"url": "https://mobilni-telefony.heureka.cz/apple-iphone-15-128gb-blue/",
"image": "https://img-cdn.heureka.group/v1/p/59b0414d-a3d5-59b0-af87-18afee1e1470.jpg?width=400&height=400",
"offer_count": 19,
"offer_count_display": "v 19 obchodech",
"rating_percent": 93,
"rating": 4.65,
"rating_scale": "0-100 (Heureka's own scale); `rating` is the same score as 0-5 stars",
"review_count": 21,
"category": null,
"category_url": null,
"variant_count_listed": null,
"badges": [
"Top 49"
],
"price_min": 15590,
"price_max": 24235,
"price_min_display": "15 590 Kč",
"price_max_display": "24 235 Kč",
"price_display": "15 590 – 24 235 Kč",
"price_kind": "band",
"price_is_single_offer": false,
"currency": "CZK"
},
{
"row_type": "product",
"product_id": "1187320169",
"product_uuid": "ab2a4023-7546-500f-a271-d15e0f080290",
"product": "mobilni-telefony/apple-iphone-15-256gb-black",
"title": "Apple iPhone 15 256GB Black",
"url": "https://mobilni-telefony.heureka.cz/apple-iphone-15-256gb-black/",
"image": "https://img-cdn.heureka.group/v1/p/ab2a4023-7546-500f-a271-d15e0f080290.jpg?width=400&height=400",
"offer_count": 8,
"offer_count_display": "v 8 obchodech",
"rating_percent": 91,
"rating": 4.55,
"rating_scale": "0-100 (Heureka's own scale); `rating` is the same score as 0-5 stars",
"review_count": 45,
"category": null,
"category_url": null,
"variant_count_listed": null,
"badges": null,
"price_min": 17360,
"price_max": 26355,
"price_min_display": "17 360 Kč",
"price_max_display": "26 355 Kč",
"price_display": "17 360 – 26 355 Kč",
"price_kind": "band",
"price_is_single_offer": false,
"currency": "CZK"
}
],
"count": 15,
"query_heading": "Apple iPhone 15",
"product_count": 8,
"shop_offer_count": 7,
"unreadable_tiles": 2,
"last_page": null,
"total_results": null,
"market": "cz",
"currency": "CZK",
"page": 1,
"sort": "relevance",
"query": "iphone 15"
}
}What the Heureka API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | 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. | Pricing teams call search to search Heureka by keyword and get the matching products. | query, page, sort, market |
| product/detail | 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. | Marketplace operators call product/detail to get the full Heureka product record for one product address. | product, market |
| product/offers | 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. | Catalog enrichment teams call product/offers to get every shop offer Heureka lists for one product. | product, market |
Call search from your stack
curl -X POST https://api.reefapi.com/heureka/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"iphone 15"}'import os
import requests
REEF_KEY = os.environ["REEF_KEY"]
r = requests.post(
"https://api.reefapi.com/heureka/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "iphone 15"
},
timeout=90,
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/heureka/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "iphone 15"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.heureka.search with {"query":"iphone 15"}.Who uses this API and why
- Pricing teams use Heureka to search Heureka by keyword and get the matching products.
- Marketplace operators use Heureka to get the full Heureka product record for one product address.
- Catalog enrichment teams use Heureka to get every shop offer Heureka lists for one product.
Questions developers ask before integrating
What is the Heureka API?
Heureka API is a ReefAPI endpoint group for heureka It returns live JSON through POST requests under /heureka/v1.
Is the Heureka API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Heureka calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Heureka login or account?
No login to Heureka is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Heureka data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Heureka API use?
Heureka actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Heureka from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call heureka actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Heureka API a Heureka scraper?
It is the managed alternative to a DIY Heureka scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same heureka back as clean JSON.
Why does my Heureka scraper keep getting blocked?
Most Heureka scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked calls are free.