Μετάβαση στο περιεχόμενο

API ελέγχου τιμών

Δείξτε στο chatbot ή widget σας ό,τι δείχνει το widget StayParity ενός ξενοδοχείου: ένα GET, η απευθείας τιμή, όσα OTA δεν είναι φθηνότερα, ποτέ απόκλιση.

Το API ελέγχου τιμών απαντά σε μία ερώτηση για μία διανυκτέρευση: πόσο χρεώνει η ιστοσελίδα του ίδιου του ξενοδοχείου και είναι αυτή η καλύτερη διαθέσιμη τιμή; Διαβάζει τα ίδια δεδομένα με το widget κρατήσεων του ξενοδοχείου, ώστε να μπορεί να αναφέρει την απάντησή του και ένα bot στο WhatsApp, ένας βοηθός συνομιλίας ή ένα widget που φτιάχνετε εσείς. Επιστρέφει το αποτέλεσμα σύγκρισης που βρήκε ο έλεγχος. Η σφραγίδα Best price here του widget είναι ισχυρισμός του ίδιου του ξενοδοχείου, εμφανίζεται σε κάθε αποτέλεσμα και δεν αποτελεί μέρος της απάντησης.

Δεν χρειάζεται λογαριασμό ή API token, μόνο το κλειδί ενσωμάτωσης του ξενοδοχείου, και δεν λέει τίποτα που δεν θα έβλεπε ένας επισκέπτης στην ιστοσελίδα του ξενοδοχείου. Όταν ένα OTA πουλάει τη διανυκτέρευση φθηνότερα, δίνει μόνο την τιμή του ξενοδοχείου, ακριβώς όπως για μια διανυκτέρευση που δεν πουλάει κανένα OTA, ώστε ούτε εσείς ούτε κανείς άλλος να μπορεί να διακρίνει μια απόκλιση από την απάντησή του.

Αίτημα

Ένα GET, με τρεις παραμέτρους ερωτήματος:

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

Παράμετροι

ΠαράμετροςΤιμή
keyΤο κλειδί ενσωμάτωσης του ξενοδοχείου, wk_…: η τιμή του data-hotel στον κώδικα του widget, στις Ρυθμίσεις → Widget κρατήσεων της εφαρμογής.
stayDateΗ διανυκτέρευση, με την ημερομηνία άφιξης σε μορφή YYYY-MM-DD. Μία διανυκτέρευση: για μεγαλύτερη διαμονή, ρωτήστε για την πρώτη.
occupancyΟ αριθμός ενηλίκων, από 1 έως 10.

Το API ελέγχου τιμών λειτουργεί μόνο όσο το widget του ξενοδοχείου είναι ενεργό. Το ξενοδοχείο δεν χρειάζεται να εμφανίζει το widget σε κάποια σελίδα.

Απαντήσεις

Κάθε απάντηση είναι JSON με ένα status. Μια απάντηση 200 φέρει ένα από τα τρία:

ΚατάστασηΣημασίαΤι κάνετε
readyΔιαβάσαμε τιμή για τη διαμονή. Βρίσκεται στο comparison.Αναφέρετέ τη σύμφωνα με τους κανόνες διατύπωσης, με σύνδεσμο στο bookUrl.
pendingΔεν έχουμε διαβάσει ακόμη τιμή για τη διαμονή και ένας έλεγχος εκτελείται τώρα.Ρωτήστε ξανά, όπως περιγράφει η ενότητα Αναμονή όσο ο έλεγχος εκτελείται.
unavailableΔεν υπάρχει τιμή για να αναφέρετε και δεν μπορεί να ξεκινήσει έλεγχος τώρα: η παρακολούθηση του ξενοδοχείου είναι σε παύση στο StayParity, το ξενοδοχείο δεν ελέγχεται για αυτόν τον αριθμό ενηλίκων, η διανυκτέρευση έχει περάσει στη ζώνη ώρας του ξενοδοχείου ή είναι πέρα από τις επόμενες ημέρες που ελέγχει το πακέτο του, οι έλεγχοι της ημέρας έχουν εξαντληθεί ή ο τελευταίος έλεγχος δεν βρήκε τιμή.Απαντήστε χωρίς τιμή, με σύνδεσμο στο bookUrl. Για αριθμό ενηλίκων για τον οποίο το ξενοδοχείο δεν ελέγχεται, μπορείτε να ρωτήσετε ξανά για 2 και να πείτε ότι ελέγξατε για 2 ενήλικες.

