API di verifica dei prezzi
Porta nel tuo chatbot o nella tua app l’esito del widget StayParity di un hotel: un GET, la tariffa diretta e le OTA che eguaglia o batte, mai una discrepanza.
L’API di verifica dei prezzi risponde a una domanda per una notte: quanto chiede il sito dell’hotel stesso, ed è il prezzo migliore disponibile? Usa gli stessi dati del Widget prenotazioni dell’hotel, così anche un bot di WhatsApp, un assistente di chat o un widget che sviluppi tu possono riportarla. Riporta il risultato trovato dal controllo. Il sigillo Miglior prezzo qui del widget è un’affermazione dell’hotel stesso, compare con ogni risultato e non fa parte della risposta.
Non servono un account né un token API, solo la chiave dell’hotel, e non dice nulla che un ospite sul sito dell’hotel non possa vedere. Quando un’OTA vende la notte a meno, dà solo la tariffa dell’hotel, esattamente come per una notte che nessuna OTA vende, quindi né tu né altri potete riconoscere una discrepanza dalla sua risposta.
Richiesta
Un GET con tre parametri di query:
GET https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=2027-06-14&occupancy=2Parametri
| Parametro | Valore |
|---|---|
key | La chiave dell’hotel, wk_…: il valore di data-hotel nel codice del suo widget, in Impostazioni → Widget prenotazioni nell’applicazione. |
stayDate | La notte, come data di arrivo in formato YYYY-MM-DD. Una sola notte: per un soggiorno più lungo, chiedi la prima. |
occupancy | Il numero di adulti, da 1 a 10. |
L’API di verifica dei prezzi funziona solo mentre il widget dell’hotel è attivo. Non è necessario che l’hotel mostri il widget in una pagina.
Risposte
Ogni risposta è un JSON con uno status. Una risposta 200 ne contiene uno di questi tre:
| Stato | Che cosa significa | Che cosa fare |
|---|---|---|
ready | È stato rilevato un prezzo per il soggiorno. Si trova in comparison. | Citalo secondo le regole di formulazione e inserisci un link a bookUrl. |
pending | Per il soggiorno non è ancora stato rilevato nulla e c’è un controllo in corso. | Chiedi di nuovo, come spiegato in Gestisci le risposte in sospeso. |
unavailable | Non c’è nulla da citare e ora non può partire nessun controllo: il monitoraggio dell’hotel è sospeso in StayParity, l’hotel non viene controllato per quel numero di adulti, la notte è già passata nel fuso orario dell’hotel o è oltre i giorni controllati dal suo piano, i controlli del giorno sono esauriti oppure l’ultimo controllo non ha trovato alcun prezzo. | Rispondi senza prezzo e inserisci un link a bookUrl. Per un numero di adulti che l’hotel non controlla, puoi chiedere di nuovo per 2 e indicare che hai controllato il prezzo per 2 adulti. |
Codici HTTP
| Codice | Quando | Corpo |
|---|---|---|
200 | Sempre, quando la chiave e la richiesta sono valide. | ready, pending o unavailable |
400 | Un parametro manca o ha un formato non valido, occupancy è fuori dall’intervallo da 1 a 10 oppure la notte è già passata ovunque sulla Terra. | {"status": "unavailable", "error": "…"}, con l’errore in inglese per chi ha scritto la richiesta |
404 | La chiave è sconosciuta o è stata sostituita, oppure il widget dell’hotel è disattivato. | {"status": "unavailable"} |
405 | Un metodo diverso da GET. | Nessuno |
502 | Il server del widget non è riuscito a raggiungere StayParity. Riprova più tardi. | {"status": "unavailable"} |
Considera qualsiasi altro codice, un corpo che non è JSON o un errore di rete come assenza di risposta.
Campi
| Campo | Tipo | Significato |
|---|---|---|
status | string | ready, pending o unavailable. |
asOf | integer | Solo con ready. Quando è stato rilevato il prezzo più recente in comparison, in millisecondi Unix. Mai l’ora della tua richiesta. |
comparison | object | Solo con ready. La tariffa dell’hotel e le OTA accanto a cui può essere mostrata. |
comparison.currency | string | La valuta dell’hotel, codice ISO 4217 come EUR. Tutti i prezzi del confronto sono in questa valuta. |
comparison.directPriceMinor | integer | La tariffa dell’hotel stesso per la notte, in unità minori. |
comparison.verdict | string | cheapest, matched o direct_only: vedi Risultati. |
comparison.savingMinor | integer | Il prezzo dell’OTA elencata più economica meno la tariffa dell’hotel, in unità minori. Zero se verdict non è cheapest. |
comparison.channels | array | Le OTA da mostrare accanto alla tariffa dell’hotel. Vuoto quando verdict è direct_only. |
comparison.channels[].ota | string | L’identificatore dell’OTA, come booking o expedia. Per il tuo codice, mai da mostrare. |
comparison.channels[].label | string | Il nome dell’OTA da mostrare, come Booking.com. |
comparison.channels[].priceMinor | integer | Il prezzo dell’OTA per la stessa notte, in unità minori, per un numero di ospiti pari o inferiore a quello del prezzo dell’hotel: vedi le regole di formulazione. |
bookUrl | string | La pagina di prenotazione dell’hotel, sempre https. È presente in ogni risposta 200. |
bookUrlTemplate | string o null | La ricerca di prenotazione dell’hotel, con {checkin}, {checkout}, {nights} e {adults} da compilare: le date nel formato YYYY-MM-DD, le notti e gli adulti come numeri interi. null se l’hotel non ne ha salvata nessuna. È presente in ogni risposta 200. |
perks | object | I vantaggi propri dell’hotel per un ospite che prenota direttamente, come la colazione, attribuiti all’hotel. È presente in ogni risposta 200. Mostrali separati dal prezzo: vedi le regole di formulazione. |
perks.from | string | Il nome a cui attribuire i vantaggi: il nome dell’hotel, o quello più breve che ha dato al suo widget. |
perks.items | array | Fino a due vantaggi, nell’ordine in cui mostrarli. Vuoto quando l’hotel non ne mostra nessuno. |
perks.items[].key | string | L’identificatore del vantaggio, come breakfast. Per il tuo codice, mai da mostrare. |
perks.items[].icon | string | L’identificatore dell’icona, come cup. Per il tuo codice, mai da mostrare. |
perks.items[].paths | array | L’icona come dati di tracciato SVG su una griglia di 24 per 24, da uno a tre tracciati, disegnati a tratto con estremità arrotondate e senza riempimento. |
perks.items[].label | object | Il nome del vantaggio da mostrare, con una chiave per lingua: en, es, el, it, de e cs. Potrebbero aggiungersi altre lingue, quindi usa la lingua dell’ospite quando c’è e en quando non c’è. |
error | string | Solo in una risposta 400. Che cosa non va nella richiesta. |
Risultati
| Risultato | Che cosa significa | Che cosa puoi dire |
|---|---|---|
cheapest | Ogni OTA elencata è più cara della prenotazione diretta. | Il risparmio, savingMinor, rispetto all’OTA elencata più economica, e il prezzo di ogni OTA. |
matched | Nessuna OTA elencata costa meno e almeno una è pari alla tariffa dell’hotel. | «Lo stesso prezzo di» un’OTA solo quando il suo priceMinor è uguale a directPriceMinor. |
direct_only | La tariffa dell’hotel è tutto ciò che si può dire: un’OTA può costare meno, vendere a condizioni diverse o non vendere affatto quella notte. | Solo la tariffa dell’hotel. |
Esempi
Una notte in cui l’hotel è il più economico:
{
"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" }
}
]
}
}Una notte in cui c’è solo la tariffa dell’hotel da indicare:
{
"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" }
}
]
}
}Una notte il cui controllo è ancora in corso:
{
"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" }
}
]
}
}Gestisci le risposte in sospeso
La prima richiesta per una notte che nessuno ha ancora chiesto avvia un controllo e risponde pending. La maggior parte dei controlli termina in pochi secondi, alcuni richiedono più tempo. Chiedi di nuovo dopo 2 secondi, poi dopo 3, poi dopo 5 e quindi ogni 8, e fermati dopo 8 richieste o 30 secondi, a seconda di cosa arriva prima. Il widget attende allo stesso modo. Se a quel punto la risposta è ancora pending, rispondi senza prezzo e inserisci un link a bookUrl; una richiesta qualche minuto dopo di solito trova il prezzo.
Non salvare mai in cache una risposta pending e non chiedere una notte che nessuno ti ha chiesto: ogni controllo consuma parte della quota giornaliera dell’hotel.
Aggiornamento e cache
asOf indica quando è stato rilevato il prezzo. I prezzi dell’hotel vengono controllati secondo una programmazione e l’API di verifica dei prezzi dà l’ultimo che ha, quindi un prezzo può risalire a ore o giorni prima. Una richiesta avvia un nuovo controllo solo quando il prezzo è vecchio per il suo soggiorno, cioè più vecchio dell’intervallo della programmazione per quella notte: 1 giorno per stanotte e le 6 notti successive, 4 giorni fino alla notte 30 e 20 giorni oltre. Il prezzo di una notte tra qualche mese può risalire a 15 giorni prima senza avviare nulla. Quando una richiesta avvia un controllo, finché l’hotel ha controlli disponibili, riceve comunque il vecchio prezzo, e una richiesta successiva riceve quello nuovo. Indica sempre quanto è vecchio il prezzo, come fa il widget con Controllato 12 min fa e come fa l’esempio più sotto, e usa l’ora attuale se asOf è successivo all’ora del tuo orologio.
Le risposte sono condivise tra tutti quelli che chiedono la stessa notte, compreso il widget dell’hotel. Una risposta ready resta in cache per 60 secondi e poi viene servita per altri 3600 secondi al massimo mentre si aggiorna, quindi un prezzo può arrivarti fino a 61 minuti dopo che StayParity lo ha: la prima richiesta dopo un periodo senza richieste riceve la risposta precedente, e quella successiva la nuova. unavailable e 404 restano in cache per 60 secondi, pending e 400 mai. L’header Cache-Control dice lo stesso, e la tua cache può seguirlo.
Regole di formulazione
Formula le risposte in base al risultato, non al sigillo del widget:
- Dichiara un risparmio, o che la prenotazione diretta è la più economica, solo con
cheapest. - Di’ «lo stesso prezzo di» un’OTA solo quando il
priceMinordi quell’OTA è esattamente uguale adirectPriceMinor. - Con
direct_only, indica la tariffa dell’hotel e nulla sulle OTA. Non dire che nessuna OTA costa meno, e nemmeno che una costa meno. - Chiama ogni OTA con il valore di
label, mai con l’identificatoreota. - Cita i prezzi così come arrivano: per notte, in
currency. Non convertirli e non aggiungervi nulla. - Un prezzo è per una camera che ospita almeno il numero di adulti richiesto, e a volte per una camera che ne ospita di più, sia per l’hotel sia per le OTA. Il prezzo di un’OTA elencata è per un numero di ospiti pari o inferiore a quello dell’hotel, mai superiore. Indica ciò che hai chiesto, per esempio «per 2 adulti», non che la camera ospita esattamente quel numero di persone.
- Mostra i vantaggi di
perksseparati dal prezzo, attribuiti aperks.from, qualunque sia la risposta. Sono una promessa dell’hotel, non di StayParity, e l’API di verifica dei prezzi non li verifica: non includerne mai uno in un prezzo o in un risparmio, e non aggiungere mai un vantaggio che la risposta non elenca. - Inserisci un link a
bookUrlper la prenotazione, qualunque sia la risposta. SebookUrlTemplatenon ènulle conosci le date di arrivo e di partenza dell’ospite, inserisci invece un link al modello compilato, come fastayUrlpiù sotto. Non ricavare mai una data di partenza che l’ospite non ha indicato, e usabookUrlquando il modello richiede{adults}e non sai quanti sono.
Loghi dei portali
Il logo del widget per un’OTA è all’indirizzo https://badge.stayparity.com/widget/marks/{ota}.svg, in base all’identificatore ota del canale: un SVG quadrato con il riquadro e il simbolo dell’OTA come li disegna il widget, di 22 pixel se non gli dai un’altra dimensione. Per un’OTA di cui il widget non ha il logo la risposta è 404, quindi in quel caso mostra un tuo segnaposto, come il widget mostra la prima lettera del nome. I loghi rispondono a qualsiasi origine e non contengono script. Ognuno resta in cache per un giorno e poi viene servito per altri 30 giorni al massimo mentre si aggiorna, come dice il suo header Cache-Control. Se il sito invia una Content-Security-Policy, consenti l’origine in img-src.
<img src="https://badge.stayparity.com/widget/marks/booking.svg" alt="" width="22" height="22">Attribuzione
Quando il tuo bot o widget cita questi prezzi, ti chiediamo di indicarne la fonte come fa il widget: il simbolo di StayParity, poi «Prezzi verificati da StayParity», con un link a https://stayparity.com. Il simbolo è all’indirizzo https://badge.stayparity.com/widget/brand/mark.svg per uno sfondo chiaro e https://badge.stayparity.com/widget/brand/mark-dark.svg per uno scuro, ed è servito come i loghi dei portali. Un bot che risponde con del testo può chiudere con «Prezzi verificati da StayParity · stayparity.com», come fa in inglese l’esempio più sotto. Non è una condizione: l’API di verifica dei prezzi risponde allo stesso modo anche senza.
<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Prezzi verificati da Stay<b>Parity</b></a>Conta le visualizzazioni
La pagina Widget dell’hotel in StayParity conta quante volte gli ospiti vedono il suo widget. Anche una pagina che mostra il proprio widget con l’API di verifica dei prezzi può contarne le visualizzazioni, e la pagina Widget le mostra separate da quelle del widget StayParity, sotto Il tuo widget: le visualizzazioni, in quante è comparso un prezzo, in quante era sullo schermo e in quante c’è stato un clic su Book direct, per risultato, dispositivo e lingua. Il conteggio è facoltativo: l’API di verifica dei prezzi risponde allo stesso modo anche senza.
La pagina invia un piccolo corpo all’indirizzo:
POST https://badge.stayparity.com/widget/beaconInvia il corpo come stringa: il browser la manda come text/plain, quindi non serve alcun preflight CORS. Un corpo di qualsiasi altro tipo viene scartato.
Corpo
| Campo | Tipo | Significato |
|---|---|---|
key | string | La chiave dell’hotel, la stessa con cui la pagina ha interrogato l’API di verifica dei prezzi. |
view | boolean | true nel primo invio di una visualizzazione di pagina, false nel suo unico invio successivo. |
verdict | string | Solo nel primo invio, dove è obbligatorio. Il verdict dell’ultima risposta ready mostrata dalla pagina, o none se non ne ha mostrata nessuna. |
device | string | Solo nel primo invio, dove è obbligatorio. mobile quando lo schermo è largo meno di 768 pixel, altrimenti desktop. |
lang | string | Solo nel primo invio, dove è obbligatorio. La lingua del browser, navigator.language, al massimo 35 caratteri. |
shown | boolean | Una risposta ready è stata mostrata sullo schermo. |
inView | boolean | Almeno metà di ciò che mostra la risposta è rimasta nel viewport per un secondo senza interruzioni, mentre la pagina era visibile. |
clicked | boolean | L’ospite ha cliccato il link o il pulsante Book direct mostrato con la risposta, che porti a bookUrl o apra la prenotazione dell’hotel stesso. |
Un flag omesso vale false, e un invio successivo deve contenere almeno un flag impostato a true. Un corpo con un campo che non è nella tabella, o con un campo nel formato sbagliato, non conta nulla.
Il primo invio di una visualizzazione di pagina:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": true,
"verdict": "cheapest",
"device": "desktop",
"lang": "en-GB",
"shown": true,
"inView": true
}Il suo invio successivo, per un flag attivato nel frattempo:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": false,
"clicked": true
}Quando inviare
- Conta una visualizzazione quando la pagina ha chiesto all’API di verifica dei prezzi almeno un soggiorno. Una pagina che non ha mai chiesto nulla non conta nulla.
- Fai il primo invio quando la pagina viene nascosta (
visibilitychangea hidden, opagehide) o quando l’ospite clicca Book direct, a seconda di cosa avviene prima. - Fai al massimo un invio successivo, con i soli flag attivati nel frattempo, al successivo di quei momenti.
- Tieni un contatore per chiave e per pagina, così un widget mostrato due volte conta una volta sola.
- Non inviare nulla quando
navigator.webdriverè impostato.
L’origine della pagina
Il beacon conta la visualizzazione per l’host dell’header Origin della richiesta, che imposta il browser. Quindi invialo dalla pagina, mai da un server: un server non invia alcun Origin e i suoi beacon non contano nulla. Un host che non è uno dei siti dell’hotel in StayParity viene conteggiato in Altri siti nella pagina Widget, e localhost non conta mai.
Invialo con fetch e keepalive, come fa l’esempio più sotto. navigator.sendBeacon funziona nella maggior parte dei browser, ma Safari lo invia senza Origin quando la Referrer-Policy della pagina è no-referrer o same-origin, e allora non conta nulla.
Limiti
- Un corpo pesa al massimo 1 KiB.
- Un indirizzo può inviare 30 beacon al minuto, condivisi con il widget dell’hotel.
- Un hotel conta al massimo 5000 beacon nella sua giornata, condivisi con il suo widget. Dopo, non si conta più nulla fino alla mezzanotte, ora dell’hotel.
Controlla i conteggi
Il beacon risponde sempre 204 senza corpo, qualunque cosa sia successa a ciò che hai inviato, quindi la sua risposta non ti dice nulla. Per controllare il conteggio, apri la pagina sul sito dell’hotel, esci e guarda il riquadro Oggi nella pagina Widget di StayParity, sotto Il tuo widget.
Esempio
In JavaScript per un browser. Chiama pageView quando la pagina interroga per la prima volta l’API di verifica dei prezzi con una chiave, shown quando mostra una risposta ready e clicked quando l’ospite clicca 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)Importi
Ogni prezzo è un intero nelle unità minori della valuta, secondo ISO 4217: 14200 in EUR corrisponde a 142,00 €. ISK, JPY e KRW non hanno unità minori, quindi 14200 in JPY corrisponde a 14.200 ¥. Tutte le altre valute che l’API di verifica dei prezzi invia hanno due decimali. Prendi i decimali da questa regola, non dal formattatore di valute della tua piattaforma: i formattatori non concordano e alcuni non danno decimali a HUF e IDR.
Provalo
La chiave wk_demo risponde per l’Hotel Aurora, l’hotel di esempio della pagina demo, con prezzi inventati per un numero di adulti da 1 a 4 e per ogni notte dell’anno a venire. Non risponde mai pending e non consuma i controlli di nessun hotel, quindi puoi chiamarla tutte le volte che vuoi durante i test:
curl "https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=$(date -u +%F)&occupancy=2"Una risposta per un bot in stile WhatsApp, in JavaScript per Node 18 o successivo, Deno, Bun o un browser. Attende finché la risposta resta pending, come fa il widget, indica quanto è vecchio il prezzo e segue le regole di formulazione. stayUrl fornisce il link per il soggiorno dell’ospite:
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)Limiti
- Una richiesta che avvia un controllo consuma uno dei 40 controlli dell’hotel per giorno UTC, condivisi con il suo widget. Una risposta dalla cache, o da un prezzo già rilevato, non consuma nulla. Esauriti i controlli, le notti senza prezzo rispondono
unavailablefino alla mezzanotte UTC e quelle con un prezzo mantengono l’ultimo. - La chiave è pubblica: si trova nel sito dell’hotel. Chiunque la abbia riceve le tue stesse risposte, e l’hotel può sostituirla in qualsiasi momento; da quel momento la vecchia chiave risponde
404. - Usa la chiave solo con il consenso dell’hotel. Funziona solo mentre il widget dell’hotel è attivo.
Da un browser
L’API di verifica dei prezzi risponde a qualsiasi origine (Access-Control-Allow-Origin: *) e non richiede cookie, quindi un widget può chiamarla dalla pagina. Invia un semplice GET senza header personalizzati: l’API di verifica dei prezzi non risponde alle richieste preflight CORS. Se il sito invia una Content-Security-Policy, consenti l’origine dell’API:
connect-src https://badge.stayparity.com;Versioni
Questa è la versione 1 dell’API di verifica dei prezzi e resterà così: nessun campo viene rinominato, rimosso o cambia tipo, non si aggiungono stati né risultati, e ognuno mantiene il proprio significato. Potrà aggiungere campi e valute, quindi ignora i campi che non conosci. Una modifica che romperebbe il tuo codice verrà pubblicata su un nuovo percorso, annunciato in questa pagina. Lo stesso vale per il corpo del beacon: potrà acquisire campi facoltativi, ma nessun campo diventerà obbligatorio, verrà rinominato o rimosso, e nessun corpo che oggi conta smetterà di contare.
Lo stesso contratto è nella descrizione OpenAPI 3.1, con questi esempi.
Widget prenotazioni
Aggiungi il widget StayParity per prenotazioni dirette al sito dell’hotel con un solo codice. Il codice, il dock, cosa vedono gli ospiti e la CSP necessaria.
Misura il widget nei tuoi strumenti di analisi
Conta in GA4 le prenotazioni dal widget StayParity per prenotazioni dirette: il contrassegno stayparity=1 su Book direct, un segmento e cosa non contiene mai.