Přejít na obsah

API pro kontrolu cen

Načtěte do chatbota nebo widgetu výsledek, z něhož vychází widget hotelu od StayParity: jeden GET, přímá cena a stejně drahé či dražší OTA, nikdy levnější.

Kontrola cen odpovídá na jednu otázku pro jednu noc: kolik účtuje vlastní web hotelu a je to nejlepší cena, jakou lze najít? Čte stejná data jako hotelový widget na web, takže ji může uvést i bot pro WhatsApp, chatovací asistent nebo widget, který si postavíte sami. Uvádí výsledek, který kontrola zjistila. Štítek Nejlepší cena zde ve widgetu je tvrzení samotného hotelu, zobrazuje se u každého výsledku a není součástí odpovědi.

Nepotřebuje účet ani API token, jen klíč pro vložení daného hotelu, a neprozradí nic, co by host na webu hotelu nemohl vidět sám. Když některá OTA prodává noc levněji, kontrola cen uvede jen vlastní cenu hotelu, přesně jako u noci, kterou žádná OTA neprodává. Nikdo, ani vy, tak z odpovědi nepozná, jestli je některá OTA levnější než hotel.

Požadavek

Jeden GET se třemi parametry v query stringu:

GET https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=2027-06-14&occupancy=2

Parametry

ParametrHodnota
keyKlíč pro vložení daného hotelu, wk_…: hodnota data-hotel v jeho kódu pro vložení widgetu, v portálu pod Nastavení → Widget na web.
stayDateNoc, zadaná jako její datum příjezdu ve tvaru YYYY-MM-DD. Vždy jedna noc: u delšího pobytu se ptejte na jeho první noc.
occupancyPočet dospělých, od 1 do 10.

Kontrola cen funguje, jen dokud je widget hotelu zapnutý. Hotel ho přitom nemusí mít zobrazený na žádné stránce.

Odpovědi

Každá odpověď je JSON s polem status. Odpověď 200 nese jednu ze tří hodnot:

StavCo znamenáCo dělat
readyPro pobyt už je načtená cena. Obsahuje ji comparison.Uveďte ji podle pravidel formulace a odkažte na bookUrl.
pendingPro pobyt zatím není načtené nic a právě běží kontrola.Zeptejte se znovu, jak popisuje oddíl Čekání při pending.
unavailableNení co uvést a teď nemůže začít žádná kontrola: hotel je ve StayParity pozastavený, pro tento počet dospělých se nekontroluje, noc je v časovém pásmu hotelu už minulá nebo dál v budoucnosti, než kam tarif hotelu kontroluje, jeho kontroly na daný den jsou vyčerpané, nebo poslední kontrola nenašla žádnou cenu.Odpovězte bez ceny a odkažte na bookUrl. U počtu dospělých, pro který se hotel nekontroluje, se můžete zeptat znovu pro 2 a uvést, že kontrola proběhla pro 2 dospělé.

Stav HTTP

KódKdyTělo
200Vždy, když je klíč i požadavek v pořádku.ready, pending nebo unavailable
400Některý parametr chybí nebo má špatný tvar, occupancy je mimo rozsah 1 až 10, nebo noc už skončila všude na Zemi.{"status": "unavailable", "error": "…"}, chyba v angličtině pro toho, kdo požadavek napsal
404Klíč je neznámý nebo byl nahrazen, nebo je widget hotelu vypnutý.{"status": "unavailable"}
405Jiná metoda než GET.Žádné
502Server widgetu se nespojil se StayParity. Zkuste to později znovu.{"status": "unavailable"}

Jakýkoli jiný kód, tělo, které není JSON, nebo chybu sítě berte jako žádnou odpověď.

Pole