Κωδικοί HTTP

ΚωδικόςΠότεΣώμα
200Πάντα, όταν το κλειδί και το αίτημα είναι έγκυρα.ready, pending ή unavailable
400Λείπει ή είναι λανθασμένη μια παράμετρος, το occupancy είναι εκτός του εύρους 1 έως 10 ή η διανυκτέρευση έχει ήδη περάσει παντού στη Γη.{"status": "unavailable", "error": "…"}, με το σφάλμα στα αγγλικά, για όποιον έγραψε το αίτημα
404Το κλειδί είναι άγνωστο, έχει αντικατασταθεί ή το widget του ξενοδοχείου είναι ανενεργό.{"status": "unavailable"}
405Μέθοδος διαφορετική από GET.Κανένα
502Ο διακομιστής του widget δεν μπόρεσε να συνδεθεί με το StayParity. Δοκιμάστε ξανά αργότερα.{"status": "unavailable"}

Αντιμετωπίστε κάθε άλλο κωδικό, σώμα που δεν είναι JSON ή σφάλμα δικτύου ως έλλειψη απάντησης.

Πεδία

ΠεδίοΤύποςΣημασία
statusstringready, pending ή unavailable.
asOfintegerΜόνο στο ready. Πότε βρέθηκε η πιο πρόσφατη τιμή του comparison, σε χιλιοστά του δευτερολέπτου Unix. Ποτέ η ώρα του αιτήματός σας.
comparisonobjectΜόνο στο ready. Η τιμή του ξενοδοχείου και τα OTA δίπλα στα οποία μπορεί να εμφανιστεί.
comparison.currencystringΤο νόμισμα του ξενοδοχείου, ως κωδικός ISO 4217, π.χ. EUR. Σε αυτό εκφράζεται κάθε τιμή της σύγκρισης.
comparison.directPriceMinorintegerΗ τιμή του ίδιου του ξενοδοχείου για τη διανυκτέρευση, στη μικρότερη υποδιαίρεση του νομίσματος.
comparison.verdictstringcheapest, matched ή direct_only: βλ. Αποτελέσματα σύγκρισης.
comparison.savingMinorintegerΗ τιμή του φθηνότερου OTA της λίστας μείον την τιμή του ξενοδοχείου, στη μικρότερη υποδιαίρεση. Μηδέν, εκτός αν το verdict είναι cheapest.
comparison.channelsarrayΤα OTA που εμφανίζονται δίπλα στην τιμή του ξενοδοχείου. Κενό όταν το verdict είναι direct_only.
comparison.channels[].otastringΤο αναγνωριστικό του OTA, π.χ. booking ή expedia. Για τον κώδικά σας, ποτέ για εμφάνιση.
comparison.channels[].labelstringΤο όνομα του OTA για εμφάνιση, π.χ. Booking.com.
comparison.channels[].priceMinorintegerΗ τιμή του OTA για την ίδια διανυκτέρευση, στη μικρότερη υποδιαίρεση, για ίσο ή μικρότερο αριθμό ατόμων από την τιμή του ξενοδοχείου: δείτε τους κανόνες διατύπωσης.
bookUrlstringΗ σελίδα κρατήσεων του ξενοδοχείου, πάντα https. Υπάρχει σε κάθε απάντηση 200.
bookUrlTemplatestring ή nullΗ αναζήτηση κρατήσεων του ξενοδοχείου, με τα {checkin}, {checkout}, {nights} και {adults} για να τα συμπληρώσετε: τις ημερομηνίες σε μορφή YYYY-MM-DD, τις διανυκτερεύσεις και τους ενήλικες ως ακέραιους αριθμούς. null όταν το ξενοδοχείο δεν έχει αποθηκεύσει καμία. Υπάρχει σε κάθε απάντηση 200.
perksobjectΟι παροχές του ίδιου του ξενοδοχείου για έναν πελάτη που κάνει απευθείας κράτηση, π.χ. πρωινό, στο όνομα του ξενοδοχείου. Υπάρχει σε κάθε απάντηση 200. Εμφανίστε τις χωριστά από την τιμή: δείτε τους κανόνες διατύπωσης.
perks.fromstringΤο όνομα στο οποίο αποδίδονται οι παροχές: το όνομα του ξενοδοχείου ή το συντομότερο που έδωσε στο widget του.
perks.itemsarrayΈως δύο παροχές, με τη σειρά με την οποία πρέπει να εμφανίζονται. Κενό όταν το ξενοδοχείο δεν εμφανίζει καμία.
perks.items[].keystringΤο αναγνωριστικό της παροχής, π.χ. breakfast. Για τον κώδικά σας, ποτέ για εμφάνιση.
perks.items[].iconstringΤο αναγνωριστικό του εικονιδίου, π.χ. cup. Για τον κώδικά σας, ποτέ για εμφάνιση.
perks.items[].pathsarrayΤο εικονίδιο ως δεδομένα διαδρομών SVG σε πλέγμα 24 επί 24, μία έως τρεις διαδρομές, που σχεδιάζονται ως γραμμή με στρογγυλεμένα άκρα και χωρίς γέμισμα.
perks.items[].labelobjectΤο όνομα της παροχής για εμφάνιση, με κλειδί τη γλώσσα: en, es, el, it, de και cs. Μπορεί να προστεθούν κι άλλες γλώσσες, οπότε πάρτε τη γλώσσα του πελάτη όταν υπάρχει και το en όταν δεν υπάρχει.
errorstringΜόνο σε απάντηση 400. Τι είναι λάθος στο αίτημα.

