Riferimento XML per query e suggerimenti

Questa sezione fornisce un riferimento per i messaggi Hint Request, i messaggi Hint Response e i messaggi Query basati su XML di Google.

<Hint> (messaggio Hint Response)

L'elemento principale di un messaggio Hint Response. I messaggi Hint Response specificano le combinazioni hotel/itinerario di cui ridefinire il prezzo. Sono la tua risposta a un messaggio Hint Request di Google.

Un messaggio Hint Response deve specificare solo gli hotel i cui prezzi sono cambiati dall'ultima volta che Google ha ricevuto un messaggio Hint Response riuscito dai tuoi server.

I messaggi Hint Response utilizzano uno dei seguenti metodi per specificare gli hotel e gli itinerari che Google deve rideterminare i prezzi:

  • Itinerari esatti: una combinazione di data di check-in e durata del soggiorno.

  • Intervalli di date di check-in: specifica un intervallo di date di check-in, che inizia con la prima data di check-in e termina con l'ultima data di check-in.

  • Soggiorni con intervallo di date (o itinerario con intervallo di date)

Ciascuno di questi metodi richiede una sintassi diversa per il messaggio Hint Response.

Per ulteriori informazioni, consulta la sezione Messaggi Hint Response.

Sintassi

L'elemento <Hint> utilizza una sintassi diversa, a seconda del tipo di messaggio Hint Response:

Itinerari esatti

Di seguito viene mostrata la sintassi per gli itinerari esatti in un messaggio Hint Response:

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>hotel_ID</Property>
    ...
    <Stay>
      <CheckInDate>checkin_date</CheckInDate>
      <LengthOfStay>number_of_nights</LengthOfStay>
    </Stay>
  </Item>
  ...
</Hint>

Intervalli di check-in

Di seguito viene mostrata la sintassi per gli intervalli di check-in in un messaggio Hint Response:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "checkin_range" in your
         QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

    <!-- Required -->
    <FirstDate>first_checkin_date</FirstDate>
    <!-- Required -->
    <LastDate>last_checkin_date</LastDate>
  </Item>
  ...
</Hint>

Soggiorni con intervallo di date

Di seguito è riportata la sintassi per i soggiorni con intervallo di date in un messaggio Hint Response:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "affected_dates" in your
         QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>first_date</FirstDate>

      <!-- Optional -->
      <LastDate>last_date</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

Attributi

L'elemento <Hint> contiene un attributo facoltativo: id. Se fornito, viene incluso come attributo hintId in <Query> messaggi inviati in base a questo <Hint>.

Elementi secondari

L'elemento <Hint> ha i seguenti elementi secondari:

Elemento secondario Campo obbligatorio? Tipo Tipo di risposta Suggerimento Descrizione
<CheckInDate> Required Date Itinerari esatti La data del check-in per l'itinerario.
<FirstDate> Required Date Intervalli di check-in e itinerari con intervallo di date La prima data dell'intervallo di date per un messaggio Hint Response relativo a un intervallo di check-in o a un soggiorno con intervallo di date. Le date sono incluse.
<Item> Required Object Tutte Un contenitore per l'hotel/itinerario da aggiornare.
<LastDate> Required* Date Intervalli di check-in e itinerari con intervallo di date

L'ultima data dell'intervallo di date per un messaggio Hint Response relativo a un intervallo di check-in o a un soggiorno con intervallo di date. Le date sono incluse.

* Questo elemento è facoltativo per i soggiorni con intervallo di date.

<LengthOfStay> Required integer Itinerari esatti Il numero di notti per l'itinerario, espresso come un numero intero positivo.
<Property> Required string Tutte

L'ID di un hotel, utilizzando lo stesso ID dell'elenco hotel. Il numero di elementi <Property> che puoi specificare in un singolo blocco <Item> è determinato dal tipo di messaggio Hint Response:

  • Itinerari esatti: fino a 100 hotel.
  • Intervalli per il check-in: più di uno se imposti <MultipleItineraries> su "checkin_range" nel messaggio <QueryControl>.
  • Soggiorno con intervallo di date: più di uno se imposti <MultipleItineraries> su "affected_dates" nel tuo messaggio <QueryControl>.
<Stay> Required Object Itinerari esatti Un container per gli elementi <CheckinDate> e <LengthOfStay> in un messaggio Hint Response esatto per l'itinerario. Ogni elemento <Item> può contenere un solo valore <Stay>.
<StaysIncludingRange> Required Object Itinerari con intervallo di date Un container per gli elementi <FirstDate> e <LastDate> in un messaggio Hint Response con soggiorno con intervallo di date.

