Referência XML de consultas e dicas

Esta seção fornece uma referência para as mensagens de solicitação de sugestão, mensagens de resposta de sugestão e mensagens de consulta baseadas em XML do Google.

<Hint> (mensagem de resposta de dica)

O elemento raiz de uma mensagem de resposta de dica. As mensagens de resposta de dicas especificam quais combinações de hotéis ou itinerários devem ter o preço reajustado. Elas são sua resposta a uma mensagem de solicitação de dica do Google.

Uma mensagem de resposta de sugestão deve especificar apenas os hotéis cujos preços mudaram desde a última vez que o Google recebeu uma resposta de sugestão dos seus servidores.

As mensagens de resposta de dicas usam um dos seguintes métodos para especificar quais hotéis e itinerários o Google deve reajustar o preço:

  • Itinerários exatos: uma combinação de data de check-in e duração da estadia.

  • Períodos de check-in: especifica um período de check-in, começando com a primeira data de check-in e terminando com a última.

  • Estadias em um intervalo (ou itinerários em um intervalo)

Cada um desses métodos requer uma sintaxe diferente para a mensagem de resposta de dicas.

Para mais informações, consulte Mensagens de resposta de dicas.

Sintaxe

O elemento <Hint> usa uma sintaxe diferente, dependendo do tipo de mensagem de resposta de sugestão:

Itinerários exatos

Confira a seguir a sintaxe para itinerários exatos em uma mensagem de resposta de sugestão:

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

Intervalos de check-in

Confira a seguir a sintaxe para intervalos de check-in em uma mensagem de resposta de sugestão:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

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

Estadias em intervalos

Confira abaixo a sintaxe para estadias em um intervalo em uma mensagem de resposta de sugestão:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

Atributos

O elemento <Hint> contém um atributo opcional: id. Quando for fornecido, ele será incluído como o atributo hintId nas mensagens <Query> enviadas com base nesse <Hint>.

Elementos filhos

O elemento <Hint> tem os seguintes elementos filhos:

Elemento filho Obrigatório? Tipo Tipo de resposta de dica Descrição
<CheckInDate> Required Date Itinerários exatos A data de check-in do itinerário.
<FirstDate> Required Date Intervalos de check-in e itinerários com intervalos A primeira data do período de check-in ou da mensagem de resposta de sugestão de estadia. As datas são inclusivas.
<Item> Required Object Todos Um contêiner para o hotel/itinerário ser atualizado.
<LastDate> Required* Date Intervalos de check-in e itinerários com intervalos

A última data do período de check-in ou a mensagem de resposta de sugestão de estadia. As datas são inclusivas.

* Este elemento é opcional para estadias em um período.
<LengthOfStay> Required integer Itinerários exatos O número de noites do itinerário, expresso como um número inteiro positivo.
<Property> Required string Todos

O ID de um hotel, usando o mesmo ID da Lista de hotéis. O número de elementos <Property> que podem ser especificados em um único bloco <Item> é determinado pelo tipo de mensagem de resposta de sugestão:

  • Itinerários exatos: até 100 hotéis.
  • Intervalos de check-in: mais de um se você definir <MultipleItineraries> como "checkin_range" na mensagem <QueryControl>.
  • Estadia com intervalo: mais de uma, se você definir <MultipleItineraries> como "affected_dates" na mensagem <QueryControl>.
<Stay> Required Object Itinerários exatos Um contêiner para os elementos <CheckinDate> e <LengthOfStay> em uma mensagem de resposta de sugestão de itinerário exato. Cada <Item> pode conter apenas um <Stay>.
<StaysIncludingRange> Required Object Itinerários com intervalos Um contêiner para os elementos <FirstDate> e <LastDate> em uma mensagem de resposta de sugestão de estadia com intervalo.

Exemplos

Itinerários exatos

O exemplo a seguir define vários itinerários para uma única propriedade e uma mensagem de resposta de sugestão:

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

Intervalos de check-in

O exemplo a seguir especifica dois hotéis cujos preços mudaram e precisam ser buscados novamente. O Google recebe todos os itinerários entre 3 e 6 de julho para as propriedades 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>

Estadias em intervalos

O exemplo a seguir mostra dois usos diferentes de estadias com intervalos, um para um intervalo de noites e outro para uma única noite:

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

Para cada um desses exemplos, o Google responde com um <Query>, e você precisa responder com um <Transaction> que inclua atualizações de preço para os hotéis/itinerários especificados.

<HintRequest>

O elemento raiz de uma mensagem de solicitação de dica. O Google envia uma mensagem de solicitação de sugestão para seu servidor e espera uma resposta que especifique os hotéis e os itinerários cujos preços mudaram desde a última vez que o Google recebeu uma resposta de sugestão do seu servidor.

