Messaggi Query

I messaggi Query sono richieste di aggiornamenti relativi a 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 sulle camere e sui pacchetti negli hotel specificati.

Devi definire l'endpoint utilizzato da Google 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 non contenere l'intestazione User-Agent.

La formattazione dettagliata dei messaggi Query è disponibile nella pagina Riferimento XML per i messaggi Query.

Messaggi Query sui prezzi

I messaggi Query sui prezzi specificano le combinazioni proprietà e itinerario per cui fornisci i prezzi.

Quando riceve un messaggio Query sui prezzi, il tuo 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:

  1. Prezzi in tempo reale:se questa opzione è attiva, le query vengono inviate quando un utente sta sfogliando attivamente i prezzi per la combinazione di proprietà o itinerario specificata e hai un periodo di tempo specificato per rispondere.

  2. Con contesto:se questa opzione è attiva, i suggerimenti sul contesto dell'utente vengono inclusi in ogni query che Google ti invia e i suggerimenti riflettono i tipi più comuni di utenti che cercano le combinazioni di proprietà o itinerari specifiche. Se segui questi consigli, l'efficienza delle tue risposte potrebbe aumentare.

  3. 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 sui prezzi in tempo reale effettuate da Google in risposta a ricerche degli utenti. Google riceve una richiesta di ricerca da un utente per una combinazione hotel o itinerario e poiché i dati relativi al prezzo non sono disponibili o non sono aggiornati, ti richiede un aggiornamento con il prezzo al momento della ricerca. Con le query sui prezzi in tempo reale, Google tenta di ottenere un prezzo e di mostrarlo nei risultati al momento della ricerca.

Tutte le richieste Query sui prezzi in tempo reale hanno un limite di tempo di risposta, in genere fino a 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 all'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 ospiti adulti o bambini. Con le query sui prezzi in tempo reale, puoi mostrare prezzi più aggiornati che corrispondono a quanto ricercato dai clienti.

Le query sui prezzi in tempo reale sono pensate come meccanismo secondario di aggiornamento dei prezzi. Il meccanismo principale per la rideterminazione dei prezzi prevede comunque le modalità Pull o Prezzo modificato. Le query sui prezzi in tempo reale consentono di colmare le lacune nei dati nei casi in cui Google non dispone dei prezzi per le combinazioni hotel/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 avanti nel tempo o perché 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.

Solitamente Google memorizza nella cache i risultati di un prezzo in tempo reale per evitare che lo stesso hotel o itinerario venga cercato con una nuova query. Può richiedere combinazioni di un singolo hotel o itinerario, nonché combinazioni di più hotel o un singolo itinerario.

La funzionalità Prezzi in tempo reale con contesto consente a Google di inviare richieste specifiche sui prezzi in tempo reale in base al tipo di dispositivo dell'utente, al paese da cui effettua la ricerca e al numero di persone, inclusi i bambini. Sia il messaggio Query che il messaggio Transaction sono espansi per 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 un Pacchetto camera, se si tratta di un prezzo per un numero di persone specifico, e come tariffa agevolata, se per paese o dispositivo dell'utente.

Query con contesto

Le query contestuali sono richieste regolari di aggiornamento del nostro database per le combinazioni di proprietà o itinerari specificate. Contengono un elenco di contesti utente che sono popolari per queste combinazioni. Se vengono utilizzate le tariffe agevolate, l'invio di tariffe per tutti i possibili contesti utente potrebbe essere costoso, pertanto puoi utilizzare questo elenco di contesti utente per limitare la risposta. La restituzione dei prezzi solo per i contesti utente specificati copre la stragrande maggioranza delle query utente pertinenti.

Se ti interessa ricevere query con contesto, contatta il tuo Technical Account Manager (TAM). Possono confermare che sei pronto a ricevere questi messaggi e quindi apportare una modifica alla configurazione per iniziare a inviarti i contesti utente nelle query.

Messaggi Query sui metadati

I messaggi Query sui metadati contengono i dettagli sulle informazioni relative a 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 controllare quali proprietà e itinerari possono essere oggetto di messaggi Query da Google.

Limiti degli itinerari

Puoi determinare i possibili limiti delle query sui prezzi utilizzando <ItineraryCapabilities>. Devi definire le regole che determinano l'intervallo di date e la durata massima dei soggiorni supportati.

Puoi impostare valori predefiniti per <MaxAdvancePurchase> e <MaxLengthOfStay> applicabili a tutte le combinazioni hotel o itinerario. Puoi anche definire queste impostazioni per gruppi di hotel.

Esempi di messaggi Query

In questa sezione vengono mostrati alcuni esempi di messaggi Query sui prezzi e un messaggio Query sui metadati. Ulteriori esempi sono disponibili nella sezione Riferimento XML per i messaggi Query.

Itinerario di esempio

L'esempio seguente mostra un elemento <Query> relativo ai prezzi che richiede aggiornamenti dei prezzi di 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 limite di risposta 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 il prezzo per un singolo hotel:

6/23/23 - 6/25/23

Per un esempio di messaggio Transaction di risposta a questa query, consulta la sezione Riferimento XML per prezzi e inventario delle camere (messaggi Transaction).

Esempi di query con contesto

Di seguito sono riportati alcuni esempi di query con contesto:

Query di base 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, 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>

Query con contesto, incluso il numero di persone della richiesta

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2025-07-10</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <Context>
        <UserCountry>US</UserCountry>
      </Context>
      <Occupancy>3</Occupancy>
      <OccupancyDetails>
        <NumAdults>2</NumAdults>
        <Children>
          <Child age="7"/>
        </Children>
      </OccupancyDetails>
    </PropertyContext>
    <PropertyContext>
      <Property>8675310</Property>
      <Context>
        <UserCountry>GB</UserCountry>
      </Context>
      <Occupancy>1</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
      </OccupancyDetails>
    </PropertyContext>
  </PropertyContextList>
</Query>

Con le query contestuali viene specificato solo il contesto del paese dell'utente. In futuro, queste query potrebbero specificare anche il dispositivo dell'utente.

Intervalli di date di check-in

Se utilizzi la modalità Prezzo modificato, la struttura del messaggio Query dipende dal tipo di messaggio Hint utilizzato 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 per i 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 l'aggiornamento dei metadati per le 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 in cui definisci i metadati di camere e pacchetti. Per ulteriori informazioni, consulta la sezione Definire i metadati di camere e pacchetti.