Αποτελέσματα σύγκρισης

ΑποτέλεσμαΣημασίαΤι μπορείτε να πείτε
cheapestΚάθε OTA της λίστας είναι ακριβότερο από την απευθείας κράτηση.Την εξοικονόμηση, savingMinor, σε σχέση με το φθηνότερο OTA της λίστας, και την τιμή κάθε OTA.
matchedΚανένα OTA της λίστας δεν είναι φθηνότερο και τουλάχιστον ένα έχει την ίδια τιμή με το ξενοδοχείο.«Η ίδια τιμή με» ένα OTA μόνο όταν το priceMinor του ισούται με το directPriceMinor.
direct_onlyΗ τιμή του ξενοδοχείου είναι το μόνο που μπορεί να ειπωθεί: ένα OTA μπορεί να είναι φθηνότερο, να πουλάει με διαφορετικούς όρους ή να μην πουλάει καθόλου τη διανυκτέρευση.Μόνο την τιμή του ξενοδοχείου.

Παραδείγματα

Μια διανυκτέρευση όπου το ξενοδοχείο είναι το φθηνότερο:

{
  "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" }
      }
    ]
  }
}

Μια διανυκτέρευση με μόνο την τιμή του ξενοδοχείου:

{
  "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" }
      }
    ]
  }
}

Μια διανυκτέρευση που ελέγχεται ακόμη:

{
  "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" }
      }
    ]
  }
}

Αναμονή όσο ο έλεγχος εκτελείται

Το πρώτο αίτημα για μια διανυκτέρευση για την οποία δεν έχει ρωτήσει κανείς ξεκινά έναν έλεγχο και απαντά pending. Οι περισσότεροι έλεγχοι ολοκληρώνονται μέσα σε λίγα δευτερόλεπτα, κάποιοι διαρκούν περισσότερο. Ρωτήστε ξανά μετά από 2 δευτερόλεπτα, έπειτα μετά από 3, μετά από 5 και στη συνέχεια κάθε 8, και σταματήστε μετά από 8 αιτήματα ή 30 δευτερόλεπτα, όποιο συμβεί πρώτο. Το widget περιμένει με τον ίδιο τρόπο. Αν η απάντηση είναι τότε ακόμη pending, απαντήστε χωρίς τιμή, με σύνδεσμο στο bookUrl· ένα αίτημα λίγα λεπτά αργότερα συνήθως βρίσκει την τιμή.