PoleTypVýznam
statusstringready, pending nebo unavailable.
asOfintegerJen u ready. Kdy byla načtena nejnovější cena v comparison, v milisekundách unixového času. Nikdy čas vašeho požadavku.
comparisonobjectJen u ready. Cena hotelu a OTA, vedle kterých smí být zobrazena.
comparison.currencystringMěna hotelu jako kód ISO 4217, například EUR. Jsou v ní všechny ceny v porovnání.
comparison.directPriceMinorintegerVlastní cena hotelu za noc v nejmenších jednotkách měny.
comparison.verdictstringcheapest, matched nebo direct_only: viz Výsledky.
comparison.savingMinorintegerCena nejlevnější uvedené OTA minus cena hotelu, v nejmenších jednotkách měny. Nula, pokud verdict není cheapest.
comparison.channelsarrayOTA, které se mají ukázat vedle ceny hotelu. Prázdné, když je verdict rovno direct_only.
comparison.channels[].otastringID dané OTA, například booking nebo expedia. Pro váš kód, nikdy k zobrazení.
comparison.channels[].labelstringNázev OTA k zobrazení, například Booking.com.
comparison.channels[].priceMinorintegerCena OTA za stejnou noc v nejmenších jednotkách měny, pro stejný nebo menší počet hostů než cena hotelu: viz pravidla formulace.
bookUrlstringRezervační stránka hotelu, vždy https. Má ji každá odpověď 200.
bookUrlTemplatestring nebo nullAdresa vyhledávání v rezervačním systému hotelu s {checkin}, {checkout}, {nights} a {adults}, které doplníte vy: data ve tvaru YYYY-MM-DD, noci a dospělé jako celá čísla. null, pokud hotel žádnou neuložil. Má ji každá odpověď 200.
perksobjectVlastní výhody hotelu pro hosta, který rezervuje přímo, například snídaně, uvedené pod názvem hotelu. Má je každá odpověď 200. Ukažte je odděleně od ceny: viz pravidla formulace.
perks.fromstringNázev, pod kterým se mají výhody uvést: název hotelu nebo kratší název, který hotel dal svému widgetu.
perks.itemsarrayNejvýše dvě výhody, v pořadí, v jakém se mají ukázat. Prázdné, když hotel žádné neukazuje.
perks.items[].keystringID výhody, například breakfast. Pro váš kód, nikdy k zobrazení.
perks.items[].iconstringID ikony, například cup. Pro váš kód, nikdy k zobrazení.
perks.items[].pathsarrayIkona jako data cest SVG na mřížce 24 na 24, jedna až tři cesty, kreslené tahem se zakulacenými konci a bez výplně.
perks.items[].labelobjectNázev výhody k zobrazení, s jazykem jako klíčem: en, es, el, it, de a cs. Mohou přibýt další jazyky, proto použijte jazyk hosta, když je k dispozici, a jinak en.
errorstringJen u odpovědi 400. Co je na požadavku špatně.

Výsledky

VýsledekCo znamenáCo smíte říct
cheapestKaždá uvedená OTA je dražší než přímá rezervace.Úsporu, savingMinor, oproti nejlevnější uvedené OTA a cenu každé OTA.
matchedŽádná uvedená OTA není levnější a aspoň jedna je stejně drahá jako hotel.„Stejná cena jako na“ dané OTA jen tehdy, když se její priceMinor rovná directPriceMinor.
direct_onlyCena hotelu je jediné, co lze říct: některá OTA může být levnější, může prodávat za jiných podmínek, nebo noc vůbec neprodávat.Jen cenu hotelu.

Příklady

Noc, kdy je hotel nejlevnější:

{
  "status": "ready",
  "asOf": 1791547200000,
  "comparison": {
    "currency": "EUR",
    "directPriceMinor": 14200,
    "verdict": "cheapest",
    "savingMinor": 1600,
    "channels": [
      { "ota": "booking", "label": "Booking.com", "priceMinor": 15800 },
      { "ota": "expedia", "label": "Expedia", "priceMinor": 16100 }
    ]
  },
  "bookUrl": "https://stayparity.com/book-demo",
  "bookUrlTemplate": null,
  "perks": {
    "from": "Hotel Aurora",
    "items": [
      {
        "key": "breakfast",
        "icon": "cup",
        "paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
        "label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
      },
      {
        "key": "late-checkout",
        "icon": "clock",
        "paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
        "label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
      }
    ]
  }
}

Noc, pro kterou lze uvést jen cenu hotelu:

