Veřejné API nabídek

Veřejné API je nejjednodušší způsob, jak strojově získávat nabídky z Domonautu. Je určené hlavně jako náhrada klasického scrapování výsledků a detailů, které zbytečně zatěžuje web i samotný scraper. Přes API lze efektivně stáhnout aktuální nabídky, sledovat jejich změny a pracovat také s vybranými AI hodnotami.

Povolené použití a atribuce

Data lze prezentovat nebo použít pro monitoring, analytiku či výzkum. Pokud z dat vzniká veřejný výstup, musí být viditelně uvedeno „Zdroj: Domonaut.cz“ s odkazem na Domonaut. U konkrétní nabídky musí zůstat také odkaz z pole URL.

API není určené k vytvoření kopie Domonautu ani jako náhrada vlastní realitní inzerce. Automatické procházení webových stránek mimo API, pokusy získávat kontaktní údaje nebo hromadné stahování fotografií mohou vést k blokaci. Pole titulniFoto slouží pouze jako náhled nabídky nebo pomůcka pro deduplikaci, nikoli pro vytváření vlastní fotogalerie či archivu fotografií.

Limity

Limit se počítá podle kontaktního e-mailu bez ohledu na způsob použití endpointu. Při překročení limitu API vrátí 429 a hlavičku Retry-After. Doporučený je noční přístup, ideálně v období nejnižší aktivity mezi 02:00 a 05:00. Větší synchronizace spouštějte právě v tomto čase, používejte dávky až 500 záznamů a další stránky načítejte pomocí kurzoru.

Endpoint a způsoby použití

API má jeden endpoint GET https://domonaut.cz/api/offers.php. Podle parametrů ho lze použít třemi způsoby.

Parametry kolekce

Při pokračování stačí poslat cursor a případně limit. Časové okno i stav jsou už uložené v kurzoru. Po dokončení změnového okna použijte jeho query.to jako from dalšího okna. Záznamy přesně na hranici from se mohou záměrně objevit znovu, proto je vhodné je deduplikovat podle ID.

Příklad požadavku

Struktura odpovědi

JSON záměrně zachovává názvy polí používané v databázi Domonautu. Všechna pole nabídky jsou přítomná v každém záznamu; pokud údaj není známý, pro daný typ nemovitosti nedává smysl nebo ho skrylo nastavení soukromí, má hodnotu null. Číselné příznaky se posílají jako 0, 1 nebo null, nikoli jako JSON true/false.

Obálka odpovědi

Kompletní příklad odpovědi

{
  "apiVersion": "1.0",
  "generatedAt": "2026-08-20T01:02:03+02:00",
  "query": {
    "mode": "changes",
    "state": "all",
    "from": "2026-08-19T00:00:00+02:00",
    "to": "2026-08-20T00:00:00+02:00",
    "limit": 500
  },
  "data": [{
    "ID": 46563,
    "username": "inzerent123",
    "typNabidky": "Pronájem",
    "typNemovitosti": "Byt",
    "dispozice": "2+kk",
    "kategorieDomu": null,
    "kategoriePozemku": null,
    "kategorieKomercni": null,
    "stav": "Velmi dobrý",
    "prislusenstviBytu": "Lodžie/Balkon,Výtah,Sklep",
    "prislusenstviDomu": null,
    "prislusenstviKomercni": null,
    "vybavenost": "Částečně vybavený",
    "stavba": "Cihla",
    "vlastnictvi": "Osobní",
    "penb": "C",
    "pokoje": null,
    "room_count_kind": "exact",
    "youtube_url": null,
    "is_reserved": 0,
    "podlazi": 3,
    "podlaziMax": 7,
    "plocha": 58,
    "plochaPozemku": null,
    "popis": "Světlý byt po rekonstrukci.",
    "nastehovani": "2026-09-01",
    "cena": 18000,
    "mena": "Kč",
    "typCeny": null,
    "poznamkaCeny": "+ zálohy na služby",
    "anuita": null,
    "poplatky": 3500,
    "kauce": 36000,
    "provizeAno": 0,
    "provize": null,
    "houseNumber": "123/45",
    "street": "Vinohradská",
    "level10": "Vinohrady",
    "level8": "Praha",
    "level7": "Praha 2",
    "level6": "Hlavní město Praha",
    "level4": "Praha",
    "PSC": "12000",
    "latitude": 50.0755,
    "longitude": 14.4378,
    "created": "2026-08-18",
    "updated": "2026-08-19",
    "archived": null,
    "URL": "https://domonaut.cz/detail/46563",
    "advert_code": "DOMONAUT-ABC123",
    "inzerent": "Jméno Příjmení",
    "titulniFoto": "https://domonaut.cz/img/nabidky/46563/thumbs/1.jpg",
    "offers_ai_suggestions": {
      "poplatky": 3500,
      "minPoplatky": null,
      "kauce": 36000,
      "provize": 0,
      "anuita": null,
      "pets": 1,
      "cats": null,
      "dogs": 1,
      "students": null,
      "sharedHousing": 0,
      "shortTerm": 0,
      "singles": 1,
      "families": null
    }
  }],
  "pagination": {"count": 1, "hasMore": false, "nextCursor": null}
}

Datový slovník nabídky

Typ integer|null, number|null nebo string|null znamená, že pole je v JSON vždy přítomné, ale může být null. Hodnoty příslušenství jsou v jednom řetězci oddělené čárkou bez mezer; pořadí není významové.

Identita a druh nabídky

Vlastnosti nemovitosti

Cena a finanční údaje

Adresa a poloha

Odkazy a životní cyklus

AI návrhy offers_ai_suggestions

Celé pole je null, pokud pro nabídku AI návrhy neexistují. Jinak jde o objekt se všemi následujícími klíči. Jde o automatickou extrakci z textu, nikoli o údaje potvrzené inzerentem; strukturovaná pole nabídky mají před AI návrhy přednost. Finanční AI hodnoty jsou vždy celé Kč bez ohledu na mena nabídky.

Soukromí a kontakty

API nikdy neposkytuje telefon, e-mail ani jiná citlivá data uživatelů. Před odesláním se kontroluje také text nabídky a rozpoznané kontaktní údaje se nahrazují textem [kontakt odstraněn]. Adresa respektuje stejné nastavení soukromí jako při běžném anonymním zobrazení nabídky. Podle volby inzerenta se může skrýt číslo domu a posunout poloha, případně se skryje ulice, katastrální území, PSČ i souřadnice.

Změny API a individuální požadavky

API se může v průběhu času měnit společně s Domonautem a jeho datovým modelem. Za průběžnou kontrolu funkčnosti a aktuálnosti svého scraperu nebo jiné integrace odpovídá její vývojář. K datovým nebo strukturálním změnám může dojít bez předchozího oznámení. O významných změnách API bude informace zaslána na kontaktní e-mail uvedený při identifikaci entity. Tato dokumentace vždy popisuje aktuálně podporovanou podobu API.

Pokud má konkrétní projekt oprávněnou potřebu, kterou současné API nepokrývá, je možné požádat o individuální úpravu nebo rozšíření. Žádosti posílejte přes kontaktní formulář a stručně popište způsob použití a požadovaná data.

Stavové kódy

Chyby mají vždy JSON tvar {"error":{"code":"…","message":"…"}}.