Se houver mudanças nos preços, o Google vai enviar um <Query> que vai buscar os dados de preços atualizados dos hotéis e itinerários indicados.

Para mais informações, consulte Mensagens de solicitação de dicas.

Sintaxe

O elemento <HintRequest> usa a seguinte sintaxe:

Sintaxe

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

Atributos

O elemento <HintRequest> não tem atributos.

Elementos filhos

O elemento <HintRequest> tem os seguintes elementos filhos:

Elemento filho Tipo Descrição
<LastFetchTime> DateTime A última vez que o Google conseguiu uma mensagem de resposta a uma solicitação de dica.

Se esse horário for anterior à última vez que você atualizou os preços no servidor, responda com uma mensagem de resposta de sugestão especificando quais hotéis foram alterados.

Se não houver uma busca recente bem-sucedida, ela será definida como um valor de intervalo fixo para evitar problemas mais graves com grandes pendências. O valor atual do intervalo fixo é de 1.000 segundos, mas está sujeito a mudanças.

Para mais informações, consulte Mensagens de resposta de dicas.

Exemplos

O exemplo a seguir mostra uma mensagem de solicitação de dica:

Mensagem de solicitação de dica

O exemplo a seguir mostra uma mensagem de solicitação de dicas:

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

O elemento raiz de uma mensagem Query. As mensagens Query são solicitações do Google para atualizações de preços ou metadados. Eles são usados com os modos de envio de preços puxados e alterados.

Mensagens de consulta de preços

As mensagens de consulta de preços especificam as combinações de propriedade e itinerário para as quais você fornece os preços.

Quando o servidor receber uma mensagem de consulta de preços, ele vai responder com uma mensagem <Transaction> que contém as informações de preços solicitadas.

Para mais informações, consulte Visão geral dos preços.

Há três tipos especiais de mensagens Query:

  • Preços em tempo real:o Google responde a uma solicitação específica do usuário, solicitando uma atualização de preço em tempo real. Quando os parceiros recebem uma mensagem Live pricing query, eles precisam responder com uma mensagem <Transaction> que contenha as informações de preço solicitadas nos elementos <Result>.

  • Com preços de contexto:o Google atualiza o cache de preços com base em contextos que são historicamente populares. Quando você receber uma mensagem With context query, responda com uma mensagem <Transaction> que contenha as informações de preços solicitadas nos elementos <Result>.

  • Metadados:o Google solicita atualizações de metadados para os quartos e pacotes de quartos dos hotéis especificados. Quando você receber uma mensagem Metadata Query, responda com uma mensagem <Transaction> que especifique dados sobre os quartos e as categorias de quarto nos elementos <PropertyDataSet>. Para mais informações, consulte Metadados de categorias de quarto.

Sintaxe

O elemento <Query> usa a seguinte sintaxe:

Consulta de preços

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</Query>

Preço em tempo real

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

Com contexto

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

Metadados

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

Atributos

O elemento <Query> pode conter um atributo: latencySensitive.

O atributo latencySensitive é opcional. Quando fornecido e definido como true, indica que a consulta é uma Live Pricing Query. Para que o Google envie consultas com o atributo latencySensitive, entre em contato com seu Gerente técnico de contas (TAM).

Elementos filhos

O elemento <Query> tem os seguintes elementos filhos:

Elemento filho Tipo de consulta Tipo Descrição
<AffectedNights> Pricing integer O número de noites de uma estadia com intervalo. Esse elemento é usado apenas para consultas de preços de estadia com intervalo usadas com preços alterados.
<Checkin> Pricing Date As datas de uma mudança de preço específica.
<Context> Pricing (Live Pricing Queries only) <Context> Para consultas de preços em tempo real, especifica determinados parâmetros em que a consulta é feita. Os elementos filhos incluem:
  • <Occupancy>: o número total de convidados
  • <OccupancyDetails>: o tipo de hóspede, como adultos ou crianças
  • <UserCountry>: o país em que o usuário está localizado
  • <UserDevice>: o tipo de dispositivo que o hóspede usou para pesquisar um hotel, como "mobile, tablet ou desktop.