{
  "status": "ready",
  "asOf": 1791547200000,
  "comparison": {
    "currency": "EUR",
    "directPriceMinor": 14200,
    "verdict": "direct_only",
    "savingMinor": 0,
    "channels": []
  },
  "bookUrl": "https://stayparity.com/book-demo",
  "bookUrlTemplate": null,
  "perks": {
    "from": "Hotel Aurora",
    "items": [
      {
        "key": "breakfast",
        "icon": "cup",
        "paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
        "label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
      },
      {
        "key": "late-checkout",
        "icon": "clock",
        "paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
        "label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
      }
    ]
  }
}

Noc, která se ještě kontroluje:

{
  "status": "pending",
  "bookUrl": "https://stayparity.com/book-demo",
  "bookUrlTemplate": null,
  "perks": {
    "from": "Hotel Aurora",
    "items": [
      {
        "key": "breakfast",
        "icon": "cup",
        "paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
        "label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
      },
      {
        "key": "late-checkout",
        "icon": "clock",
        "paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
        "label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
      }
    ]
  }
}

Čekání při pending

První požadavek na noc, na kterou se zatím nikdo neptal, spustí kontrolu a odpoví pending. Většina kontrol skončí během několika sekund, některé trvají déle. Zeptejte se znovu po 2 sekundách, pak po 3, pak po 5, pak každých 8, a po 8 požadavcích nebo 30 sekundách přestaňte, podle toho, co nastane dřív. Widget čeká stejně. Pokud je odpověď i pak pending, odpovězte bez ceny a odkažte na bookUrl; požadavek o pár minut později cenu obvykle najde.

Odpověď pending nikdy neukládejte do mezipaměti a neptejte se na noc, na kterou se vás nikdo neptal: každá kontrola se odečte z denního limitu hotelu.

Aktuálnost a mezipaměť

asOf říká, kdy byla cena načtena. Ceny hotelu se kontrolují podle rozvrhu a kontrola cen vrací tu nejnovější, kterou má, takže cena může být stará hodiny i dny. Požadavek spustí novou kontrolu, jen když je cena pro jeho pobyt zastaralá, tedy starší než rozestup, který rozvrh pro danou noc stanoví: 1 den pro dnešní noc a 6 nocí po ní, 4 dny až do noci 30 a 20 dní pro pozdější noci. Cena noci, která je měsíce dopředu, může být stará 15 dní a nic nespustí. Když požadavek kontrolu spustí, dokud má hotel kontroly k dispozici, dostane i tak starou cenu a novou dostane až pozdější požadavek. Vždy uveďte, jak stará cena je, jako to dělá widget textem „Zkontrolováno před 12 min“ i příklad níže, a pokud je asOf pozdější než vaše hodiny, použijte aktuální čas.

Odpovědi sdílí všichni, kdo se ptají na stejnou noc, včetně widgetu hotelu. Odpověď ready zůstává v mezipaměti 60 sekund a pak se ještě až 3 600 sekund vydává, zatímco se obnovuje, takže cena se k vám může dostat až 61 minut poté, co ji má StayParity: první požadavek po chvíli bez požadavků dostane starší odpověď a další už tu novou. unavailable a 404 zůstávají v mezipaměti 60 sekund, pending a 400 v ní nezůstávají vůbec. Totéž říká hlavička Cache-Control a vaše vlastní mezipaměť se jí může řídit.

Pravidla formulace

