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 que solicita atualizações de preço dos hotéis especificados.
Metadados:o Google envia uma Mensagem de consulta que solicita dados sobre as informações de quartos e pacotes 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).
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 consultas.
Mensagens de consulta de preços
As Mensagens de consulta de preços especificam as combinações de propriedade ou itinerário para que você fornece os preços.
Quando o servidor recebe uma Mensagem de consulta de pricing, ele precisa responder com uma mensagem
<Transaction> contendo as informações de preço solicitadas.
Para mais informações, consulte Visão geral de preços.
Há três tipos especiais de Mensagens de consulta:
Preço em tempo real:se ativado, as consultas serão enviadas quando um usuário estiver procurando ativamente os preços da propriedade ou combinação de itinerário especificada e você tiver um prazo definido para responder.
Com contexto:se ativada, as recomendações de contexto do usuário são incluídas em cada consulta que o Google envia e refletem os tipos mais comuns de usuários que pesquisam determinadas combinações de propriedade ou itinerário. Seguir essas recomendações pode aumentar a eficiência das suas respostas.
Metadados:é uma solicitação de detalhes sobre quartos e pacotes das propriedades especificadas.
Consultas de preço em tempo real
As consultas de preços em tempo real são solicitações do Google de 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 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 normalmente é de até 4.000 milissegundos. Esse limite é especificado na solicitação de consulta de preço em tempo real. Se uma resposta não puder ser fornecida dentro do limite de tempo, isso resultará em uma participação perdida na 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 da 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 extrair 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, é possível mostrar preços mais atualizados que correspondem ao que o cliente pesquisou.
As consultas de preços em tempo real devem ser um mecanismo secundário para atualizações de preços. O principal mecanismo para mudanças no preço continua sendo os preços "Pull" ou "Alterados". As consultas de preços em tempo real ajudam a preencher as lacunas quando 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 em cache para o itinerário solicitado 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 é padrão.
: Observação: as datas padrão não estão qualificadas para consultas de preço em tempo real. As consultas de preços em tempo real são solicitadas apenas para datas fora do padrão.
Normalmente, o Google armazena em cache os resultados de uma página de preços em tempo real para que o mesmo hotel ou itinerário não seja consultado novamente. É possível solicitar combinações de hotel ou itinerário, além de combinações de itinerário único ou de vários hotéis.
O recurso Preços em tempo real com contexto permite que o Google envie solicitações
de preços em tempo real específicas 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. A Mensagem de consulta e a Mensagem de transação são expandidas para incluir o elemento <Context> que define os parâmetros de consulta. Os preços recebidos das
consultas de preços em tempo real com contexto podem ser armazenados em cache como uma Categoria 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 de contexto
Com as consultas de contexto, são solicitações regulares para atualizar o banco de dados para as combinações de propriedade ou itinerário especificadas. Eles contêm uma lista de contextos de usuário que são populares para essas combinações. Se as tarifas condicionais forem usadas, as taxas de envio para todos os contextos de usuário possíveis poderão ser caras. Portanto, use essa lista de contextos de usuário para limitar sua resposta. O retorno de preços apenas para os contextos de usuário especificados abrange a grande maioria das consultas relevantes do usuário.
Mensagens de consulta de metadados
As mensagens de consulta de metadados contêm detalhes sobre informações de quartos e pacotes das propriedades especificadas.
Quando você receber uma Mensagem de consulta de metadados, responda com
uma mensagem <Transaction> que especifique o preço das propriedades solicitadas
em elementos <Result>.
Para mais informações, consulte Como definir metadados de quartos e pacotes.
Consultas de controle
Nesta seção, descrevemos como você controla quais propriedades e itinerários podem ser o assunto das Mensagens de consulta do Google.
Limites de itinerário
Determine os possíveis limites das consultas de preços usando
<ItineraryCapabilities>. Você define regras que determinam o intervalo de datas e a duração máxima da estadia aceita.
É possível definir valores padrão para <MaxAdvancePurchase> e <MaxLengthOfStay> que se aplicam a todas as combinações de hotel ou itinerário. Você também pode definir essas configurações para grupos de hotéis.
Exemplos de mensagens de consulta
Nesta seção, mostramos vários exemplos de Mensagens de consulta de preços e de metadados. Outros exemplos estão disponíveis na Referência XML de consulta.
Roteiro de exemplo
O exemplo a seguir mostra um <Query> de preços que solicita atualizações de preços
para quatro hotéis, disponíveis por três noites, 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>
Este exemplo solicita atualizações de preços para cada hotel:
5/23/18 - 6/26/18
Exemplo de consulta de preço em tempo real
O exemplo a seguir mostra uma consulta de preço 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
Veja um exemplo de resposta da mensagem de transação a essa consulta na Referência XML de preços e inventário de quartos (transações).
Com exemplo de consulta de contexto
O exemplo a seguir mostra um exemplo de consulta 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, 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>
Com as consultas de contexto, apenas o contexto do país do usuário é especificado. No futuro, essas consultas também poderão especificar o dispositivo e a ocupação do usuário.
Períodos do check-in
Se você usar os preços alterados, a estrutura da Mensagem de consulta dependerá do tipo de dica usado para períodos de check-in, itinerários exatos ou itinerários predeterminados. Para mais informações sobre cada um desses tipos de dica, consulte Mensagens Hint Response.
O exemplo a seguir mostra uma mensagem <Query> de preço para períodos 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 (de 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 predeterminadas
O exemplo a seguir mostra uma mensagem <Query> de preço para estadias
prolongadas:
<?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 iniciadas antes (mas que incluem) a noite em questão:
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 das 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 os metadados de quartos e pacotes. Para mais informações, consulte Como definir metadados de quartos e pacotes.