Preisprüfungs-API
Fragen Sie im Chatbot oder Widget das Ergebnis hinter dem StayParity-Badge ab: ein GET, der Direktpreis und gleich teure oder teurere OTAs, nie günstigere.
Die Preisprüfung beantwortet eine Frage für eine Nacht: Was verlangt die eigene Website des Hotels, und ist das der beste Preis, den es gibt? Sie liest dieselben Daten wie das Website-Badge des Hotels. So kann auch ein WhatsApp-Bot, ein Chatassistent oder ein selbst gebautes Widget ihre Antwort nennen. Sie meldet das Ergebnis, das die Prüfung gefunden hat. Das Siegel Bester Preis hier des Badges ist eine Aussage des Hotels selbst, erscheint bei jedem Ergebnis und gehört nicht zur Antwort.
Sie braucht weder ein Konto noch ein API-Token, nur den Einbettungsschlüssel des Hotels, und sie verrät nichts, was ein Gast auf der Website des Hotels nicht auch sehen könnte. Verkauft eine OTA die Nacht günstiger, nennt die Preisprüfung nur den eigenen Preis des Hotels, genau wie bei einer Nacht, die keine OTA verkauft. Deshalb können weder Sie noch sonst jemand an der Antwort erkennen, ob eine OTA das Hotel unterbietet.
Anfrage
Ein GET mit drei Query-Parametern:
GET https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=2027-06-14&occupancy=2Parameter
| Parameter | Wert |
|---|---|
key | Der Einbettungsschlüssel des Hotels, wk_…: der Wert von data-hotel in seinem Badge-Snippet, im Portal unter Einstellungen → Website-Badge. |
stayDate | Die Nacht, angegeben als ihr Anreisedatum im Format YYYY-MM-DD. Immer eine Nacht: Fragen Sie bei einem längeren Aufenthalt nach dessen erster. |
occupancy | Die Zahl der Erwachsenen, von 1 bis 10. |
Die Preisprüfung funktioniert nur, solange das Badge des Hotels eingeschaltet ist. Das Hotel muss das Badge dafür nicht auf einer Seite zeigen.
Antworten
Jede Antwort ist JSON mit einem status. Eine 200 enthält einen von drei Werten:
| Status | Bedeutung | Was zu tun ist |
|---|---|---|
ready | Für den Aufenthalt liegt ein abgefragter Preis vor. comparison enthält ihn. | Nennen Sie ihn nach den Formulierungsregeln und verlinken Sie bookUrl. |
pending | Für den Aufenthalt wurde noch nichts abgefragt, und gerade läuft eine Prüfung. | Fragen Sie erneut, wie unter Wartezeit bei pending beschrieben. |
unavailable | Es gibt nichts zu nennen, und gerade kann keine Prüfung starten: Das Hotel ist in StayParity pausiert, es wird für diese Zahl an Erwachsenen nicht geprüft, die Nacht liegt in der Zeitzone des Hotels in der Vergangenheit oder weiter in der Zukunft, als sein Paket prüft, seine Prüfungen für den Tag sind aufgebraucht, oder die letzte Prüfung hat keinen Preis gefunden. | Antworten Sie ohne Preis und verlinken Sie bookUrl. Bei einer Zahl an Erwachsenen, für die das Hotel nicht geprüft wird, können Sie erneut für 2 fragen und dazusagen, dass Sie für 2 Erwachsene geprüft haben. |
HTTP-Status
| Code | Wann | Body |
|---|---|---|
200 | Immer, wenn Schlüssel und Anfrage in Ordnung sind. | ready, pending oder unavailable |
400 | Ein Parameter fehlt oder ist fehlerhaft, occupancy liegt außerhalb von 1 bis 10, oder die Nacht ist überall auf der Erde schon vorbei. | {"status": "unavailable", "error": "…"}, der Fehler auf Englisch, für die Person, die die Anfrage geschrieben hat |
404 | Der Schlüssel ist unbekannt oder wurde ersetzt, oder das Badge des Hotels ist ausgeschaltet. | {"status": "unavailable"} |
405 | Eine andere Methode als GET. | Keiner |
502 | Der Server des Badges hat StayParity nicht erreicht. Versuchen Sie es später erneut. | {"status": "unavailable"} |
Werten Sie jeden anderen Code, einen Body, der kein JSON ist, und jeden Netzwerkfehler als keine Antwort.
Felder
| Feld | Typ | Bedeutung |
|---|---|---|
status | string | ready, pending oder unavailable. |
asOf | integer | Nur bei ready. Wann der neueste Preis in comparison abgefragt wurde, in Unix-Millisekunden. Nie der Zeitpunkt Ihrer Anfrage. |
comparison | object | Nur bei ready. Der Preis des Hotels und die OTAs, neben denen er gezeigt werden darf. |
comparison.currency | string | Die Währung des Hotels als ISO-4217-Code, etwa EUR. Alle Preise im Vergleich sind in dieser Währung. |
comparison.directPriceMinor | integer | Der eigene Preis des Hotels für die Nacht, in der kleinsten Währungseinheit. |
comparison.verdict | string | cheapest, matched oder direct_only, siehe Ergebnisse. |
comparison.savingMinor | integer | Der Preis der günstigsten aufgeführten OTA minus dem des Hotels, in der kleinsten Währungseinheit. Null, außer wenn verdict gleich cheapest ist. |
comparison.channels | array | Die OTAs, die neben dem Preis des Hotels zu zeigen sind. Leer, wenn verdict gleich direct_only ist. |
comparison.channels[].ota | string | Die ID der OTA, etwa booking oder expedia. Für Ihren Code, nie zur Anzeige. |
comparison.channels[].label | string | Der anzuzeigende Name der OTA, etwa Booking.com. |
comparison.channels[].priceMinor | integer | Der Preis der OTA für dieselbe Nacht, in der kleinsten Währungseinheit, für ebenso viele Gäste wie der Preis des Hotels oder weniger: siehe Formulierungsregeln. |
bookUrl | string | Die Buchungsseite des Hotels, immer https. Jede 200 enthält sie. |
bookUrlTemplate | string oder null | Die Buchungssuche des Hotels, mit {checkin}, {checkout}, {nights} und {adults} zum Ausfüllen: Daten als YYYY-MM-DD, Nächte und Erwachsene als ganze Zahlen. null, wenn das Hotel keine gespeichert hat. Jede 200 enthält sie. |
perks | object | Die eigenen Vorteile des Hotels für einen Gast, der direkt bucht, etwa Frühstück, unter dem Namen des Hotels. Jede 200 enthält sie. Zeigen Sie sie getrennt vom Preis: siehe Formulierungsregeln. |
perks.from | string | Der Name, unter dem die Vorteile zu zeigen sind: der Name des Hotels oder der kürzere, den es seinem Badge gegeben hat. |
perks.items | array | Bis zu zwei Vorteile, in der Reihenfolge, in der sie zu zeigen sind. Leer, wenn das Hotel keine zeigt. |
perks.items[].key | string | Die ID des Vorteils, etwa breakfast. Für Ihren Code, nie zur Anzeige. |
perks.items[].icon | string | Die ID des Symbols, etwa cup. Für Ihren Code, nie zur Anzeige. |
perks.items[].paths | array | Das Symbol als SVG-Pfaddaten auf einem Raster von 24 mal 24, ein bis drei Pfade, gezeichnet als Kontur mit runden Enden und ohne Füllung. |
perks.items[].label | object | Der anzuzeigende Name des Vorteils, mit der Sprache als Schlüssel: en, es, el, it, de und cs. Weitere Sprachen können hinzukommen. Nehmen Sie daher die Sprache des Gastes, wenn es sie gibt, und sonst en. |
error | string | Nur bei einer 400. Was an der Anfrage falsch ist. |
Ergebnisse
| Ergebnis | Bedeutung | Was Sie sagen dürfen |
|---|---|---|
cheapest | Jede aufgeführte OTA ist teurer als die Direktbuchung. | Die Ersparnis, savingMinor, gegenüber der günstigsten aufgeführten OTA, und den Preis jeder OTA. |
matched | Keine aufgeführte OTA ist günstiger, und mindestens eine ist gleichauf mit dem Hotel. | „Derselbe Preis wie bei“ einer OTA nur, wenn ihr priceMinor gleich directPriceMinor ist. |
direct_only | Der Preis des Hotels ist alles, was sich sagen lässt: Eine OTA kann günstiger sein, zu anderen Bedingungen verkaufen oder die Nacht gar nicht verkaufen. | Nur den Preis des Hotels. |
Beispiele
Eine Nacht, in der das Hotel am günstigsten ist:
{
"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" }
}
]
}
}Eine Nacht, für die es nur den Preis des Hotels zu nennen gibt:
{
"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" }
}
]
}
}Eine Nacht, die noch geprüft wird:
{
"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" }
}
]
}
}Wartezeit bei pending
Die erste Anfrage für eine Nacht, nach der noch niemand gefragt hat, startet eine Prüfung und antwortet mit pending. Die meisten Prüfungen sind in wenigen Sekunden fertig, manche dauern länger. Fragen Sie nach 2 Sekunden erneut, dann nach 3, dann nach 5, dann alle 8, und hören Sie nach 8 Anfragen oder 30 Sekunden auf, je nachdem, was zuerst eintritt. Das Badge wartet genauso. Ist die Antwort dann immer noch pending, antworten Sie ohne Preis und verlinken Sie bookUrl; eine Anfrage ein paar Minuten später findet den Preis meistens.
Speichern Sie eine pending-Antwort nie zwischen, und fragen Sie nicht nach einer Nacht, nach der Sie niemand gefragt hat: Jede Prüfung geht vom täglichen Kontingent an Prüfungen des Hotels ab.
Aktualität und Zwischenspeicher
asOf sagt, wann der Preis abgefragt wurde. Die Preise des Hotels werden nach einem Zeitplan geprüft, und die Preisprüfung gibt den neuesten Preis, den sie hat, daher kann ein Preis Stunden oder Tage alt sein. Eine Anfrage startet nur dann eine neue Prüfung, wenn der Preis für ihren Aufenthalt veraltet ist, also älter als der Abstand, den der Zeitplan für diese Nacht vorsieht: 1 Tag für heute Nacht und die 6 Nächte danach, 4 Tage bis Nacht 30 und 20 Tage darüber hinaus. Ein Preis für eine Nacht, die Monate entfernt ist, kann 15 Tage alt sein und nichts starten. Startet eine Anfrage eine Prüfung, solange das Hotel noch Prüfungen übrig hat, erhält sie trotzdem den alten Preis, und eine spätere Anfrage erhält den neuen. Sagen Sie immer, wie alt der Preis ist, so wie das Badge mit „Geprüft vor 12 Min.“ und das Beispiel unten, und rechnen Sie mit der aktuellen Zeit, wenn asOf später liegt als Ihre Uhr.
Alle, die nach derselben Nacht fragen, erhalten dieselbe Antwort, das Badge des Hotels eingeschlossen. Eine ready-Antwort wird 60 Sekunden lang zwischengespeichert und danach bis zu 3.600 Sekunden länger ausgeliefert, während sie aktualisiert wird. Ein Preis kann Sie also bis zu 61 Minuten, nachdem StayParity ihn hat, erreichen: Die erste Anfrage nach einer Zeit ohne Anfragen erhält die ältere Antwort, die nächste die neue. unavailable und 404 werden 60 Sekunden lang zwischengespeichert, pending und 400 gar nicht. Der Cache-Control-Header sagt dasselbe, und Ihr eigener Cache kann sich danach richten.
Formulierungsregeln
Formulieren Sie Ihre Antworten nach dem Ergebnis, nicht nach dem Siegel des Badges:
- Sprechen Sie nur bei
cheapestvon einer Ersparnis oder davon, dass die Direktbuchung am günstigsten ist. - Sagen Sie „derselbe Preis wie bei“ einer OTA nur, wenn deren
priceMinorgenau gleichdirectPriceMinorist. - Nennen Sie bei
direct_onlyden Preis des Hotels und nichts über OTAs. Sagen Sie weder, dass keine OTA günstiger ist, noch, dass eine es ist. - Nennen Sie eine OTA bei ihrem
label, nie bei ihrerota-ID. - Geben Sie Preise so wieder, wie sie kommen: pro Nacht, in
currency. Rechnen Sie sie nicht um und rechnen Sie nichts hinzu. - Ein Preis gilt für ein Zimmer, in dem mindestens so viele Erwachsene schlafen können wie erfragt, und manchmal für ein Zimmer, in dem mehr schlafen können, beim Hotel wie bei den OTAs. Der Preis einer aufgeführten OTA gilt für ebenso viele Gäste wie der des Hotels oder weniger, nie für mehr. Sagen Sie, wonach Sie gefragt haben, etwa „für 2 Erwachsene“, nicht, dass das Zimmer für genau so viele Personen ist.
- Zeigen Sie die Vorteile aus
perksgetrennt vom Preis, unter dem Namen ausperks.from, egal wie die Antwort lautet. Sie sind ein Versprechen des Hotels, nicht von StayParity, und die Preisprüfung prüft sie nicht: Rechnen Sie nie einen Vorteil in einen Preis oder eine Ersparnis ein, und fügen Sie nie einen Vorteil hinzu, den die Antwort nicht aufführt. - Verlinken Sie für die Buchung
bookUrl, egal wie die Antwort lautet. IstbookUrlTemplatenichtnullund kennen Sie An- und Abreisedatum des Gastes, verlinken Sie stattdessen die ausgefüllte Vorlage, wie esstayUrlweiter unten tut. Erschließen Sie nie ein Abreisedatum, das der Gast nicht genannt hat, und nehmen SiebookUrl, wenn die Vorlage{adults}verlangt und Sie die Zahl nicht kennen.
Logos der Anbieter
Das Logo des Badges für eine OTA liegt unter https://badge.stayparity.com/widget/marks/{ota}.svg, anhand der ota-ID des Kanals: ein quadratisches SVG mit der Kachel und der Bildmarke der OTA, wie das Badge sie zeichnet, 22 Pixel groß, sofern Sie keine andere Größe festlegen. Hat das Badge für eine OTA kein Logo, lautet die Antwort 404. Zeigen Sie dann Ihren eigenen Platzhalter, so wie das Badge den ersten Buchstaben des Namens zeigt. Die Logos antworten jedem Ursprung und enthalten keine Skripte. Jedes wird einen Tag lang zwischengespeichert und danach bis zu 30 Tage länger ausgeliefert, während es aktualisiert wird, wie sein Cache-Control-Header sagt. Sendet die Website eine Content-Security-Policy, erlauben Sie den Ursprung in img-src.
<img src="https://badge.stayparity.com/widget/marks/booking.svg" alt="" width="22" height="22">Quellenangabe
Wenn Ihr Bot oder Widget diese Preise nennt, bitten wir Sie, sie so auszuweisen wie das Badge: mit der Bildmarke von StayParity, danach „Preisprüfung von StayParity“, verlinkt auf https://stayparity.com. Die Bildmarke liegt unter https://badge.stayparity.com/widget/brand/mark.svg für einen hellen Hintergrund und unter https://badge.stayparity.com/widget/brand/mark-dark.svg für einen dunklen; sie wird ausgeliefert wie die Logos der Anbieter. Ein Bot, der mit Text antwortet, kann mit „Preisprüfung von StayParity · stayparity.com“ enden, wie es das Beispiel unten auf Englisch tut. Das ist keine Bedingung: Die Preisprüfung antwortet ohne diese Angabe genauso.
<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Preisprüfung von Stay<b>Parity</b></a>Aufrufe zählen
Die Seite Badge des Hotels in StayParity zählt, wie oft Gäste sein Badge sehen. Eine Seite, die mit der Preisprüfung ihr eigenes Widget anzeigt, kann dessen Aufrufe ebenfalls zählen, und die Seite Badge zeigt sie getrennt von denen des Badges unter Ihr eigenes Widget: die Aufrufe, in wie vielen davon ein Preis zu sehen war, in wie vielen er auf dem Bildschirm war und in wie vielen auf Book direct geklickt wurde, nach Ergebnis, Gerät und Sprache. Das Zählen ist freiwillig: Die Preisprüfung antwortet auch ohne Zählung genauso.
Die Seite sendet einen kleinen Body an:
POST https://badge.stayparity.com/widget/beaconSenden Sie den Body als String, den der Browser als text/plain sendet, sodass kein CORS-Preflight nötig ist. Ein Body eines anderen Typs wird verworfen.
Body
| Feld | Typ | Bedeutung |
|---|---|---|
key | string | Der Einbettungsschlüssel des Hotels, mit dem die Seite die Preisprüfung abgefragt hat. |
view | boolean | true bei der ersten Übermittlung eines Seitenaufrufs, false bei seiner einzigen späteren Übermittlung. |
verdict | string | Nur bei der ersten Übermittlung, und dort Pflicht. Das verdict der letzten ready-Antwort, die die Seite gezeigt hat, oder none, wenn sie keine gezeigt hat. |
device | string | Nur bei der ersten Übermittlung, und dort Pflicht. mobile, wenn der Bildschirm schmaler als 768 Pixel ist, sonst desktop. |
lang | string | Nur bei der ersten Übermittlung, und dort Pflicht. Die Sprache des Browsers, navigator.language, höchstens 35 Zeichen. |
shown | boolean | Eine ready-Antwort wurde auf dem Bildschirm angezeigt. |
inView | boolean | Mindestens die Hälfte dessen, was die Antwort zeigt, war eine Sekunde lang ohne Unterbrechung im Viewport, während die Seite sichtbar war. |
clicked | boolean | Der Gast hat auf den Link oder Button Book direct geklickt, der mit der Antwort angezeigt wurde, ob er zu bookUrl führt oder die eigene Buchung des Hotels öffnet. |
Ein weggelassenes Flag bedeutet false, und eine spätere Übermittlung muss mindestens ein Flag mit dem Wert true enthalten. Ein Body mit einem Feld, das nicht in der Tabelle steht, oder mit einem Feld in falscher Form zählt nichts.
Die erste Übermittlung eines Seitenaufrufs:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": true,
"verdict": "cheapest",
"device": "desktop",
"lang": "en-GB",
"shown": true,
"inView": true
}Seine spätere Übermittlung, für ein seitdem eingeschaltetes Flag:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": false,
"clicked": true
}Wann senden
- Zählen Sie einen Aufruf, sobald die Seite die Preisprüfung nach mindestens einem Aufenthalt gefragt hat. Eine Seite, die nie gefragt hat, zählt nichts.
- Senden Sie die erste Übermittlung, wenn die Seite ausgeblendet wird (
visibilitychangeauf hidden oderpagehide) oder wenn der Gast auf Book direct klickt, je nachdem, was zuerst eintritt. - Senden Sie höchstens eine spätere Übermittlung, nur mit den seitdem eingeschalteten Flags, beim nächsten dieser Momente.
- Führen Sie einen Zähler pro Schlüssel und Seite, damit ein zweimal angezeigtes Widget einmal zählt.
- Senden Sie nichts, wenn
navigator.webdrivergesetzt ist.
Der Ursprung der Seite
Der Beacon zählt den Aufruf für den Host im Origin-Header der Anfrage, den der Browser setzt. Senden Sie ihn also von der Seite, nie von einem Server: Ein Server sendet keinen Origin-Header, und seine Beacons zählen nichts. Ein Host, der nicht zu den Websites des Hotels in StayParity gehört, zählt auf der Seite Badge unter Andere Websites, und localhost zählt nie.
Senden Sie ihn mit fetch und keepalive, wie es das Beispiel unten tut. navigator.sendBeacon funktioniert in den meisten Browsern, aber Safari sendet ihn ohne Origin, wenn die Referrer-Policy der Seite no-referrer oder same-origin ist, und dann zählt nichts.
Grenzen
- Ein Body ist höchstens 1 KiB groß.
- Eine Adresse kann 30 Beacons pro Minute senden, geteilt mit dem Badge des Hotels.
- Ein Hotel zählt höchstens 5.000 Beacons an seinem Tag, geteilt mit seinem Badge. Danach zählt nichts mehr bis Mitternacht Hotelzeit.
Zählung prüfen
Der Beacon antwortet immer mit 204 ohne Body, egal was mit dem Gesendeten geschehen ist, seine Antwort sagt Ihnen also nichts. Um Ihre Zählung zu prüfen, öffnen Sie die Seite auf der Website des Hotels, verlassen sie wieder und sehen sich in StayParity auf der Seite Badge unter Ihr eigenes Widget die Karte Heute an.
Beispiel
In JavaScript für einen Browser. Rufen Sie pageView auf, wenn die Seite die Preisprüfung zum ersten Mal mit einem Schlüssel abfragt, shown, wenn sie eine ready-Antwort anzeigt, und clicked, wenn der Gast auf Book direct klickt:
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)Geldbeträge
Jeder Preis ist eine ganze Zahl in der kleinsten Einheit der Währung, wie in ISO 4217 festgelegt: 14200 in EUR sind 142,00 €. ISK, JPY und KRW haben keine kleinere Einheit, also sind 14200 in JPY 14.200 ¥. Jede andere Währung, die die Preisprüfung sendet, hat zwei Nachkommastellen. Nehmen Sie die Nachkommastellen aus dieser Regel, nicht aus dem Währungsformatierer Ihrer Plattform: Formatierer sind sich nicht einig, und manche geben HUF und IDR keine.
Ausprobieren
Der Schlüssel wk_demo antwortet für das Hotel Aurora, das Beispielhotel auf der Demoseite, mit erfundenen Preisen für 1 bis 4 Erwachsene und jede Nacht des kommenden Jahres. Er antwortet nie mit pending und verbraucht keine Prüfungen eines Hotels, Sie können ihn also bei jedem Test aufrufen:
curl "https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=$(date -u +%F)&occupancy=2"Code für die Antworten eines Bots im Stil von WhatsApp, in JavaScript für Node 18 oder neuer, Deno, Bun oder einen Browser. Er wartet pending so ab wie das Badge, sagt, wie alt der Preis ist, und hält sich an die Formulierungsregeln. stayUrl liefert den Link für den Aufenthalt des Gastes:
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)Grenzen
- Eine Anfrage, die eine Prüfung startet, verbraucht eine der 40 Prüfungen, die das Hotel pro UTC-Tag hat und mit seinem Badge teilt. Eine Antwort aus dem Cache oder aus einem bereits abgefragten Preis verbraucht nichts. Sind die Prüfungen aufgebraucht, antworten Nächte ohne Preis bis Mitternacht UTC mit
unavailable, und Nächte mit Preis behalten ihren letzten Preis. - Der Schlüssel ist öffentlich: Er steht in der Website des Hotels. Jeder, der ihn hat, erhält dieselben Antworten wie Sie, und das Hotel kann ihn jederzeit ersetzen. Danach antwortet der alte Schlüssel mit
404. - Verwenden Sie den Schlüssel nur mit dem Einverständnis des Hotels. Er funktioniert nur, solange das Badge des Hotels eingeschaltet ist.
Aus dem Browser
Die Preisprüfung antwortet jedem Ursprung (Access-Control-Allow-Origin: *) und braucht keine Cookies, ein Widget kann sie also direkt aus der Seite aufrufen. Senden Sie ein einfaches GET ohne eigene Header: Auf einen CORS-Preflight antwortet die Preisprüfung nicht. Sendet die Website eine Content-Security-Policy, erlauben Sie den Ursprung der API:
connect-src https://badge.stayparity.com;Versionierung
Dies ist Version 1 der Preisprüfung, und sie bleibt, wie sie ist: Kein Feld wird umbenannt oder entfernt oder ändert seinen Typ, kein Status und kein Ergebnis kommt hinzu, und jedes behält seine Bedeutung. Felder und Währungen können hinzukommen, ignorieren Sie also Felder, die Sie nicht kennen. Eine Änderung, die Ihren Code brechen würde, erscheint unter einem neuen Pfad und wird auf dieser Seite angekündigt. Dasselbe gilt für den Body des Beacons: Er kann um optionale Felder erweitert werden, aber kein Feld wird Pflicht, umbenannt oder entfernt, und kein Body, der heute zählt, hört auf zu zählen.
Dieselbe Spezifikation steht mit diesen Beispielen in der OpenAPI-3.1-Beschreibung.
Website-Badge
Binden Sie das Direktbuchungs-Badge von StayParity mit einem Snippet in die Website eines Hotels ein. Snippet, Dock, was Gäste sehen und die nötige CSP.
Das Badge in Ihrer Webanalyse messen
Buchungen über das Direktbuchungs-Badge von StayParity in GA4 zählen: die Markierung stayparity=1 an Book direct, ein Segment darauf und was sie nie enthält.