Formulujte odpovědi podle výsledku, ne podle štítku widgetu:

  • Úsporu, nebo že je přímá rezervace nejlevnější, uvádějte jen u cheapest.
  • „Stejná cena jako na“ dané OTA pište jen tehdy, když se priceMinor této OTA přesně rovná directPriceMinor.
  • U direct_only uveďte cenu hotelu a nic o OTA. Netvrďte, že žádná OTA není levnější, ani že nějaká levnější je.
  • OTA uvádějte podle jejího label, nikdy podle ID v ota.
  • Ceny uvádějte tak, jak přišly: za noc, v currency. Nepřepočítávejte je a nic k nim nepřičítejte.
  • Cena platí pro pokoj, ve kterém může spát aspoň dotazovaný počet dospělých, a někdy pro pokoj, ve kterém může spát víc osob, u hotelu i u OTA stejně. Cena uvedené OTA platí pro stejný nebo menší počet hostů než cena hotelu, nikdy větší. Uveďte, pro koho byl dotaz, například „pro 2 dospělé“, a netvrďte, že je pokoj přesně pro tolik osob.
  • Výhody z perks ukazujte odděleně od ceny, pod názvem z perks.from, ať je odpověď jakákoli. Slibuje je hotel, ne StayParity, a kontrola cen je neověřuje: nikdy žádnou nezapočítávejte do ceny ani do úspory a nikdy nepřidávejte výhodu, kterou odpověď neuvádí.
  • Pro rezervaci vždy odkažte na bookUrl, ať je odpověď jakákoli. Když bookUrlTemplate není null a znáte datum příjezdu i odjezdu hosta, odkažte místo toho na vyplněnou šablonu, jak to dělá stayUrl níže. Nikdy nedopočítávejte datum odjezdu, které host neuvedl, a když šablona žádá {adults} a počet dospělých neznáte, použijte bookUrl.

Loga prodejců

Logo, které widget hotelu ukazuje pro danou OTA, je na https://badge.stayparity.com/widget/marks/{ota}.svg podle ID kanálu v ota: čtvercové SVG s dlaždicí a znakem OTA tak, jak je widget kreslí, o velikosti 22 pixelů, pokud mu nenastavíte jinou. Pro OTA, pro kterou widget logo nemá, odpovídá adresa 404, takže v tom případě zobrazte vlastní zástupný obrázek, tak jako widget ukazuje první písmeno názvu. Loga odpovídají jakémukoli originu a neobsahují žádné skripty. Každé zůstává v mezipaměti jeden den a pak se ještě až 30 dní vydává, zatímco se obnovuje, jak říká jeho hlavička Cache-Control. Pokud web posílá hlavičku Content-Security-Policy, povolte origin v img-src.

<img src="https://badge.stayparity.com/widget/marks/booking.svg" alt="" width="22" height="22">

Uvedení zdroje

Když tyto ceny uvádí váš bot nebo vlastní widget, prosíme, abyste je označili stejně jako widget hotelu: znakem StayParity a za ním textem „Ceny kontroluje StayParity“ s odkazem na https://stayparity.com. Znak je na https://badge.stayparity.com/widget/brand/mark.svg pro světlé pozadí a na https://badge.stayparity.com/widget/brand/mark-dark.svg pro tmavé. Vydává se stejně jako loga prodejců. Bot, který odpovídá textem, může končit slovy „Ceny kontroluje StayParity · stayparity.com“, jako to v angličtině dělá příklad níže. Není to podmínka: kontrola cen bez uvedení zdroje odpovídá stejně.

<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Ceny kontroluje Stay<b>Parity</b></a>

Počítání zobrazení

Stránka Widget hotelu ve StayParity počítá, jak často hosté vidí jeho widget. Stránka, která z kontroly cen vykresluje vlastní widget, může počítat i jeho zobrazení a stránka Widget je ukazuje odděleně od zobrazení widgetu hotelu, v sekci Váš vlastní widget: zobrazení, v kolika z nich se ukázala cena, v kolika byla na obrazovce a v kolika host klikl na Book direct, podle výsledku, zařízení a jazyka. Počítání je nepovinné: kontrola cen bez něj odpovídá stejně.

Stránka posílá malé tělo na adresu:

POST https://badge.stayparity.com/widget/beacon

Tělo pošlete jako řetězec, který prohlížeč odešle jako text/plain, takže nepotřebuje CORS preflight. Tělo jakéhokoli jiného typu se zahodí.

Tělo

PoleTypVýznam
keystringKlíč pro vložení daného hotelu, tentýž, se kterým se stránka ptala kontroly cen.
viewbooleantrue při prvním odeslání zobrazení stránky, false při jeho jediném pozdějším odeslání.
verdictstringJen při prvním odeslání, kde je povinné. verdict poslední odpovědi ready, kterou stránka ukázala, nebo none, pokud žádnou neukázala.
devicestringJen při prvním odeslání, kde je povinné. mobile, když je obrazovka užší než 768 pixelů, jinak desktop.
langstringJen při prvním odeslání, kde je povinné. Jazyk prohlížeče, navigator.language, nejvýš 35 znaků.
shownbooleanOdpověď ready se ukázala na obrazovce.
inViewbooleanAspoň polovina toho, co odpověď ukazuje, byla jednu sekundu bez přerušení ve viewportu, zatímco byla stránka viditelná.
clickedbooleanHost klikl na odkaz nebo tlačítko Book direct vykreslené s odpovědí, ať vede na bookUrl, nebo otevírá vlastní rezervaci hotelu.

