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ço:o Google envia uma Mensagem de consulta que solicita atualizações de preços dos hotéis especificados.
Metadados: o Google envia uma Mensagem de consulta que solicita dados sobre 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ço 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 usando Google-TravelAds-Live. Essas consultas de amostra podem ou não conter o cabeçalho User-Agent.
A formatação detalhada para Mensagens de consulta pode ser encontrada na Referência XML de consulta.
Mensagens de consulta de preço
As Mensagens de consulta de preço especificam as combinações de propriedade ou itinerário para as quais você fornece os preços.
Quando o servidor recebe uma Mensagem de consulta de pricing, ele deve responder com uma mensagem <Transaction> que contém 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ços em tempo real:se ativada, as consultas são enviadas quando um usuário está pesquisando ativamente os preços da combinação especificada de propriedade ou itinerário, e você tem um período específico para responder.
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 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ços em tempo real
As consultas de preço em tempo real são solicitações do Google por atualizações de preço em tempo real 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 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 mostrá-lo nos resultados no momento da pesquisa.
Todas as solicitações de consulta de preço em tempo real têm um limite de tempo de resposta 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á na perda da participação na oportunidade específica. No entanto, recomendamos fornecer um preço de qualquer maneira 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ço 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ço em tempo real, é possível mostrar preços mais atualizados que correspondam ao que o cliente pesquisou.
As consultas de preço em tempo real devem ser um mecanismo secundário para atualizações de preços. O principal mecanismo para mudanças de preço ainda é o preço pull ou alterado. 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 o itinerário solicitado é atípico, por exemplo, as datas estão muito distantes no futuro ou o hotel é pesquisado com pouca frequência.
A data solicitada não é padrão.
Observação: as datas padrão não são qualificadas para consultas de preço em tempo real. As consultas de preço 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, além de 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
de preços em tempo real específicas com base no tipo de dispositivo do usuário, no país de
pesquisa e no número de ocupantes, incluindo crianças. Tanto a Mensagem de consulta quanto 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 Categoria de quarto
se for 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
Elas são solicitações regulares para atualizar nosso banco de dados com base nas combinações especificadas de propriedade ou itinerário. Eles contêm uma lista de contextos do usuário mais usados para essas combinações. Se as Tarifas condicionais forem usadas, o envio de tarifas para todos os contextos de usuário possíveis poderá ser caro. Portanto, você pode usar essa lista de contextos do 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.
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.
Ao receber uma Mensagem de consulta de metadados, responda com uma mensagem <Transaction> que especifique o preço das propriedades solicitadas nos elementos <Result>.
Para mais informações, consulte Definir metadados de quartos e pacotes.
Controlar consultas
Esta seção descreve 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ço 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. Também é possível definir essas configurações para grupos de hotéis.
Exemplos de mensagens de consulta
Nesta seção, você verá vários exemplos de Mensagens de consulta de preços e uma Mensagem de consulta de metadados. Outros exemplos são encontrados na Referência de XML de consulta.
Roteiro de exemplo
O exemplo a seguir mostra um preço <Query> que solicita atualizações de preço
para quatro hotéis, disponíveis para 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 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 o preço de um único hotel:
6/23/23 - 6/25/23
Um exemplo de resposta de mensagem de transação para essa consulta pode ser encontrado na Referência XML de preços e inventário de quartos (transações).
Com exemplo de consulta de contexto
Confira a seguir um exemplo 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, 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 podem especificar o dispositivo e a ocupação do usuário.
Períodos de check-in
Se você usar "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 de Hint Response.
O exemplo a seguir mostra uma mensagem de preço <Query> 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 de preço <Query> 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 incluindo) 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.