Esta página foi traduzida pela API Cloud Translation.

Referência XML de consultas e dicas

Esta seção fornece uma referência para as Mensagens de solicitação de Hint, as Mensagens de Hint Response e as Mensagens de consulta baseadas em XML do Google.

`<Hint>` (mensagem de Hint Response)

O elemento raiz de uma mensagem de Hint Response. As mensagens Hint Response especificam quais combinações de hotel/itinerário devem ser atualizadas. Elas são sua resposta a uma Mensagem de solicitação de dica do Google.

Uma mensagem de Hint Response deve especificar apenas os hotéis com preços que mudaram desde a última vez que o Google recebeu uma Hint Response bem-sucedida de seus servidores.

As mensagens de Hint Response usam um dos seguintes métodos para especificar em quais hotéis e itinerários o Google deve atualizar o preço:

Itinerários exatos: uma combinação da data do check-in e da duração da estadia.
Períodos de check-in: especifica um intervalo de datas de check-in, começando pela data do primeiro e terminando na última.
Estadias predeterminadas (ou itinerários predeterminados)

Cada um desses métodos requer uma sintaxe diferente para a mensagem Hint Response.

Para mais informações, consulte Mensagens de Hint Response.

Sintaxe

O elemento <Hint> usa uma sintaxe diferente, dependendo do tipo de mensagem de Hint Response:

Itinerários exatos

Veja a seguir a sintaxe de itinerários exatos em uma mensagem de Hint Response:

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

Veja a seguir a sintaxe para intervalos de check-in em uma mensagem Hint Response:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "checkin_range" in your
         QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

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

Estadias predeterminadas

Veja a seguir a sintaxe de estadias predeterminadas em uma mensagem de Hint Response:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is "affected_dates" in your
         QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>first_date</FirstDate>

      <!-- Optional -->
      <LastDate>last_date</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

Atributos

O elemento <Hint> contém um atributo opcional: id. Quando fornecido, ele é 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 predeterminados	A primeira data do período de um período de check-in ou de estadia predeterminada de Hint Response. As datas são inclusivas.
<Item>	Required	Object	All	Um contêiner do hotel/itinerário a ser atualizado.
<LastDate>	Required*	Date	Intervalos de check-in e itinerários predeterminados	A última data do período de um período de check-in ou de estadia predeterminada de Hint Response. As datas são inclusivas. * Este elemento é opcional para estadias predeterminadas.
<LengthOfStay>	Required	integer	Itinerários exatos	O número de noites do itinerário expresso como um número inteiro positivo.
<Property>	Required	string	All	O código de um hotel, usando o mesmo código 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 Hint Response: Itinerários exatos: até 100 hotéis. Intervalos de check-in: mais de um se você definir `<MultipleItineraries>` como `"checkin_range"` na mensagem `<QueryControl>`. Permanência limitada: mais de um 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 Hint Response exata do itinerário. Cada `<Item>` pode conter apenas um único `<Stay>`.
<StaysIncludingRange>	Required	Object	Itinerários predeterminados	Um contêiner para os elementos `<FirstDate>` e `<LastDate>` em uma mensagem de Hint Response de estadia predeterminada.

Exemplos

Itinerários exatos

O exemplo a seguir define vários itinerários para uma única propriedade de uma mensagem Hint Response:

<!-- 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 com preços que 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>

Para que uma mensagem de intervalo de check-in possa especificar várias propriedades em uma única <Item>, o valor de <MultipleItineraries> em <QueryControl> precisa ser definido como "checkin_range".

Estadias predeterminadas

O exemplo a seguir mostra dois usos diferentes de estadias predeterminadas, 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 que uma mensagem de estadia predeterminada possa especificar várias propriedades em uma única <Item>, o valor de <MultipleItineraries> em <QueryControl> precisa ser definido como "affected_dates".

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 Hint. O Google envia uma mensagem de solicitação de Hint para seu servidor e espera uma resposta que especifique os hotéis e os itinerários com preços alterados desde a última vez que o Google recebeu uma Hint Response bem-sucedida do seu servidor.

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

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

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 recebeu com êxito uma mensagem de Hint Response para uma mensagem de solicitação de Hint. Se esse horário for anterior à última atualização de preços no servidor, responda com uma mensagem de Hint Response especificando quais hotéis foram alterados. Se não houver uma busca bem-sucedida recente, ela será definida com um valor de intervalo fixo para evitar problemas mais sérios com backlogs grandes. O valor atual do intervalo fixo é de 1.000 segundos, mas está sujeito a alterações. Para mais informações, consulte Mensagens de Hint Response.

Elemento filho

Tipo

Descrição

DateTime

A última vez que o Google recebeu com êxito uma mensagem de Hint Response para uma mensagem de solicitação de Hint.

Se esse horário for anterior à última atualização de preços no servidor, responda com uma mensagem de Hint Response especificando quais hotéis foram alterados.

Se não houver uma busca bem-sucedida recente, ela será definida com um valor de intervalo fixo para evitar problemas mais sérios com backlogs grandes. O valor atual do intervalo fixo é de 1.000 segundos, mas está sujeito a alterações.

Para mais informações, consulte Mensagens de Hint Response.

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 Hint Request:

<?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. Mensagens Query são solicitações do Google para atualizações de preços ou metadados. Eles são usados com os modos de transferência de preços pull e alterados.

Há três tipos de mensagens Query:

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

