I messaggi Query sono richieste di aggiornamenti di prezzi o metadati inviate da Google. Vengono utilizzati con le modalità di invio Pull e Prezzo modificato.
L'elemento principale dei messaggi Query è <Query>.
La struttura del messaggio Query dipende dal tipo di messaggio:
Prezzi:Google invia un messaggio Query in cui vengono richiesti gli aggiornamenti sui prezzi per gli hotel specificati.
Metadati: Google invia un messaggio Query in cui vengono richiesti i dati sulla camera e sul pacchetto negli hotel specificati.
Sei tu a definire l'endpoint che Google utilizza per i messaggi Query e le query sui prezzi in tempo reale durante la configurazione iniziale. Per ulteriori informazioni, contatta il tuo Technical Account Manager (TAM).
Google invia un messaggio Query come richiesta POST HTTP con l'intestazione Content-Type
impostata su "application/xml" e l'intestazione User-Agent impostata su
Google-HotelAdsPrices. L'eccezione a questa regola si verifica durante il test manuale dell'integrazione dell'endpoint prezzo tramite Google-TravelAds-Live. Queste query di esempio potrebbero contenere o meno l'intestazione User-Agent.
La formattazione dettagliata dei messaggi Query è disponibile nella pagina Riferimento XML per i messaggi Query.
Messaggi delle query sui prezzi
I messaggi Query sui prezzi specificano le combinazioni di proprietà o itinerario per cui fornisci i prezzi.
Quando riceve un messaggio Query sui pricing, il server deve rispondere con un messaggio
<Transaction> contenente le informazioni sui prezzi richieste.
Per ulteriori informazioni, consulta la sezione Panoramica dei prezzi.
Esistono tre tipi speciali di messaggi Query:
Prezzi in tempo reale: se questa opzione è abilitata, le query vengono inviate quando un utente sfoglia attivamente i prezzi per la proprietà o la combinazione di itinerario specificata e hai un periodo di tempo specificato per rispondere.
Con contesto: se attivati, i suggerimenti sul contesto dell'utente vengono inclusi in ogni query che Google ti invia e riflettono i tipi più comuni di utenti che cercano la proprietà o le combinazioni di itinerari in questione. Seguendo questi consigli, le tue risposte saranno più efficaci.
Metadati: si tratta di una richiesta di dettagli su camere e pacchetti per le proprietà specificate.
Query sui prezzi in tempo reale
Le query sui prezzi in tempo reale sono richieste di aggiornamenti dei prezzi in tempo reale inviate da Google in risposta alle ricerche degli utenti. Google riceve una richiesta di ricerca da un utente per una combinazione hotel o itinerario e, poiché i dati sui prezzi non sono disponibili o non aggiornati, ti chiede un aggiornamento del prezzo al momento della ricerca. Con le query sui prezzi in tempo reale, Google tenta di ottenere un prezzo e di visualizzarlo nei risultati al momento della ricerca.
Tutte le richieste di query sui prezzi in tempo reale hanno un limite di tempo di risposta che solitamente è di 4000 millisecondi. Questo limite è specificato nella richiesta di query sui prezzi in tempo reale. La mancata risposta entro il limite di tempo comporta la mancata partecipazione per l'opportunità specifica. Tuttavia, ti consigliamo di indicare comunque un prezzo in modo che possa essere memorizzato nella cache e utilizzato per opportunità future. La connessione per la risposta rimane aperta per dieci minuti o come specificato nella configurazione del partner.
Anche le query sui prezzi in tempo reale sono contestuali e possono recuperare i prezzi per i seguenti parametri: paese dell'utente, tipo di dispositivo, numero di persone (numero di ospiti) e se gli ospiti sono adulti o bambini. Con le query sui prezzi in tempo reale, puoi mostrare prezzi più aggiornati che corrispondono a ciò che il cliente ha cercato.
Le query sui prezzi in tempo reale sono pensate come meccanismo secondario di aggiornamento dei prezzi. Il meccanismo principale per il ricalcolo dei prezzi è ancora tramite prezzi pull o modificati. Le query sui prezzi in tempo reale aiutano a colmare le lacune nei casi in cui Google non prevede prezzi per le combinazioni di hotel o itinerario.
Regole per l'utilizzo delle query sui prezzi in tempo reale
Non esistono dati memorizzati nella cache per l'itinerario in questione perché l'itinerario richiesto è atipico, ad esempio le date sono molto distanti o l'hotel viene cercato molto raramente.
La data richiesta è una data non predefinita.
. Nota: le date predefinite non sono idonee per le query sui prezzi in tempo reale. Le query sui prezzi in tempo reale vengono richieste solo per le date non predefinite.
Generalmente Google memorizza nella cache i risultati di un prezzo in tempo reale in modo che non vengano più eseguite query sullo stesso hotel o itinerario. Può richiedere combinazioni di un singolo hotel o di itinerario, nonché combinazioni di più hotel o itinerario singolo.
La funzionalità Prezzi in tempo reale con contesto consente a Google di inviare
richieste di prezzi in tempo reale specifiche in base al tipo di dispositivo dell'utente, al paese da cui
effettua la ricerca e al numero di persone, compresi i bambini. Sia il messaggio Query sia il messaggio Transaction vengono espansi in modo da includere l'elemento <Context> che definisce i parametri di ricerca. I prezzi ricevuti dalle
query sui prezzi in tempo reale con contesto possono essere memorizzati nella cache come pacchetto camera,
se si tratta di un prezzo per un numero di persone specifico e come tariffa agevolata,
se si riferisce al paese o al dispositivo di un utente.
Con query contestuali
Con le query di contesto, le query di contesto sono richieste regolari di aggiornamento del nostro database per le combinazioni di proprietà o itinerario specificate. Contengono un elenco di contesti utente popolari per queste combinazioni. Se utilizzi le tariffe agevolate, l'invio di tariffe per tutti i possibili contesti utente può essere costoso, pertanto puoi utilizzare questo elenco di contesti utente per limitare la risposta. I prezzi restituiti solo per i contesti utente specificati coprono la stragrande maggioranza delle query pertinenti degli utenti.
Messaggi query sui metadati
I messaggi query sui metadati contengono dettagli sulle informazioni su camere e pacchetti per le proprietà specificate.
Quando ricevi un messaggio Query sui metadati, devi rispondere con un messaggio <Transaction> che specifica i prezzi per le proprietà richieste negli elementi <Result>.
Per ulteriori informazioni, consulta la sezione Definire i metadati di camere e pacchetti.
Query di controllo
Questa sezione descrive come puoi controllare quali proprietà e itinerari possono essere oggetto dei messaggi Query di Google.
Confini degli itinerari
Puoi determinare i possibili limiti delle query sui prezzi utilizzando
<ItineraryCapabilities>. Sei tu a definire le regole che determinano l'intervallo di date
e le durate massime dei soggiorni supportati.
Puoi impostare valori predefiniti per <MaxAdvancePurchase> e <MaxLengthOfStay>
che si applicano a tutte le combinazioni di hotel o itinerario. Puoi anche definire queste
impostazioni per gruppi di hotel.
Esempi di messaggi Query
Questa sezione mostra diversi esempi di messaggi Query sui prezzi e un messaggio Query sui metadati. Ulteriori esempi sono disponibili nella sezione Riferimento XML per le query.
Itinerario di esempio
L'esempio seguente mostra un <Query> di prezzo che richiede aggiornamenti dei prezzi per 4 hotel, disponibili per 3 notti, a partire dal 23 maggio 2023:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>3</Nights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
In questo esempio vengono richiesti gli aggiornamenti dei prezzi per ciascun hotel:
5/23/18 - 6/26/18
Esempio di query sui prezzi in tempo reale
L'esempio seguente mostra una query sui prezzi in tempo reale con un tempo di risposta massimo di 500 millisecondi:
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<!-- Note that the latencySensitive attribute is not present by default but can
be configured to be displayed, on request, by Google. This attribute is only
displayed for a Live Pricing Query request -->
<Checkin>2023-05-23</Checkin>
<Nights>2</Nights>
<DeadlineMs>500</DeadlineMs>
<!-- The deadline represents the timeframe by which a response will need to be
received by. This element is only displayed for a Live Pricing Query request -->
<PropertyList>
<Property>6781291</Property>
</PropertyList>
<!-- Note that Context tags are potentially repeatable -->
<Context>
<!-- The total number of guests occupying the room (adults+children) -->
<Occupancy>3</Occupancy>
<OccupancyDetails>
<NumAdults>2</NumAdults>
<!-- In this example one of the 3 guests is a 5yr old child -->
<Children>
<Child age="5"/>
</Children>
</OccupancyDetails>
<!-- The user was located in the US when this search was made -->
<UserCountry>US</UserCountry>
<!-- The user was searching from a mobile device at the time of search -->
<UserDevice>mobile</UserDevice>
</Context>
</Query>
In questo esempio viene richiesto un prezzo per un singolo hotel:
6/23/23 - 6/25/23
Un esempio di messaggio Transaction di risposta a questa query è disponibile nella sezione Riferimento XML per prezzi e inventario delle camere (messaggi Transaction).
Esempio di query di contesto
L'esempio seguente mostra un esempio di query con contesto:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>2</Nights>
<PropertyContextList>
<PropertyContext>
<Property>8675309</Property>
<!-- In the future, occupancy and device might be specified -->
<Context><UserCountry>US</UserCountry></Context>
<Context><UserCountry>GB</UserCountry></Context>
</PropertyContext>
<PropertyContext>
<Property>8675310</Property>
<Property>8675311</Property>
<Context><UserCountry>CA</UserCountry></Context>
</PropertyContext>
</PropertyContextList>
</Query>
Con le query di contesto, specifica solo il contesto del paese dell'utente. In futuro, queste query potrebbero specificare anche il dispositivo dell'utente e il numero di persone.
Intervalli di date di check-in
Se utilizzi la modalità Prezzo modificato, la struttura del messaggio Query dipende dal tipo di suggerimento che utilizzi per gli intervalli di date di check-in, gli itinerari esatti o gli itinerari con intervallo di date. Per ulteriori informazioni su ciascuno di questi tipi di suggerimenti, consulta la sezione Messaggi Hint Response.
L'esempio seguente mostra un messaggio <Query> sui prezzi per gli intervalli di date di check-in:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<FirstDate>2023-05-23</FirstDate>
<LastDate>2023-05-26</LastDate>
<Nights>3</Nights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
In questo esempio vengono richiesti gli aggiornamenti dei prezzi dei seguenti soggiorni (per ciascun hotel):
5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/24/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23
Soggiorni con intervallo di date
L'esempio seguente mostra un messaggio <Query> sui prezzi per i soggiorni
con intervallo di date:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<FirstDate>2023-05-23</FirstDate>
<LastDate>2023-05-26</LastDate>
<AffectedNights>3</AffectedNights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
In questo esempio vengono richiesti gli aggiornamenti dei prezzi per ciascun hotel:
5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/25/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23
Più i soggiorni che sono iniziati prima della notte specificata (che è inclusa):
5/20/23 - 5/23/23
5/21/23 - 5/23/23
5/21/23 - 5/24/23
5/22/23 - 5/23/23
5/22/23 - 5/24/23
5/22/23 - 5/25/23
Messaggio query sui metadati
L'esempio seguente mostra un messaggio <Query> che richiede aggiornamenti
dei metadati relativi alle informazioni su camere e pacchetti per diverse proprietà:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<HotelInfoProperties>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</HotelInfoProperties>
</Query>
Devi rispondere a questo tipo di messaggio Query con un messaggio Transaction che definisce i metadati di camere e pacchetti. Per ulteriori informazioni, consulta la sezione Definire i metadati di camere e pacchetti.