Μην αποθηκεύετε ποτέ στην προσωρινή μνήμη μια απάντηση pending και μη ρωτάτε για διανυκτέρευση για την οποία δεν σας ρώτησε κανείς: κάθε έλεγχος καταναλώνει από το ημερήσιο όριο ελέγχων του ξενοδοχείου.

Επικαιρότητα και προσωρινή αποθήκευση

Το asOf δείχνει πότε βρέθηκε η τιμή. Οι τιμές του ξενοδοχείου ελέγχονται σε τακτά διαστήματα και το API ελέγχου τιμών δίνει την πιο πρόσφατη που έχει, οπότε μια τιμή μπορεί να είναι ώρες ή ημέρες παλιά. Ένα αίτημα ξεκινά νέο έλεγχο μόνο όταν η τιμή είναι παλιά για τη διαμονή του, δηλαδή παλαιότερη από το διάστημα ανάμεσα στους ελέγχους για εκείνη τη διανυκτέρευση: 1 ημέρα για απόψε και τις 6 επόμενες διανυκτερεύσεις, 4 ημέρες έως τη διανυκτέρευση 30 και 20 ημέρες μετά από αυτήν. Μια τιμή για διανυκτέρευση σε μερικούς μήνες μπορεί να είναι 15 ημερών χωρίς να ξεκινά τίποτα. Όταν ένα αίτημα ξεκινά έλεγχο, εφόσον το ξενοδοχείο έχει ακόμη διαθέσιμους ελέγχους, παίρνει και πάλι την παλιά τιμή, και ένα επόμενο αίτημα παίρνει τη νέα. Αναφέρετε πάντα πόσο παλιά είναι η τιμή, όπως κάνει το widget με το Checked 12 min ago και όπως κάνει το παράδειγμα παρακάτω, και χρησιμοποιήστε την τρέχουσα ώρα αν το asOf είναι μεταγενέστερο από το ρολόι σας.

Οι απαντήσεις είναι κοινές για όλους όσοι ρωτούν για την ίδια διανυκτέρευση, μαζί και για το widget του ξενοδοχείου. Μια απάντηση ready αποθηκεύεται στην προσωρινή μνήμη για 60 δευτερόλεπτα και στη συνέχεια εξυπηρετείται για έως 3.600 δευτερόλεπτα ακόμη όσο ανανεώνεται, οπότε μια τιμή μπορεί να φτάσει σε εσάς έως 61 λεπτά αφότου τη λάβει το StayParity: το πρώτο αίτημα μετά από ένα διάστημα χωρίς αιτήματα παίρνει την παλαιότερη απάντηση και το επόμενο τη νέα. Οι απαντήσεις unavailable και 404 αποθηκεύονται για 60 δευτερόλεπτα, οι pending και 400 καθόλου. Η κεφαλίδα Cache-Control λέει το ίδιο και η δική σας προσωρινή μνήμη μπορεί να την ακολουθεί.

Κανόνες διατύπωσης