Vynechaný příznak znamená false a pozdější odeslání musí nést aspoň jeden příznak s hodnotou true. Tělo s polem, které v tabulce není, nebo s polem ve špatném tvaru nezapočítá nic.

První odeslání zobrazení stránky:

{
  "key": "wk_0123456789abcdef0123456789abcdef",
  "view": true,
  "verdict": "cheapest",
  "device": "desktop",
  "lang": "en-GB",
  "shown": true,
  "inView": true
}

Jeho pozdější odeslání, pro příznak, který se mezitím zapnul:

{
  "key": "wk_0123456789abcdef0123456789abcdef",
  "view": false,
  "clicked": true
}

Kdy odesílat

  • Zobrazení počítejte, jakmile se stránka zeptala kontroly cen aspoň na jeden pobyt. Stránka, která se nikdy nezeptala, nezapočítá nic.
  • První odeslání proveďte, když se stránka skryje (visibilitychange na hidden nebo pagehide), nebo když host klikne na Book direct, podle toho, co nastane dřív.
  • Proveďte nejvýš jedno pozdější odeslání, jen s příznaky, které se mezitím zapnuly, v nejbližším z těchto okamžiků.
  • Veďte jedno počítadlo na klíč a stránku, aby se widget vykreslený dvakrát započítal jednou.
  • Nic neodesílejte, když je nastavený navigator.webdriver.

Origin stránky

Beacon započítá zobrazení pro hostitele z hlavičky Origin požadavku, kterou nastavuje prohlížeč. Posílejte ho proto ze stránky, nikdy ze serveru: server žádný Origin neposílá a jeho beacony nezapočítají nic. Hostitel, který ve StayParity nepatří k webům hotelu, se na stránce Widget započítá v sekci Ostatní weby a localhost se nezapočítá nikdy.

Posílejte ho přes fetch s keepalive, jak to dělá příklad níže. navigator.sendBeacon funguje ve většině prohlížečů, ale Safari ho pošle bez Origin, když je Referrer-Policy stránky no-referrer nebo same-origin, a pak se nezapočítá nic.

Limity

  • Tělo má nejvýš 1 KiB.
  • Jedna adresa může poslat 30 beaconů za minutu, společně s widgetem hotelu.
  • Hotel za svůj den započítá nejvýš 5 000 beaconů, společně se svým widgetem. Potom se až do půlnoci podle času hotelu nezapočítá nic.

Kontrola počítání

Beacon vždy odpoví 204 bez těla, ať se s tím, co jste poslali, stalo cokoli, takže jeho odpověď vám nic neřekne. Počítání zkontrolujete tak, že stránku na webu hotelu otevřete, opustíte ji a ve StayParity se podíváte na stránce Widget v sekci Váš vlastní widget na kartu Dnes.

Příklad

V JavaScriptu pro prohlížeč. Zavolejte pageView, když se stránka poprvé zeptá kontroly cen s klíčem, shown, když vykreslí odpověď ready, a clicked, když host klikne na Book direct:

const BEACON = "https://badge.stayparity.com/widget/beacon";
const FLAGS = ["shown", "inView", "clicked"];
const views = new Map();

// The page view for a key, one per key however often the page asks.
function pageView(key) {
  if (!views.has(key)) views.set(key, { key, verdict: "none", on: new Set(), sent: null, done: false });
  return views.get(key);
}

