Mensagens de consulta

As mensagens de consulta são solicitações do Google para atualizações de preços ou metadados. Elas são usadas com os modos de transferência de preços por pull e alterados de entrega.

O elemento raiz das mensagens de consulta é <Query>.

A estrutura da mensagem de consulta depende do tipo de mensagem:

  • Preços:o Google envia uma mensagem de consulta que solicita atualizações de preços para os hotéis especificados.

  • Metadados:o Google envia uma mensagem de consulta que solicita dados sobre o quarto e informações do pacote nos hotéis especificados.

Você define o endpoint que o Google usa para mensagens de consulta e consultas de preços em tempo real durante a configuração inicial. Para mais informações, entre em contato com o gerente técnico de contas (TAM, na sigla em inglês).

O Google envia uma mensagem de consulta como uma solicitação HTTP POST com o cabeçalho Content-Type definido como "application/xml" e o cabeçalho User-Agent definido como Google-HotelAdsPrices. A exceção a essa regra ocorre durante o teste manual da integração do endpoint de preço usando Google-TravelAds-Live. Essas consultas de exemplo podem ou não conter o cabeçalho User-Agent.

A formatação detalhada das mensagens de consulta pode ser encontrada na referência XML de consulta.

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 recebe uma mensagem de consulta de preços, ele precisa responder com uma mensagem <Transaction> que contenha as informações de preços solicitadas.

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

Há três tipos especiais de mensagens de consulta:

  1. Preços em tempo real:se ativadas, as consultas são enviadas quando um usuário está navegando ativamente pelos preços da propriedade ou combinação de itinerário especificada, e você tem um período especificado para responder.

  2. Com contexto:se ativadas, as recomendações de contexto do usuário são incluídas em cada consulta enviada pelo Google, e as recomendações refletem os tipos mais comuns de usuários que pesquisam as combinações de propriedade ou itinerário. Seguir essas recomendações pode aumentar a eficiência das suas respostas.

  3. Metadados:é uma solicitação de detalhes sobre quartos e pacotes para as propriedades especificadas.

Consultas de preços em tempo real

As consultas de preços em tempo real são solicitações do Google para atualizações de preços em tempo real em resposta às pesquisas dos usuários. O Google recebe uma solicitação de pesquisa de um usuário para uma combinação de hotel ou itinerário e, como os dados de preços não estão disponíveis ou não são atuais, o Google solicita uma atualização de preço no momento da pesquisa. Com a consulta de preços em tempo real, o Google tenta receber um preço e exibi-lo nos resultados no momento da pesquisa.

Todas as solicitações de consulta de preços em tempo real têm um limite de tempo de resposta, que normalmente é de até 4.000 milissegundos. Esse limite é especificado na solicitação de consulta de preços em tempo real. Se uma resposta não puder ser fornecida dentro do limite de tempo, isso resultará em uma participação perdida para a oportunidade específica. No entanto, recomendamos fornecer um preço de qualquer maneira para que ele possa ser armazenado em cache e usado para oportunidades futuras. A conexão para a resposta permanece aberta por dez minutos ou conforme especificado na configuração do parceiro.

As consultas de preços em tempo real também são contextuais e podem recuperar preços para os seguintes parâmetros: país do usuário, tipo de dispositivo, ocupação (número de hóspedes) e se esses hóspedes são adultos ou crianças. Com as consultas de preços em tempo real, você pode mostrar preços mais atualizados que correspondam ao que o cliente pesquisou.

As consultas de preços em tempo real são um mecanismo secundário para atualizações de preços. O mecanismo principal para a mudança de preços ainda é por pull ou preços alterados. As consultas de preços em tempo real ajudam a preencher as lacunas em que o Google não tem preços para combinações de hotel ou itinerário.

Regras para usar consultas de preços em tempo real

  • Não há dados armazenados em cache para o itinerário especificado porque ele é atípico, como as datas estão muito distantes no futuro ou o hotel é pesquisado com pouca frequência.

  • A data solicitada não é a padrão.

: Observação: as datas padrão não são qualificadas para consultas de preços em tempo real. As consultas de preços em tempo real são solicitadas apenas para datas não padrão.