Διατυπώστε τις απαντήσεις σας με βάση το αποτέλεσμα σύγκρισης, όχι τη σφραγίδα του widget:

  • Αναφέρετε εξοικονόμηση, ή ότι η απευθείας κράτηση είναι η φθηνότερη, μόνο για cheapest.
  • Πείτε «η ίδια τιμή με» ένα OTA μόνο όταν το priceMinor εκείνου του OTA ισούται ακριβώς με το directPriceMinor.
  • Για direct_only, δώστε την τιμή του ξενοδοχείου και τίποτα για τα OTA. Μην πείτε ότι κανένα OTA δεν είναι φθηνότερο, ούτε ότι κάποιο είναι.
  • Αναφέρετε ένα OTA με το label του, ποτέ με το αναγνωριστικό ota.
  • Αναφέρετε τις τιμές όπως δίνονται: ανά διανυκτέρευση, σε currency. Μην τις μετατρέπετε και μην προσθέτετε τίποτα σε αυτές.
  • Μια τιμή αφορά δωμάτιο που χωρά τουλάχιστον τον αριθμό ενηλίκων που ζητήσατε, και μερικές φορές δωμάτιο που χωρά περισσότερους, τόσο για το ξενοδοχείο όσο και για τα OTA. Η τιμή ενός OTA της λίστας αφορά ίσο ή μικρότερο αριθμό ατόμων από την τιμή του ξενοδοχείου, ποτέ μεγαλύτερο. Πείτε τι ζητήσατε, για παράδειγμα «για 2 ενήλικες», και όχι ότι το δωμάτιο χωρά ακριβώς τόσα άτομα.
  • Εμφανίστε τις παροχές του perks χωριστά από την τιμή, στο όνομα του perks.from, όποια κι αν είναι η απάντηση. Είναι υπόσχεση του ξενοδοχείου, όχι του StayParity, και το API ελέγχου τιμών δεν τις ελέγχει: μην υπολογίζετε ποτέ μια παροχή σε τιμή ή σε εξοικονόμηση και μην προσθέτετε ποτέ παροχή που δεν αναφέρει η απάντηση.
  • Για την κράτηση, δώστε σύνδεσμο στο bookUrl, όποια κι αν είναι η απάντηση. Όταν το bookUrlTemplate δεν είναι null και γνωρίζετε τις ημερομηνίες άφιξης και αναχώρησης του πελάτη, δώστε αντί για αυτό σύνδεσμο στο συμπληρωμένο πρότυπο, όπως κάνει η stayUrl παρακάτω. Μην υπολογίζετε ποτέ ημερομηνία αναχώρησης που δεν έδωσε ο πελάτης, και χρησιμοποιήστε το bookUrl όταν το πρότυπο ζητά {adults} και δεν ξέρετε πόσοι είναι.

Λογότυπα καναλιών

Το λογότυπο του widget για ένα OTA βρίσκεται στο https://badge.stayparity.com/widget/marks/{ota}.svg, με βάση το αναγνωριστικό ota του καναλιού: ένα τετράγωνο SVG με το πλακίδιο και το σήμα του OTA όπως τα σχεδιάζει το widget, 22 pixel, εκτός αν ορίσετε άλλο μέγεθος. Αν το widget δεν έχει λογότυπο για ένα OTA, η απάντηση είναι 404, οπότε δείξτε τότε κάτι δικό σας αντί για λογότυπο, όπως το widget δείχνει το πρώτο γράμμα του ονόματος. Τα λογότυπα απαντούν σε κάθε προέλευση και δεν περιέχουν script. Το καθένα αποθηκεύεται στην προσωρινή μνήμη για μία ημέρα και στη συνέχεια εξυπηρετείται για έως 30 ημέρες ακόμη όσο ανανεώνεται, όπως λέει η κεφαλίδα Cache-Control του. Αν η ιστοσελίδα στέλνει Content-Security-Policy, επιτρέψτε την προέλευση στο img-src.

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

Αναφορά πηγής

Όταν το bot ή το widget σας παραθέτει αυτές τις τιμές, σας ζητάμε να αναφέρετε την πηγή τους όπως κάνει το widget: το σήμα του StayParity και μετά «Έλεγχος τιμών από το StayParity», με σύνδεσμο προς το https://stayparity.com. Το σήμα βρίσκεται στο https://badge.stayparity.com/widget/brand/mark.svg για ανοιχτόχρωμο φόντο και στο https://badge.stayparity.com/widget/brand/mark-dark.svg για σκουρόχρωμο, και εξυπηρετείται όπως τα λογότυπα των καναλιών. Ένα bot που απαντά με κείμενο μπορεί να κλείνει με «Έλεγχος τιμών από το StayParity · stayparity.com», όπως κάνει στα αγγλικά το παράδειγμα παρακάτω. Δεν είναι προϋπόθεση: το API ελέγχου τιμών απαντά το ίδιο και χωρίς αυτήν.

