API

Heureka API: ceny všech obchodů u jednoho produktu v JSON

Heureka neprovozuje veřejné API, přes které by se dalo číst srovnání cen. Tohle rozhraní čte stránky heureka.cz tak, jak je vidí nakupující, a vrací z nich vyhledávání, kartu produktu a hlavně seznam nabídek: který obchod prodává, za kolik korun, s jakým hodnocením a jak rychle doručí. S API klíčem, který Heureka přiděluje e-shopům (třeba pro službu Ověřeno zákazníky), to nemá nic společného: přes tohle API se do Heureky nic nenahrává ani neodesílá, jen se čte to, co vidí kupující.

Získat klíč zdarma Úplná dokumentace: každý endpoint, každý parametr →

Endpointy

endpoint	Co se vrací	Povinné
search	Vyhledávání podle slova, značky nebo modelu. Na stránku připadá 24 výsledků a Heureka k nim přidává placené pozice, případně článek. U produktu je cenové rozpětí přes všechny obchody (od–do), počet obchodů, hodnocení a počet recenzí. Typ řádku je v `row_type`: product, promoted (placená pozice), shop_offer (nabídka jediného obchodu bez karty) a article (poradenský článek).	query
product/detail	Karta produktu podle adresy: název, značka, popis, galerie, rozpětí ceny podle Heureky, drobečková navigace, kompletní tabulka parametrů a varianty.	product
product/offers	Vlastní srovnání cen: jeden řádek na obchod, od nejlevnějšího. Cena, skóre obchodu na Heurece a z kolika hodnocení vychází, dostupnost, doprava (a zda je zdarma) a název, pod kterým zboží vede sám obchod.	product

Každé volání se účtuje v kreditech. Neúspěšná a blokovaná volání jsou zdarma.

Funkční příklad

Ve výpisu vyhledávání měla pračka Electrolux EWS6426WC u sebe „v 17 obchodech“, `product/offers` vrátil 10 nabídek — přesně tolik, kolik Heureka uvádí na kartě produktu (`offer_count` 10). Číslo z výpisu je jiné počítadlo Heureky (u produktů s variantami sčítá obchody přes všechny varianty), proto ho pro srovnání cen nepoužívejte. Adresu (`product`) berte z řádku vyhledávání; samotný slug bez kategorie Heureka nepřijme.

Požadavek

curl -X POST https://api.reefapi.com/heureka/v1/product/offers \
  -H "x-api-key: VAS_KLIC" \
  -H "content-type: application/json" \
  -d '{"product": "pracky/electrolux-ews6426wc"}'

Odpověď (zkrácená)

{
  "ok": true,
  "data": {
    "product": {
      "product": "pracky/electrolux-ews6426wc",
      "title": "Electrolux EWS6426WC",
      "brand": "Electrolux",
      "price_min": 7599,
      "price_max": 9990,
      "currency": "CZK",
      "offer_count": 10,
      "rating": 4.75,
      "review_count": 10
    },
    "offers": [
      ...,
      {
        "position": 2,
        "seller": { "name": "Allegro.cz", "rating_percent": 94, "rating": 4.7, "rating_count": 73539 },
        "price": 7739,
        "price_display": "7 739 Kč",
        "availability": "Skladem",
        "delivery": "Doprava od 599 Kč",
        "free_delivery": false,
        "offer_title": "Volně stojící pračka ELECTROLUX PROFESSIONAL EWS6426WC"
      },
      {
        "position": 9,
        "seller": { "name": "elektrocz.com", "rating_percent": 93, "rating": 4.65, "rating_count": 15648 },
        "price": 8170,
        "price_display": "8 170 Kč",
        "availability": "Skladem",
        "delivery": "Doprava zdarma",
        "free_delivery": true,
        "offer_title": "Pračka Electrolux EWS6426WC"
      },
      ...
    ],
    "cheapest": 7599,
    "most_expensive": 8170
  },
  "meta": { "record_count": 10, "market": "cz", "offers_published_by_source": 10, "cache_hit": false, "mode": "live" }
}

Heureka scraper: na čem si vlastní kód vyláme zuby

Heureka.cz má na všech stránkách s obsahem řízenou výzvu Cloudflare: odpověď 403 se stránkou „Checking security“. Neprošel ani jeden z 16 otisků prohlížeče, které jsme zkoušeli, a stejnou odpověď 403 dostalo i běžné české domácí připojení s obyčejným Chromem. Kdo začne s vlastním skriptem, uvidí tuhle stránku dřív než první cenu.

Druhá past jsou přesměrování. Hledání „lego“ Heureka přesměruje na lego.heureka.cz a na „pračka“ jsme dostali rovnou výpis kategorie Pračky. HTTP klient, který přesměrování sleduje automaticky, nepřenese na novou subdoménu cookie, pošle hlavičky, jaké by prohlížeč neposlal, a dostane znovu 403, takže to vypadá, jako by se ochrana vrátila. Engine proto přesměrování prochází krok za krokem sám. Podobně zrádná je neexistující karta: nevrací 404, ale přesměruje na stránku hledání se stavem 200, a skutečná stránka 404 má 1,4 MB, takže kontrola podle velikosti odpovědi tu selže.

U nabídek Heureka propagované obchody opakuje nad seznamem. Na referenčním produktu bylo v HTML 14 bloků nabídek, skutečných nabídek 10; po odstranění duplicit číslo sedí s tím, co Heureka sama uvádí jako počet nabídek. Kdo počítá průměrnou cenu přímo z HTML, má ji posunutou k obchodům, které si zaplatily lepší místo.

This page in English →Úplná dokumentace: každý endpoint, každý parametr →

Další dokumentace v češtině

Omezení a poctivé poznámky

Heureka toto rozhraní neprovozuje ani nepodporuje a žádnou smlouvu nebo partnerství s ní nemáme.
Vývoj ceny (graf historie) API nevrací. Kdo chce hlídat cenu, musí si výsledky `product/offers` ukládat sám, třeba jednou denně.
Obchod, který Heureka zatím neohodnotila, má `rating` null a v `rating_count` jen počet recenzí; nulu za něj nedosazujeme. V našem měření to byly 2 z 10 nabídek.
`price_max` je horní hranice, kterou publikuje Heureka, a nemusí se shodovat s nejdražší vypsanou nabídkou: u pračky z příkladu 9 990 Kč proti 8 170 Kč.
Použitelnou adresu mají jen řádky typu product; u promoted, shop_offer a article je `product` null. Vyhledávání nevrací celkový počet výsledků, jen `last_page` ze stránkování Heureky. U dotazu „pračka“, který Heureka přesměrovala rovnou do kategorie, zůstala `category` prázdná ve všech 30 řádcích.
Odkaz na obchod je proklik přes Heureku (exit-click); přímou adresu zboží v e-shopu, EAN ani počet kusů skladem Heureka nezveřejňuje.
Data se pokaždé čtou živě a trvá to: vyhledávání nám odpovědělo za 12 s, nabídky za 5 s. Slovenská Heureka funguje přes `"market": "sk"` (ceny v EUR), je ale prověřená výrazně méně než heureka.cz.