Esempi

Itinerari esatti

L'esempio seguente definisce più itinerari per una singola proprietà in un messaggio Hint Response:

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>4</LengthOfStay>
    </Stay>
  </Item>
</Hint>

Intervalli di check-in

L'esempio seguente specifica due hotel i cui prezzi sono stati modificati e devono essere recuperati di nuovo. Google recupera tutti gli itinerari tra il 3 e il 6 luglio per le proprietà 12345 e 67890:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Property>67890</Property>
    <FirstDate>2018-07-03</FirstDate>
    <LastDate>2018-07-06</LastDate>
  </Item>
</Hint>

Tieni presente che, affinché un messaggio relativo all'intervallo di check-in possa specificare più proprietà in un singolo elemento <Item>, il valore di <MultipleItineraries> in <QueryControl> deve essere impostato su "checkin_range".

Soggiorni con intervallo di date

L'esempio seguente mostra due diversi utilizzi dei soggiorni con intervallo di date, uno per un intervallo di notti e l'altro per una singola notte:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <!-- Google fetches prices for all itineraries (first and last date are set) -->
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
      <LastDate>2018-07-06</LastDate>
    </StaysIncludingRange>
  </Item>

  <!-- Google fetches prices for a single night (first date only) -->
  <Item>
    <Property>67890</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
    </StaysIncludingRange>
  </Item>
</Hint>

Tieni presente che, affinché un messaggio relativo a un soggiorno con intervallo di date possa specificare più proprietà in un singolo elemento <Item>, il valore di <MultipleItineraries> in <QueryControl> deve essere impostato su "affected_dates".

Per ognuno di questi esempi, Google risponde con un elemento <Query> e devi quindi rispondere con un elemento <Transaction> che include gli aggiornamenti dei prezzi per gli hotel/gli itinerari specificati.

<HintRequest>

L'elemento principale di un messaggio Hint Request. Google invia un messaggio Hint Request al tuo server e si aspetta una risposta che specifichi gli hotel e gli itinerari i cui prezzi sono cambiati dall'ultima volta in cui Google ha ricevuto un messaggio Hint Response riuscito dal tuo server.

In caso di modifiche al prezzo, Google invia un elemento <Query> che recupera i dati aggiornati sui prezzi per gli hotel e gli itinerari indicati.

Per ulteriori informazioni, consulta la sezione Messaggi Hint Request.

Sintassi

L'elemento <HintRequest> utilizza la seguente sintassi:

Sintassi

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

Attributi

L'elemento <HintRequest> non ha attributi.

Elementi secondari

L'elemento <HintRequest> ha i seguenti elementi secondari:

Elemento secondario Tipo Descrizione
<LastFetchTime> DateTime L'ultima volta che Google è riuscita a ricevere un messaggio Hint Response a un messaggio Hint Request.

Se questo periodo è antecedente all'ultima volta in cui hai aggiornato i prezzi sul tuo server, devi rispondere con un messaggio Hint Response che specifica quali hotel sono stati modificati.

Se di recente non è stato eseguito un recupero, questo verrà impostato su un valore di intervallo fisso (per evitare problemi più gravi con backlog di grandi dimensioni). L'attuale valore dell'intervallo fisso è 1000 secondi, ma è soggetto a modifiche.

Per ulteriori informazioni, consulta la sezione Messaggi Hint Response.

Esempi

Nell'esempio seguente viene mostrato un messaggio Hint Request:

Messaggio Hint Request

L'esempio seguente mostra un messaggio Hint Request:

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="ABCDEF" timestamp="2018-06-07T16:20:00Z">
  <LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>

<Query>

L'elemento principale di un messaggio Query. I messaggi Query sono richieste da Google di aggiornamenti di prezzi o metadati. Vengono utilizzati con le modalità di invio Pull e Prezzo modificato.

