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=2Parametry
| Parametr | Hodnota |
|---|---|
key | Klíč 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. |
stayDate | Noc, 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. |
occupancy | Poč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:
| Stav | Co znamená | Co dělat |
|---|---|---|
ready | Pro pobyt už je načtená cena. Obsahuje ji comparison. | Uveďte ji podle pravidel formulace a odkažte na bookUrl. |
pending | Pro pobyt zatím není načtené nic a právě běží kontrola. | Zeptejte se znovu, jak popisuje oddíl Čekání při pending. |
unavailable | Není 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ód | Kdy | Tělo |
|---|---|---|
200 | Vždy, když je klíč i požadavek v pořádku. | ready, pending nebo unavailable |
400 | Ně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 |
404 | Klíč je neznámý nebo byl nahrazen, nebo je widget hotelu vypnutý. | {"status": "unavailable"} |
405 | Jiná metoda než GET. | Žádné |
502 | Server 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
| Pole | Typ | Význam |
|---|---|---|
status | string | ready, pending nebo unavailable. |
asOf | integer | Jen u ready. Kdy byla načtena nejnovější cena v comparison, v milisekundách unixového času. Nikdy čas vašeho požadavku. |
comparison | object | Jen u ready. Cena hotelu a OTA, vedle kterých smí být zobrazena. |
comparison.currency | string | Měna hotelu jako kód ISO 4217, například EUR. Jsou v ní všechny ceny v porovnání. |
comparison.directPriceMinor | integer | Vlastní cena hotelu za noc v nejmenších jednotkách měny. |
comparison.verdict | string | cheapest, matched nebo direct_only: viz Výsledky. |
comparison.savingMinor | integer | Cena nejlevnější uvedené OTA minus cena hotelu, v nejmenších jednotkách měny. Nula, pokud verdict není cheapest. |
comparison.channels | array | OTA, které se mají ukázat vedle ceny hotelu. Prázdné, když je verdict rovno direct_only. |
comparison.channels[].ota | string | ID dané OTA, například booking nebo expedia. Pro váš kód, nikdy k zobrazení. |
comparison.channels[].label | string | Název OTA k zobrazení, například Booking.com. |
comparison.channels[].priceMinor | integer | Cena OTA za stejnou noc v nejmenších jednotkách měny, pro stejný nebo menší počet hostů než cena hotelu: viz pravidla formulace. |
bookUrl | string | Rezervační stránka hotelu, vždy https. Má ji každá odpověď 200. |
bookUrlTemplate | string nebo null | Adresa 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. |
perks | object | Vlastní 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.from | string | Název, pod kterým se mají výhody uvést: název hotelu nebo kratší název, který hotel dal svému widgetu. |
perks.items | array | Nejvýše dvě výhody, v pořadí, v jakém se mají ukázat. Prázdné, když hotel žádné neukazuje. |
perks.items[].key | string | ID výhody, například breakfast. Pro váš kód, nikdy k zobrazení. |
perks.items[].icon | string | ID ikony, například cup. Pro váš kód, nikdy k zobrazení. |
perks.items[].paths | array | Ikona 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[].label | object | Ná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. |
error | string | Jen u odpovědi 400. Co je na požadavku špatně. |
Výsledky
| Výsledek | Co znamená | Co smíte říct |
|---|---|---|
cheapest | Kaž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_only | Cena 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
priceMinortéto OTA přesně rovnádirectPriceMinor. - U
direct_onlyuveď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 vota. - 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
perksukazujte odděleně od ceny, pod názvem zperks.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žbookUrlTemplatenenínulla znáte datum příjezdu i odjezdu hosta, odkažte místo toho na vyplněnou šablonu, jak to dělástayUrlníže. Nikdy nedopočítávejte datum odjezdu, které host neuvedl, a když šablona žádá{adults}a počet dospělých neznáte, použijtebookUrl.
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/beaconTě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
| Pole | Typ | Význam |
|---|---|---|
key | string | Klíč pro vložení daného hotelu, tentýž, se kterým se stránka ptala kontroly cen. |
view | boolean | true při prvním odeslání zobrazení stránky, false při jeho jediném pozdějším odeslání. |
verdict | string | Jen 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. |
device | string | Jen při prvním odeslání, kde je povinné. mobile, když je obrazovka užší než 768 pixelů, jinak desktop. |
lang | string | Jen při prvním odeslání, kde je povinné. Jazyk prohlížeče, navigator.language, nejvýš 35 znaků. |
shown | boolean | Odpověď ready se ukázala na obrazovce. |
inView | boolean | Aspoň polovina toho, co odpověď ukazuje, byla jednu sekundu bez přerušení ve viewportu, zatímco byla stránka viditelná. |
clicked | boolean | Host 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 (
visibilitychangena hidden nebopagehide), 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
unavailablea 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.
Widget na web
Jak vložit widget pro přímé rezervace od StayParity na web hotelu jedním kódem pro vložení: kód, panel, co uvidí hosté a jakou CSP potřebuje.
Měření widgetu v analytice
Spočítejte v GA4 rezervace přes widget pro přímé rezervace od StayParity: příznak stayparity=1 na odkazu Book direct, segment podle něj a co nikdy nenese.