<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Έλεγχος τιμών από το Stay<b>Parity</b></a>

Μέτρηση προβολών

Η σελίδα Widget του ξενοδοχείου στο StayParity μετρά πόσο συχνά βλέπουν οι επισκέπτες το widget κρατήσεών του. Μια σελίδα που εμφανίζει δικό της widget με το API ελέγχου τιμών μπορεί επίσης να μετρά τις προβολές του, και η σελίδα Widget τις δείχνει χωριστά από εκείνες του widget κρατήσεων, στην επιλογή Το δικό σας widget: τις προβολές, σε πόσες εμφανίστηκε τιμή, σε πόσες ήταν ορατή στην οθόνη και σε πόσες έγινε κλικ στο Book direct, ανά αποτέλεσμα σύγκρισης, συσκευή και γλώσσα. Η μέτρηση είναι προαιρετική: το API ελέγχου τιμών απαντά το ίδιο και χωρίς αυτήν.

Η σελίδα στέλνει ένα μικρό σώμα στη διεύθυνση:

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

Στείλτε το σώμα ως συμβολοσειρά, την οποία το πρόγραμμα περιήγησης στέλνει ως text/plain, ώστε να μη χρειάζεται CORS preflight. Σώμα οποιουδήποτε άλλου τύπου απορρίπτεται.

Σώμα

ΠεδίοΤύποςΣημασία
keystringΤο κλειδί ενσωμάτωσης του ξενοδοχείου, το ίδιο με το οποίο η σελίδα ρώτησε το API ελέγχου τιμών.
viewbooleantrue στην πρώτη αποστολή μιας προβολής σελίδας, false στη μοναδική επόμενη αποστολή της.
verdictstringΜόνο στην πρώτη αποστολή, όπου είναι υποχρεωτικό. Το verdict της τελευταίας απάντησης ready που έδειξε η σελίδα, ή none αν δεν έδειξε καμία.
devicestringΜόνο στην πρώτη αποστολή, όπου είναι υποχρεωτικό. mobile όταν η οθόνη έχει πλάτος κάτω από 768 pixel, αλλιώς desktop.
langstringΜόνο στην πρώτη αποστολή, όπου είναι υποχρεωτικό. Η γλώσσα του προγράμματος περιήγησης, navigator.language, έως 35 χαρακτήρες.
shownbooleanΜια απάντηση ready εμφανίστηκε στην οθόνη.
inViewbooleanΤουλάχιστον το μισό από ό,τι δείχνει την απάντηση ήταν μέσα στο viewport για ένα δευτερόλεπτο χωρίς διακοπή, ενώ η σελίδα ήταν ορατή.
clickedbooleanΟ επισκέπτης έκανε κλικ στον σύνδεσμο ή στο κουμπί Book direct που εμφανίζεται μαζί με την απάντηση, είτε οδηγεί στο bookUrl είτε ανοίγει την κράτηση του ίδιου του ξενοδοχείου.

Μια ένδειξη που παραλείπεται σημαίνει false, και μια επόμενη αποστολή πρέπει να περιέχει τουλάχιστον μία ένδειξη με τιμή true. Σώμα με πεδίο που δεν υπάρχει στον πίνακα, ή με πεδίο σε λάθος μορφή, δεν μετρά τίποτα.

Η πρώτη αποστολή μιας προβολής σελίδας:

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

Η επόμενη αποστολή της, για μια ένδειξη που ενεργοποιήθηκε στο μεταξύ:

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