Esistono tre tipi di messaggi Query:

  • Prezzi in tempo reale: Google risponde a una richiesta specifica di un utente, chiedendo un aggiornamento dei prezzi in tempo reale. Quando i partner ricevono un messaggio Live pricing query, devono rispondere con un messaggio <Transaction> contenente le informazioni sui prezzi richieste negli elementi <Result>.

  • Con prezzi contestuali: Google aggiorna la cache dei prezzi in base ai contesti storici popolari. Quando ricevi un messaggio With context query, devi rispondere con un messaggio <Transaction> contenente le informazioni sui prezzi richieste negli elementi <Result>.

  • Metadati: Google richiede aggiornamenti dei metadati per le camere e i pacchetti camera per gli hotel specificati. Quando ricevi un messaggio Metadata Query, dovresti rispondere con un messaggio <Transaction> che specifica i dati relativi alle camere e ai pacchetti camera negli elementi <PropertyDataSet>.

Per ulteriori informazioni, consulta la sezione Panoramica dei prezzi per le query sui prezzi e Metadati dei pacchetti camera per le query sui metadati.

Di seguito viene descritta la sintassi per i tre tipi diversi.

Sintassi

L'elemento <Query> utilizza la seguente sintassi:

Prezzi in tempo reale

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
  <!-- See documentation below for <Context> -->
  <Context>
   ...
  </Context>
</Query>

Con contesto

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyContextList>
    <PropertyContext>
      <Property>hotel_id</Property>
      ...
      <!-- See documentation below for <Context> -->
      <Context>
      ...
      </Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

Metadati

<HotelInfoProperties>
  <Property>property_ID</Property>
  ...
</HotelInfoProperties>

Attributi

L'elemento <Query> può contenere un attributo: latencySensitive.

L'attributo latencySensitive è facoltativo. Se fornito e impostato su true, indica che la query è un Live Pricing Query. Per consentire a Google di inviare query con l'attributo latencySensitive, rivolgiti al tuo Technical Account Manager (TAM).

Elementi secondari

L'elemento <Query> ha i seguenti elementi secondari:

Elemento secondario Tipo di query Tipo Descrizione
<AffectedNights> Pricing integer Il numero di notti per un soggiorno con intervallo di date. Questo elemento viene utilizzato solo per le query sui prezzi dei soggiorni con intervallo di date utilizzate con la modalità Prezzo modificato.
<Checkin> Pricing Date Le date di una specifica variazione di prezzo.
<Context> Pricing (Live Pricing Queries only) <Context> Per le query sui prezzi in tempo reale, specifica alcuni parametri in base ai quali viene eseguita la query. Gli elementi secondari includono:
  • <Occupancy>: il numero totale di ospiti
  • <OccupancyDetails>: il tipo di ospiti, ad esempio adulti o bambini
  • <UserCountry>: il paese in cui si trova l'utente
  • <UserDevice>: il tipo di dispositivo utilizzato dall'ospite per cercare un hotel, ad esempio "mobile", "tablet" o "desktop".

L'elemento <Context> può essere ripetuto in una singola richiesta, consentendo di eseguire query per numeri di persone diverse. Consulta la sezione <Context> per un elenco di elementi secondari, la sintassi e gli esempi.

<FirstDate> Pricing Date La data di inizio per una serie di itinerari a cui si applica il prezzo. Questo elemento viene utilizzato solo per le query sui prezzi dell'intervallo di date di check-in utilizzate con la modalità Prezzo modificato.
<HotelInfoProperties> Metadata string Una o più proprietà per le quali Google vuole aggiornare i metadati di camere e pacchetti camera in un messaggio Query dei metadati. Questo elemento può contenere uno o più elementi <Property> che specificano gli ID proprietà hotel.
<LastDate> Pricing Date La data di fine per una serie di itinerari a cui si applica il prezzo. Questo elemento viene utilizzato solo per le query sui prezzi relative a intervalli di date di check-in utilizzate con la modalità Pull + Hint.
<Nights> Pricing integer Il numero di notti per un determinato itinerario, fino a 30.
<PropertyList> Pricing Object

Uno o più ID per hotel che richiedono aggiornamenti dei prezzi.

Definisci ciascun hotel in un elemento <Property>. Il valore è una stringa che corrisponde a un ID hotel nel tuo elenco di hotel. Ad esempio:

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

Esempi

Query sui prezzi

L'esempio seguente mostra un messaggio Query sui prezzi che richiede gli aggiornamenti dei prezzi per un insieme di hotel, disponibili per 3 notti e a partire dal 10 giugno 2018:

<?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>

Query sui prezzi in tempo reale

L'esempio seguente mostra una query sui prezzi in tempo reale con un limite di tempo di risposta di 500 millisecondi:

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="8"/>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

Con query di 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>

Query sui metadati

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