O elemento <Context> pode ser repetido em uma única solicitação, permitindo consultas para diferentes ocupações. Consulte <Context> para conferir uma lista de elementos filhos, sintaxe e exemplos.
<FirstDate> Pricing Date A data de início de uma série de itinerários a que o preço se aplica. Esse elemento é usado apenas para consultas de preços de período de check-in usadas com preços alterados.
<HotelInfoProperties> Metadata string Uma ou mais propriedades para as quais o Google quer atualizar os metadados do ambiente e do pacote de ambientes em uma mensagem de metadados Query. Esse elemento pode conter um ou mais elementos <Property> que especificam os IDs dos estabelecimentos do hotel.
<LastDate> Pricing Date A data de término de um intervalo de itinerários a que a precificação se aplica. Esse elemento é usado apenas para consultas de preços do período de check-in usadas com pull + dicas.
<Nights> Pricing integer O número de noites de um itinerário específico, até 30.
<PropertyList> Pricing Object

Um ou mais IDs de hotel que precisam de atualizações de preços.

Defina cada hotel em um elemento <Property>. O valor é uma string que corresponde a um ID de hotel na sua lista de hotéis. Por exemplo:

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

Exemplos

Consulta de preços

O exemplo a seguir mostra uma mensagem de consulta de preços que solicita atualizações de preço para um conjunto de hotéis, disponíveis por três noites e a partir de 23 de maio de 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>

Consulta de preços em tempo real

O exemplo a seguir mostra uma consulta de preços em tempo real com um limite de tempo de resposta de 500 milissegundos:

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

Com consulta de contexto

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

Consulta de metadados

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

Para mais exemplos, incluindo consultas de preços de estadia e de data de check-in, confira os exemplos de mensagem Query.

<Context>

O elemento <Context> descreve informações de um Live pricing query, incluindo o número e o tipo de convidados, o país e o dispositivo do usuário.

Várias <Context> nunca serão usadas com diferentes países ou dispositivos de usuários. Quando vários <Context> são usados para consultar várias ocupações, forneça cada preço de ocupação como um pacote de quartos adicional para a propriedade ou o itinerário correspondente. Cada propriedade ou itinerário precisa ter um único bloco <Result> com os preços de várias ocupações.

Para conferir os detalhes da resposta da consulta <Context>, consulte <OccupancyDetails>.

Sintaxe

O elemento <Context> usa a seguinte sintaxe:

Sintaxe

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

Elementos filhos

O elemento <Context> tem os seguintes elementos filhos:

Elemento filho Tipo de consulta Tipo Descrição
<Occupancy> Pricing integer Especifica o número total de convidados.

Embora não seja obrigatório, as consultas com <Occupancy> precisam resultar em uma mensagem de transação com as categorias de quarto adequadas definidas para cada <Occupancy>. No entanto, se as categorias de quarto não estiverem disponíveis, é recomendável especificar o elemento <Occupancy>.

Observação:o <Occupancy> nem sempre aparece em uma consulta. Nesses casos, você precisa retornar os preços de todas as ocupações.
<OccupancyDetails> Pricing Object É precedido por <Occupancy>. Especifica convidados por tipo, incluindo:
  • <NumAdults>: número de convidados adultos
  • <Children> e <Child="age">: especifica quais convidados são crianças (geralmente com idades entre 0 e 17 anos) e, opcionalmente, inclui a idade de cada criança.

Embora não seja obrigatório, as consultas com <OccupancyDetails> devem resultar em uma mensagem de transação com as categorias de quarto adequadas definidas para cada <Occupancy>. No entanto, se as categorias de quarto não estiverem disponíveis, é recomendável especificar o elemento <OccupancyDetails>.

Observação : <OccupancyDetails> nem sempre aparece em uma consulta. Nesses casos, considere que todos os convidados são adultos.
<UserCountry> Pricing string

Filtra as tarifas pelo país em que o usuário está. O valor é um código de país de duas letras, como "US" para os Estados Unidos, ou um código de região, como "EU" para "Europa".

As consultas com <UserCountry> definido precisam resultar em uma mensagem de transação com o bloco <Rates> apropriado definido para o país consultado.
<UserDevice> Pricing string

Filtra as tarifas pelo tipo de dispositivo que o usuário está usando para pesquisar. Valores possíveis:

  • mobile
  • desktop
  • tablet

As consultas com <UserDevice> definido precisam resultar em uma mensagem de transação com o bloco <Rates> apropriado definido para o tipo de dispositivo consultado.

Exemplos

Ocupação

O exemplo a seguir mostra uma consulta de preços em tempo real para <Occupancy> em <Context>. A consulta de preços em tempo real é para três adultos.

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

Detalhes da ocupação

O exemplo a seguir mostra uma consulta de preços em tempo real com <OccupancyDetails> em <Context>. A consulta de preços ao vivo é para quatro hóspedes, sendo que dois deles são crianças, e busca uma tarifa aplicável a uma reserva de hóspedes dos EUA feita em um dispositivo móvel:

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

Vários contextos

O exemplo a seguir mostra o uso de um elemento <Context> adicional em uma consulta de preços ao vivo.

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