Πότε να στέλνετε

  • Μετρήστε μια προβολή μόλις η σελίδα ρωτήσει το API ελέγχου τιμών για τουλάχιστον μία διαμονή. Μια σελίδα που δεν ρώτησε ποτέ δεν μετρά τίποτα.
  • Κάντε την πρώτη αποστολή όταν η σελίδα κρυφτεί (visibilitychange σε hidden, ή pagehide) ή όταν ο επισκέπτης κάνει κλικ στο Book direct, όποιο συμβεί πρώτο.
  • Κάντε το πολύ μία επόμενη αποστολή, μόνο με τις ενδείξεις που ενεργοποιήθηκαν στο μεταξύ, στην επόμενη από αυτές τις στιγμές.
  • Κρατήστε έναν μετρητή ανά κλειδί και σελίδα, ώστε ένα widget που εμφανίζεται δύο φορές να μετρά μία φορά.
  • Μη στέλνετε τίποτα όταν έχει οριστεί το navigator.webdriver.

Η προέλευση της σελίδας

Το beacon μετρά την προβολή για το όνομα τομέα της κεφαλίδας Origin του αιτήματος, την οποία ορίζει το πρόγραμμα περιήγησης. Επομένως, στείλτε το από τη σελίδα και ποτέ από διακομιστή: ένας διακομιστής δεν στέλνει Origin και τα beacon του δεν μετρούν τίποτα. Ένα όνομα τομέα που δεν είναι μία από τις ιστοσελίδες του ξενοδοχείου στο StayParity μετρά στις Άλλες ιστοσελίδες της σελίδας Widget, και το localhost δεν μετρά ποτέ.

Στείλτε το με fetch και keepalive, όπως κάνει το παρακάτω παράδειγμα. Το navigator.sendBeacon λειτουργεί στα περισσότερα προγράμματα περιήγησης, αλλά το Safari το στέλνει χωρίς Origin όταν η Referrer-Policy της σελίδας είναι no-referrer ή same-origin, και τότε δεν μετρά τίποτα.

Όρια

  • Ένα σώμα έχει μέγεθος έως 1 KiB.
  • Μια διεύθυνση μπορεί να στέλνει 30 beacon το λεπτό, κοινά με το widget κρατήσεων του ξενοδοχείου.
  • Ένα ξενοδοχείο μετρά έως 5.000 beacon ανά ημέρα, στη δική του ζώνη ώρας, κοινά με το widget κρατήσεών του. Μετά από αυτό, δεν μετριέται τίποτα έως τα μεσάνυχτα, ώρα ξενοδοχείου.

Έλεγχος των μετρήσεών σας

Το beacon απαντά πάντα 204 χωρίς σώμα, ό,τι κι αν έγινε με όσα στείλατε, οπότε η απάντησή του δεν σας λέει τίποτα. Για να ελέγξετε τη μέτρησή σας, ανοίξτε τη σελίδα στην ιστοσελίδα του ξενοδοχείου, βγείτε από αυτήν και δείτε την κάρτα Σήμερα στη σελίδα Widget του StayParity, στην επιλογή Το δικό σας widget.

Παράδειγμα

Σε JavaScript για πρόγραμμα περιήγησης. Καλέστε την pageView όταν η σελίδα ρωτά για πρώτη φορά το API ελέγχου τιμών με ένα κλειδί, την shown όταν εμφανίζει μια απάντηση ready και την clicked όταν ο επισκέπτης κάνει κλικ στο 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)

Ποσά

Κάθε τιμή είναι ακέραιος στη μικρότερη υποδιαίρεση του νομίσματος, όπως ορίζει το ISO 4217: το 14200 σε EUR είναι 142,00 €. Τα ISK, JPY και KRW δεν έχουν μικρότερη υποδιαίρεση, οπότε το 14200 σε JPY είναι 14.200 ¥. Κάθε άλλο νόμισμα που στέλνει το API ελέγχου τιμών έχει δύο δεκαδικά. Πάρτε τα δεκαδικά από αυτόν τον κανόνα και όχι από τη μορφοποίηση νομισμάτων της πλατφόρμας σας: οι βιβλιοθήκες μορφοποίησης διαφωνούν και κάποιες δεν δίνουν δεκαδικά στα HUF και IDR.