function send(view) {
  if (view.done || navigator.webdriver) return;
  const flags = FLAGS.filter((flag) => view.on.has(flag) && !view.sent?.has(flag));
  let body;
  if (view.sent === null) {
    body = {
      key: view.key,
      view: true,
      verdict: view.verdict,
      device: screen.width < 768 ? "mobile" : "desktop",
      lang: navigator.language.slice(0, 35),
    };
    view.sent = new Set();
  } else if (flags.length > 0) {
    body = { key: view.key, view: false };
    view.done = true;
  } else {
    return;
  }
  for (const flag of flags) {
    body[flag] = true;
    view.sent.add(flag);
  }
  fetch(BEACON, { method: "POST", body: JSON.stringify(body), keepalive: true }).catch(() => {});
}

// A ready answer drawn in element: in view once half of it stays on screen for a second.
function shown(view, element, verdict) {
  view.verdict = verdict;
  view.on.add("shown");
  let timer;
  let ratio = 0;
  const arm = () => {
    clearTimeout(timer);
    if (ratio < 0.5 || document.visibilityState !== "visible" || view.on.has("inView")) return;
    timer = setTimeout(() => {
      view.on.add("inView");
      observer.disconnect();
    }, 1000);
  };
  const observer = new IntersectionObserver(([entry]) => {
    ratio = entry.intersectionRatio;
    arm();
  }, { threshold: 0.5 });
  observer.observe(element);
  document.addEventListener("visibilitychange", arm);
}

// Book direct may leave the page, so the click sends at once.
function clicked(view) {
  view.on.add("clicked");
  send(view);
}

const sendAll = () => views.forEach(send);
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") sendAll();
});
window.addEventListener("pagehide", sendAll);

// const view = pageView("wk_…"); then shown(view, list, answer.comparison.verdict) and clicked(view)

Peníze

Každá cena je celé číslo v nejmenších jednotkách měny podle ISO 4217: 14200 v EUR je 142,00 €. ISK, JPY a KRW žádnou menší jednotku nemají, takže 14200 v JPY je 14 200 ¥. Každá další měna, kterou kontrola cen posílá, má dvě desetinná místa. Desetinná místa berte z tohoto pravidla, ne z formátovače měn vaší platformy: formátovače se neshodují a některé dávají HUF a IDR žádná.

Vyzkoušejte si to

Klíč wk_demo odpovídá za Hotel Aurora, ukázkový hotel na ukázkové stránce, s vymyšlenými cenami pro 1 až 4 dospělé a každou noc příštího roku. Nikdy neodpoví pending a nespotřebuje kontroly žádného hotelu, takže ho můžete volat při každém testu:

curl "https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=$(date -u +%F)&occupancy=2"

Kód odpovědí pro bota ve stylu WhatsApp, v JavaScriptu pro Node 18 nebo novější, Deno, Bun nebo prohlížeč. Při pending čeká stejně jako widget, uvádí, jak stará cena je, a dodržuje pravidla formulace. stayUrl vrací odkaz na pobyt hosta:

const API = "https://badge.stayparity.com/widget/comparison";
const WAITS_MS = [2000, 3000, 5000, 8000];
const MAX_REQUESTS = 8;
const BUDGET_MS = 30000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// The answer for one night, or null when there is none to give.
async function priceCheck(key, stayDate, adults) {
  const query = new URLSearchParams({ key, stayDate, occupancy: String(adults) });
  const started = Date.now();
  let answer = null;
  for (let request = 1; request <= MAX_REQUESTS; request++) {
    const response = await fetch(`${API}?${query}`).catch(() => null);
    const body = response?.ok ? await response.json().catch(() => null) : null;
    if (body === null) return answer;
    answer = body;
    if (answer.status !== "pending") return answer;
    const wait = WAITS_MS[Math.min(request, WAITS_MS.length) - 1];
    if (request === MAX_REQUESTS || Date.now() - started + wait > BUDGET_MS) break;
    await sleep(wait);
  }
  return answer;
}

function money(minor, currency) {
  const digits = ["ISK", "JPY", "KRW"].includes(currency) ? 0 : 2;
  const whole = minor % 10 ** digits === 0;
  return new Intl.NumberFormat("en", {
    style: "currency",
    currency,
    minimumFractionDigits: whole ? 0 : digits,
    maximumFractionDigits: digits,
  }).format(minor / 10 ** digits);
}