Per ulteriori esempi, tra cui le query sui prezzi per soggiorni con intervallo di date e intervalli di date di check-in, consulta gli esempi di messaggi di Query.

<Context>

L'elemento <Context> descrive le informazioni relative a un Live pricing query, inclusi il numero e il tipo di ospiti, il paese e il dispositivo dell'utente.

Non verranno mai utilizzati più <Context> con paesi o dispositivi dell'utente diversi. Se vengono utilizzati più <Context> per eseguire query per più persone, fornisci ogni prezzo per il numero di persone come pacchetto camera aggiuntivo per la struttura/l'itinerario corrispondente. Ogni proprietà/itinerario deve avere un singolo blocco <Result> con i prezzi per più persone.

Per i dettagli della risposta alla query <Context>, consulta <OccupancyDetails>.

Sintassi

L'elemento <Context> utilizza la seguente sintassi:

Sintassi

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>date</Checkin>
  <Nights>number_of_nights</Nights>
  <DeadlineMs>number_of_milliseconds</DeadlineMs>
  <PropertyList>
    <Property>property_ID</Property>
  </PropertyList>
  <Context>
  <Occupancy>total_number_of_guests</Occupancy>
  <OccupancyDetails>
    <NumAdults>number_of_adults</NumAdults>
    <Children>
      <Child age=age_of_one_child_guest/>
      <Child age=age_of_one_child_guest/>
    </Children>
  </OccupancyDetails>
  <UserCountry>end_user_country</UserCountry>
  <UserDevice>user_device_type</UserDevice>
  </Context>
</Query>

Elementi secondari

L'elemento <Context> ha i seguenti elementi secondari:

Elemento secondario Tipo di query Tipo Descrizione
<Occupancy> Pricing integer Specifica il numero totale di ospiti.

Sebbene non siano obbligatorie, le query con <Occupancy> dovrebbero generare un messaggio Transaction con i pacchetti camera appropriati definiti per ogni <Occupancy> oggetto di query.

Nota:<Occupancy> potrebbe non essere sempre presente in una query. In questi casi, devi restituire i prezzi per tutti i valori di numero di persone.

<OccupancyDetails> Pricing Object È preceduto da <Occupancy>. Specifica gli ospiti per tipo, tra cui:

  • <NumAdults>: numero di ospiti adulti
  • <Children> e <Child="age">: specifica quali ospiti sono bambini (in genere tra 0 e 17 anni) e, facoltativamente, include l'età di ogni bambino.
  • Sebbene non siano obbligatorie, le query con <OccupancyDetails> dovrebbero generare un messaggio Transaction con i pacchetti camera appropriati definiti per ogni <Occupancy> oggetto di query.

    Nota: <OccupancyDetails> potrebbe non essere sempre visibile in una query. In questi casi, devi presumere che tutti gli ospiti siano adulti.

<UserCountry> Pricing string

Filtra le tariffe in base al paese in cui si trova l'utente. Il valore è un codice paese di due lettere, come “US” per gli Stati Uniti, o un codice regione, come "EU" per "Europa".

Le query con <UserCountry> definito devono generare un messaggio Transaction con il blocco <Rates> appropriato definito per il paese della query.

<UserDevice> Pricing string

Filtra le tariffe in base al tipo di dispositivo da cui l'utente esegue la ricerca. Valori possibili:

  • mobile
  • desktop
  • tablet

Le query con <UserDevice> definito devono generare un messaggio Transaction con il blocco <Rates> appropriato definito per il tipo di dispositivo oggetto della query.

Esempi

Numero di persone

L'esempio seguente mostra una query sui prezzi in tempo reale per <Occupancy> all'interno di <Context>. La query sui prezzi in tempo reale è per 3 ospiti adulti.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

Dettagli sul numero di persone

L'esempio seguente mostra una query sui prezzi in tempo reale con <OccupancyDetails> in <Context>. La query sui prezzi in tempo reale è per 4 ospiti, 2 dei quali sono bambini, e cerca una tariffa applicabile a un ospite negli Stati Uniti che prenota da un dispositivo mobile:

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="4"/>
        <Child age="12"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

Più contesti

L'esempio seguente mostra l'utilizzo di un elemento <Context> aggiuntivo in una query sui prezzi in tempo reale.

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
  <Context>
    <Occupancy>6</Occupancy>
    <OccupancyDetails>
      <NumAdults>4</NumAdults>
      <Children>
        <Child age="6"/>
        <Child age="10"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>