Reef AI: ask for any data. Try it
This page is the Heureka parameter reference. What the data is used for, a real sample and pricing are on Heureka API: what you get →
E-commerce & Marketplaces

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.

3 actionsLive JSON1,000 free credits$0.67–$1.50 / 1,000 creditsMCP-ready
Get a free keyOpen in playground

🤖 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.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on .

Captured request
{
  "method": "POST",
  "url": "https://api.reefapi.com/heureka/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "query": "iphone 15"
  }
}
Captured response
{
  "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"
  }
}
Actions

What the Heureka API does

ActionDescriptionConcrete use caseKey params
searchSearch 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/detailThe 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/offersEvery 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
Code samples

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"}'
MCP one-liner
Ask your MCP-connected assistant: call reefapi.heureka.search with {"query":"iphone 15"}.
Use cases

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.
FAQ

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.

docs / heureka

Heureka

Heureka

base /heureka/v13 endpoints
post/heureka/v1/product/detail1 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.

ParameterAllowed / rangeDescription
productrequired—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 = czoptionalcz · skWhich 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.
Try in playground →
post/heureka/v1/product/offers2 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.

ParameterAllowed / rangeDescription
productrequired—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 = czoptionalcz · skWhich 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.
Try in playground →
Built for volume
5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?
We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support
2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance
Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.