O Google normalmente armazena em cache os resultados de um preço em tempo real para que o mesmo hotel ou itinerário não seja consultado novamente. Ele pode solicitar combinações de hotel ou itinerário único, bem como combinações de vários hotéis ou itinerário único.

O recurso Preços em tempo real com contexto permite que o Google envie solicitações específicas de preços em tempo real com base no tipo de dispositivo do usuário, no país em que ele está pesquisando e no número de ocupantes, incluindo crianças. As mensagens de consulta e as mensagens de transação são expandidas para incluir o <Context> elemento que define os parâmetros de consulta. Os preços recebidos de consultas de preços em tempo real com contexto podem ser armazenados em cache como um pacote de quartos, se for um preço para uma ocupação específica, e como uma tarifa condicional, se for para um país ou dispositivo do usuário.

Consultas com contexto

As consultas com contexto são solicitações normais para atualizar nosso banco de dados para a propriedade ou combinações de itinerário especificadas. Elas contêm uma lista de contextos de usuário que são populares para essas combinações. Se as tarifas condicionais forem usadas, então o envio de tarifas para todos os contextos de usuário possíveis poderá ser caro. Portanto, você pode usar essa lista de contextos de usuário para limitar sua resposta. Retornar preços apenas para os contextos de usuário especificados abrange a grande maioria das consultas de usuários relevantes.

Se você tiver interesse em receber consultas com contexto, entre em contato com o gerente técnico de contas (TAM, na sigla em inglês). Ele pode confirmar se você está pronto para receber essas mensagens e fazer um ajuste de configuração para começar a enviar contextos de usuário em consultas.

Mensagens de consulta de metadados

As mensagens de consulta de metadados contêm detalhes sobre informações de quartos e pacotes para as propriedades especificadas.

Quando você recebe uma mensagem de consulta metadados, precisa responder com uma mensagem <Transaction> que especifica os preços das propriedades solicitadas nos elementos <Result>.

Para mais informações, consulte Como definir metadados de quartos e pacotes.

Exemplos de mensagens de consulta

Esta seção mostra vários exemplos de mensagens de consulta de preços e uma mensagem de consulta de metadados. Outros exemplos podem ser encontrados na referência XML de consulta.

Roteiro de exemplo

O exemplo a seguir mostra uma <Query> de preços que solicita atualizações de preços para quatro hotéis, disponíveis por três noites, e com início em 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>

Este exemplo solicita atualizações de preços para cada hotel:

5/23/18 - 6/26/18

Exemplo de 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">
<!-- 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>

Este exemplo solicita um preço para um único hotel:

6/23/23 - 6/25/23

Um exemplo de resposta de mensagem de transação a essa consulta pode ser encontrado na referência XML de preços e inventário de quartos (transações).

Exemplos de consultas com contexto

Confira a seguir exemplos de consultas com contexto:

Consulta básica com 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 com contexto, incluindo ocupação

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

As consultas com contexto especificam apenas o contexto do país do usuário. No futuro, essas consultas também poderão especificar o dispositivo do usuário.

Períodos de data do check-in

Se você usar Preços Alterados, a estrutura da mensagem de consulta vai depender do tipo de dica usado para períodos de datas de check-in, itinerários exatos ou itinerários variados. Para mais informações sobre cada um desses tipos de dicas, consulte Mensagens de resposta de dicas.

O exemplo a seguir mostra uma mensagem <Query> de preços para períodos de data do 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>

Este exemplo solicita atualizações de preços para as seguintes estadias (para cada 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

Estadias variadas

O exemplo a seguir mostra uma mensagem <Query> de preços para estadias variadas:

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

Este exemplo solicita atualizações de preços para cada 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

Além de estadias que começaram antes (mas incluem) a noite especificada:

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

Mensagem de consulta de metadados

O exemplo a seguir mostra uma mensagem <Query> que solicita atualizações de metadados para as informações de quartos e pacotes de várias propriedades:

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

Você responde a esse tipo de mensagem de consulta com uma mensagem de transação que define metadados de quartos e pacotes. Para mais informações, consulte Como definir metadados de quartos e pacotes.