Esta página foi traduzida pela API Cloud Translation.

Mensagens de consulta

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

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 solicitando 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 seu 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 pelo 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:

Preços em tempo real:se ativado, as consultas são enviadas quando um usuário está navegando ativamente pelos preços da propriedade ou combinação de itinerários especificada, e você tem um período determinado para responder.
Com contexto:se ativadas, as recomendações de contexto do usuário são incluídas em cada consulta que o Google envia a você, 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.
Metadados: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. Como os dados de preços não estão disponíveis ou não estão atualizados, o Google pede uma atualização de preço no momento da pesquisa. Com a consulta de preços em tempo real, o Google tenta conseguir um preço e mostrá-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 geralmente é 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, a participação na oportunidade específica será perdida. No entanto, recomendamos informar um preço para que ele possa ser armazenado em cache e usado em 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 correspondem 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 principal mecanismo para redefinição de preços ainda é o Pull ou Changed pricing. 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. Por exemplo, as datas estão muito distantes 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.

Normalmente, o Google 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 um único hotel ou itinerário, bem como combinações de vários hotéis ou um único itinerário.

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 de onde ele está pesquisando e no número de ocupantes, incluindo crianças. As mensagens de consulta e de transação são expandidas para incluir o elemento <Context>, 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 quarto, 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.

Com consultas contextuais

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

Se você tiver interesse em receber consultas com contexto, entre em contato com seu gerente técnico de contas (TAM). Eles podem confirmar que 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 para você.

Mensagens de consulta de metadados

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

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

Para mais informações, consulte Como definir metadados de sala e pacote.

Consultas de controle

Esta seção descreve como controlar quais propriedades e itinerários podem ser o assunto das mensagens de consulta do Google.

Limites do itinerário

Você determina os limites possíveis das consultas de preços usando <ItineraryCapabilities>. Você define regras que determinam o intervalo de datas e as durações máximas de estadia aceitas.

É possível definir valores padrão para <MaxAdvancePurchase> e <MaxLengthOfStay> que se aplicam a todas as combinações de hotel ou itinerário. Também é possível definir essas configurações para grupos de hotéis.

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

Uma resposta de mensagem de transação de exemplo para essa consulta pode ser encontrada na Referência XML de preços e inventário de quartos (transações).

Com exemplos de consultas contextuais

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>

Com consultas de contexto, especifica 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 check-in

Se você usa o recurso "Preços alterados", a estrutura da mensagem de consulta depende do tipo de dica usado para períodos de datas de check-in, itinerários exatos ou itinerários com intervalos. Para mais informações sobre cada um desses tipos de dicas, consulte Mensagens de resposta de dica.

O exemplo a seguir mostra uma mensagem de preços <Query> para intervalos de datas de 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 em um intervalo

O exemplo a seguir mostra uma mensagem de <Query> de preços para estadias de período determinado:

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