Δοκιμάστε το

Το κλειδί wk_demo απαντά για το Hotel Aurora, το δείγμα ξενοδοχείου στη σελίδα επίδειξης, με εικονικές τιμές για 1 έως 4 ενήλικες και για κάθε διανυκτέρευση του επόμενου έτους. Δεν απαντά ποτέ pending και δεν καταναλώνει ελέγχους κανενός ξενοδοχείου, οπότε μπορείτε να το καλείτε όσο συχνά χρειάζεστε για δοκιμές:

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

Μια απάντηση για bot τύπου WhatsApp, σε JavaScript για Node 18 ή νεότερο, Deno, Bun ή πρόγραμμα περιήγησης. Περιμένει όσο η απάντηση είναι pending, όπως το widget, αναφέρει πόσο παλιά είναι η τιμή και ακολουθεί τους κανόνες διατύπωσης. Η stayUrl δίνει τον σύνδεσμο για τη διαμονή του πελάτη:

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)

Όρια

  • Ένα αίτημα που ξεκινά έλεγχο καταναλώνει έναν από τους 40 ελέγχους του ξενοδοχείου ανά ημέρα UTC, κοινούς με το widget του. Μια απάντηση από την προσωρινή μνήμη ή από τιμή που έχουμε ήδη διαβάσει δεν καταναλώνει τίποτα. Όταν εξαντληθούν, οι διανυκτερεύσεις χωρίς τιμή απαντούν unavailable έως τα μεσάνυχτα UTC και όσες έχουν τιμή κρατούν την τελευταία τους.
  • Το κλειδί είναι δημόσιο: βρίσκεται στην ιστοσελίδα του ξενοδοχείου. Όποιος το έχει λαμβάνει τις ίδιες απαντήσεις με εσάς και το ξενοδοχείο μπορεί να το αντικαταστήσει οποιαδήποτε στιγμή· μετά από αυτό, το παλιό κλειδί απαντά 404.
  • Χρησιμοποιήστε το κλειδί μόνο με τη συμφωνία του ξενοδοχείου. Λειτουργεί μόνο όσο το widget του ξενοδοχείου είναι ενεργό.

Από το πρόγραμμα περιήγησης

Το API ελέγχου τιμών απαντά σε κάθε προέλευση (Access-Control-Allow-Origin: *) και δεν χρειάζεται cookie, οπότε ένα widget μπορεί να το καλέσει από τη σελίδα. Στείλτε ένα απλό GET χωρίς δικές σας κεφαλίδες: το API ελέγχου τιμών δεν απαντά σε CORS preflight. Αν η ιστοσελίδα στέλνει Content-Security-Policy, επιτρέψτε την προέλευση του API:

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

Εκδόσεις

Αυτή είναι η έκδοση 1 του API ελέγχου τιμών και παραμένει ως έχει: κανένα πεδίο δεν μετονομάζεται, δεν αφαιρείται ούτε αλλάζει τύπο, καμία κατάσταση ή αποτέλεσμα σύγκρισης δεν προστίθεται και καθένα διατηρεί τη σημασία του. Μπορεί να προστεθούν πεδία και νομίσματα, οπότε αγνοήστε τα πεδία που δεν γνωρίζετε. Μια αλλαγή που θα έσπαγε τον κώδικά σας θα δημοσιευτεί σε νέα διαδρομή και θα ανακοινωθεί σε αυτή τη σελίδα. Το ίδιο ισχύει για το σώμα του beacon: μπορεί να αποκτήσει προαιρετικά πεδία, αλλά κανένα πεδίο δεν γίνεται υποχρεωτικό, δεν μετονομάζεται ούτε αφαιρείται, και κανένα σώμα που μετρά σήμερα δεν θα πάψει να μετρά.

Η ίδια σύμβαση περιγράφεται στην προδιαγραφή OpenAPI 3.1, μαζί με αυτά τα παραδείγματα.

Σε αυτή τη σελίδα