Importante :devido à nova experiência de pesquisa, a Consulta em tempo real não está mais disponível para usuários do EEE.
Com preços contextuais:o Google atualiza o cache de preços com base em contextos historicamente famosos. Ao receber uma mensagem With context query, responda com uma mensagem <Transaction> que contém as informações de preço solicitadas nos elementos <Result>.
Metadados:o Google solicita atualizações de metadados dos quartos e das Categorias de quarto para os hotéis especificados. Ao receber uma mensagem Metadata Query, você precisa responder com uma mensagem <Transaction> que especifique dados sobre os quartos e Categorias de quarto nos elementos <PropertyDataSet>.

Para mais informações, consulte Visão geral de preços para consultas de preços e Metadados de Pacote de quarto para consultas de metadados.

A sintaxe dos três tipos diferentes está descrita abaixo.

Sintaxe

O elemento <Query> usa a seguinte sintaxe:

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 fornecida e definida como true, ela indica que a consulta é um Live Pricing Query. Para que o Google envie consultas com o atributo latencySensitive, pergunte ao seu Gerente técnico de contas (TAM, na sigla em inglês).

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 predeterminada. Esse elemento é usado apenas para consultas de preço de estadia predeterminada 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 convidado, como adultos ou crianças `<UserCountry>`: o país em que o usuário está localizado. `<UserDevice>`: o tipo de dispositivo que o convidado 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 ver uma lista de elementos filhos, sintaxe e exemplos.
<FirstDate>	Pricing	Date	A data de início de vários itinerários aos quais os preços se aplicam. Esse elemento é usado apenas para consultas de preços do período de check-in usadas com preços alterados.
<HotelInfoProperties>	Metadata	string	Uma ou mais propriedades para as quais o Google quer metadados atualizados de quarto e Categoria de quarto em uma mensagem de metadados `Query`. Esse elemento pode conter um ou mais elementos `<Property>` que especificam IDs de propriedade do hotel.
<LastDate>	Pricing	Date	A data de término de vários itinerários aos quais os preços se aplicam. Esse elemento é usado apenas para consultas de preços do período de check-in usadas com Pull + Hints.
<Nights>	Pricing	integer	O número de noites de um itinerário específico, até 30.
<PropertyList>	Pricing	Object	Um ou mais IDs de hotéis que exigem atualizações de preços. Defina cada hotel em um elemento `<Property>`. O valor é uma string que corresponde ao código de um 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ço que solicita atualizações de preço para um conjunto de hotéis, disponível para três noites a partir de 10 de junho de 2018:

<?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ç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">
  <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, 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>

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ço de estadia predeterminada e check-in, confira os exemplos de mensagens Query.

`<Context>`

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

Vários <Context> nunca serão usados com diferentes países ou dispositivos de usuários. Quando vários <Context> são usados na consulta de várias ocupações, forneça o preço de cada uma delas como uma Categoria de quarto adicional para a propriedade/itinerário correspondente. Cada propriedade/itinerário precisa ter um único bloco <Result> com os preços para várias ocupações incluídas.

Para 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 sejam obrigatórias, as consultas com `<Occupancy>` precisam resultar em uma mensagem de transação com as Categorias de quarto apropriadas definidas para cada `<Occupancy>` consultado. Observação:`<Occupancy>` nem sempre aparece em uma consulta. Nesses casos, é preciso retornar os preços de todas as ocupações.
<OccupancyDetails>	Pricing	Object	É precedido por `<Occupancy>`. Especifica os convidados por tipo, incluindo: `<NumAdults>`: número de hóspedes adultos `<Children>` e `<Child="age">`: especificam quais convidados são crianças (normalmente de 0 a 17 anos) e, opcionalmente, incluem a idade de cada criança. Embora não sejam obrigatórias, as consultas com `<OccupancyDetails>` precisam resultar em uma mensagem de transação com as Categorias de quarto apropriadas definidas para cada `<Occupancy>` consultado. Observação : nem sempre `<OccupancyDetails>` aparece em uma consulta. Nesses casos, considere que todos os convidados são adultos.
<UserCountry>	Pricing	string	Filtra as taxas pelo país em que o usuário está localizado. O valor é um código do país de duas letras, como `“US”` para Estados Unidos, ou um código regional, como `"EU"` para "Europa". As consultas com `<UserCountry>` definido precisam resultar em uma mensagem de transação com o bloco `<Rates>` apropriado para o país consultado.
<UserDevice>	Pricing	string	Filtra as taxas pelo tipo de dispositivo em que o usuário está pesquisando. 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ço em tempo real para <Occupancy> em <Context>. A consulta de preço 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ço em tempo real com <OccupancyDetails> em <Context>. A consulta de preço em tempo real é para quatro hóspedes, sendo que dois deles são crianças, e procura uma tarifa aplicável para uma reserva de hóspedes dos EUA usando 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> extra em uma consulta de preço em tempo real.

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

Referência XML de consultas e dicas

<Hint> (mensagem de Hint Response)

Sintaxe

Itinerários exatos

Intervalos de check-in

Estadias predeterminadas

Atributos

Elementos filhos

Exemplos

Itinerários exatos

Intervalos de check-in

Estadias predeterminadas

<HintRequest>

Sintaxe

Sintaxe

Atributos

Elementos filhos

Exemplos

Mensagem de solicitação de dica

<Query>

Sintaxe

Preço em tempo real

Com contexto

Metadados

Atributos

Elementos filhos

Exemplos

Consulta de preços

Consulta de preço em tempo real

Com consulta de contexto

Consulta de metadados

<Context>

Sintaxe

Sintaxe

Elementos filhos

Exemplos

Ocupação

Detalhes da ocupação

Vários contextos

`<Hint>` (mensagem de Hint Response)

`<HintRequest>`

`<Query>`

`<Context>`