Zum Inhalt springen

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=2

Parameter

ParameterWert
keyDer Einbettungsschlüssel des Hotels, wk_…: der Wert von data-hotel in seinem Badge-Snippet, im Portal unter Einstellungen → Website-Badge.
stayDateDie Nacht, angegeben als ihr Anreisedatum im Format YYYY-MM-DD. Immer eine Nacht: Fragen Sie bei einem längeren Aufenthalt nach dessen erster.
occupancyDie 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:

StatusBedeutungWas zu tun ist
readyFür den Aufenthalt liegt ein abgefragter Preis vor. comparison enthält ihn.Nennen Sie ihn nach den Formulierungsregeln und verlinken Sie bookUrl.
pendingFür den Aufenthalt wurde noch nichts abgefragt, und gerade läuft eine Prüfung.Fragen Sie erneut, wie unter Wartezeit bei pending beschrieben.
unavailableEs 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

CodeWannBody
200Immer, wenn Schlüssel und Anfrage in Ordnung sind.ready, pending oder unavailable
400Ein 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
404Der Schlüssel ist unbekannt oder wurde ersetzt, oder das Badge des Hotels ist ausgeschaltet.{"status": "unavailable"}
405Eine andere Methode als GET.Keiner
502Der 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

FeldTypBedeutung
statusstringready, pending oder unavailable.
asOfintegerNur bei ready. Wann der neueste Preis in comparison abgefragt wurde, in Unix-Millisekunden. Nie der Zeitpunkt Ihrer Anfrage.
comparisonobjectNur bei ready. Der Preis des Hotels und die OTAs, neben denen er gezeigt werden darf.
comparison.currencystringDie Währung des Hotels als ISO-4217-Code, etwa EUR. Alle Preise im Vergleich sind in dieser Währung.
comparison.directPriceMinorintegerDer eigene Preis des Hotels für die Nacht, in der kleinsten Währungseinheit.
comparison.verdictstringcheapest, matched oder direct_only, siehe Ergebnisse.
comparison.savingMinorintegerDer 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.channelsarrayDie OTAs, die neben dem Preis des Hotels zu zeigen sind. Leer, wenn verdict gleich direct_only ist.
comparison.channels[].otastringDie ID der OTA, etwa booking oder expedia. Für Ihren Code, nie zur Anzeige.
comparison.channels[].labelstringDer anzuzeigende Name der OTA, etwa Booking.com.
comparison.channels[].priceMinorintegerDer 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.
bookUrlstringDie Buchungsseite des Hotels, immer https. Jede 200 enthält sie.
bookUrlTemplatestring oder nullDie 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.
perksobjectDie 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.fromstringDer Name, unter dem die Vorteile zu zeigen sind: der Name des Hotels oder der kürzere, den es seinem Badge gegeben hat.
perks.itemsarrayBis zu zwei Vorteile, in der Reihenfolge, in der sie zu zeigen sind. Leer, wenn das Hotel keine zeigt.
perks.items[].keystringDie ID des Vorteils, etwa breakfast. Für Ihren Code, nie zur Anzeige.
perks.items[].iconstringDie ID des Symbols, etwa cup. Für Ihren Code, nie zur Anzeige.
perks.items[].pathsarrayDas 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[].labelobjectDer 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.
errorstringNur bei einer 400. Was an der Anfrage falsch ist.

Ergebnisse

ErgebnisBedeutungWas Sie sagen dürfen
cheapestJede aufgeführte OTA ist teurer als die Direktbuchung.Die Ersparnis, savingMinor, gegenüber der günstigsten aufgeführten OTA, und den Preis jeder OTA.
matchedKeine 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_onlyDer 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 cheapest von einer Ersparnis oder davon, dass die Direktbuchung am günstigsten ist.
  • Sagen Sie „derselbe Preis wie bei“ einer OTA nur, wenn deren priceMinor genau gleich directPriceMinor ist.
  • Nennen Sie bei direct_only den 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 ihrer ota-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 perks getrennt vom Preis, unter dem Namen aus perks.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. Ist bookUrlTemplate nicht null und kennen Sie An- und Abreisedatum des Gastes, verlinken Sie stattdessen die ausgefüllte Vorlage, wie es stayUrl weiter unten tut. Erschließen Sie nie ein Abreisedatum, das der Gast nicht genannt hat, und nehmen Sie bookUrl, 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/beacon

Senden 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

FeldTypBedeutung
keystringDer Einbettungsschlüssel des Hotels, mit dem die Seite die Preisprüfung abgefragt hat.
viewbooleantrue bei der ersten Übermittlung eines Seitenaufrufs, false bei seiner einzigen späteren Übermittlung.
verdictstringNur 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.
devicestringNur bei der ersten Übermittlung, und dort Pflicht. mobile, wenn der Bildschirm schmaler als 768 Pixel ist, sonst desktop.
langstringNur bei der ersten Übermittlung, und dort Pflicht. Die Sprache des Browsers, navigator.language, höchstens 35 Zeichen.
shownbooleanEine ready-Antwort wurde auf dem Bildschirm angezeigt.
inViewbooleanMindestens die Hälfte dessen, was die Antwort zeigt, war eine Sekunde lang ohne Unterbrechung im Viewport, während die Seite sichtbar war.
clickedbooleanDer 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 (visibilitychange auf hidden oder pagehide) 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.webdriver gesetzt 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.

Auf dieser Seite