// How old the price is, from asOf; a stamp ahead of this clock is "just now".
function checkedAgo(asOf) {
  const minutes = Math.floor(Math.max(0, Date.now() - asOf) / 60000);
  if (minutes < 1) return "just now";
  if (minutes < 60) return `${minutes} min ago`;
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return `${hours} h ago`;
  const days = Math.floor(hours / 24);
  return days === 1 ? "1 day ago" : `${days} days ago`;
}

// The hotel's search on the guest's stay, or bookUrl when it has none or needs a value you don't have.
function stayUrl(answer, checkIn, checkOut, adults) {
  if (!answer.bookUrlTemplate || !checkIn || !checkOut) return answer.bookUrl;
  const values = {
    checkin: checkIn,
    checkout: checkOut,
    nights: String(Math.round((Date.parse(checkOut) - Date.parse(checkIn)) / 86400000)),
    adults: adults == null ? null : String(adults),
  };
  let missing = false;
  const url = answer.bookUrlTemplate.replace(/\{(checkin|checkout|nights|adults)\}/g, (_, name) => {
    if (values[name] === null) missing = true;
    return values[name] ?? "";
  });
  return missing ? answer.bookUrl : url;
}

function reply(answer) {
  if (answer === null) return "Sorry, I can't check prices right now.";
  if (answer.status !== "ready") return `Book direct with the hotel: ${answer.bookUrl}`;
  const { currency, directPriceMinor, verdict, savingMinor, channels } = answer.comparison;
  const direct = money(directPriceMinor, currency);
  const cheapest = channels.reduce((best, c) => (best && best.priceMinor <= c.priceMinor ? best : c), null);
  let text = `${direct} per night, booking direct.`;
  if (verdict === "cheapest" && savingMinor > 0 && cheapest) {
    text = `${direct} per night booking direct, ${money(cheapest.priceMinor, currency)} on ${cheapest.label}. You save ${money(savingMinor, currency)}.`;
  } else if (verdict === "matched" && cheapest?.priceMinor === directPriceMinor) {
    text = `${direct} per night booking direct, the same as on ${cheapest.label}.`;
  }
  return `${text} Checked ${checkedAgo(answer.asOf)}.\nBook: ${answer.bookUrl}\nPrice check by StayParity · stayparity.com`;
}

// reply(await priceCheck("wk_demo", "2027-06-14", 2))
// stayUrl(answer, "2027-06-14", "2027-06-16", 2)

Limity

  • Požadavek, který spustí kontrolu, spotřebuje jednu ze 40 kontrol hotelu na den UTC, o které se hotel dělí se svým widgetem. Odpověď z mezipaměti nebo z už načtené ceny nespotřebuje nic. Když jsou kontroly vyčerpané, noci bez ceny odpovídají až do půlnoci UTC unavailable a noci s cenou si ponechají poslední cenu.
  • Klíč je veřejný: je na webu hotelu. Kdo ho má, dostane stejné odpovědi jako vy, a hotel ho může kdykoli nahradit. Poté starý klíč odpovídá 404.
  • Klíč používejte jen se souhlasem hotelu. Funguje, jen dokud je widget hotelu zapnutý.

Z prohlížeče

Kontrola cen odpovídá jakémukoli originu (Access-Control-Allow-Origin: *) a nepotřebuje cookies, takže ji váš widget může volat přímo ze stránky. Posílejte prostý GET bez vlastních hlaviček: na CORS preflight kontrola cen neodpovídá. Pokud web posílá hlavičku Content-Security-Policy, povolte origin API:

connect-src https://badge.stayparity.com;

Verzování

Toto je verze 1 kontroly cen a taková zůstane: žádné pole se nepřejmenuje, neodstraní ani nezmění typ, nepřibude žádný stav ani výsledek a každý si ponechá svůj význam. Mohou přibýt pole a měny, takže pole, která neznáte, ignorujte. Změna, která by rozbila váš kód, vyjde na nové cestě a oznámíme ji na této stránce. Totéž platí pro tělo beaconu: mohou v něm přibýt nepovinná pole, ale žádné pole se nestane povinným, nepřejmenuje se ani neodstraní a žádné tělo, které se dnes započítá, se nepřestane započítávat.

Tentýž kontrakt i s těmito příklady najdete v popisu OpenAPI 3.1.

Na této stránce