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 Hint Request, mensagens Hint Response e de consulta baseadas em XML do Google.

`<Hint>` (mensagem de dica de resposta)

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

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

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

Itinerários exatos: uma combinação de data do check-in e duração da estadia.
Períodos de check-in: especifica um período de datas de check-in, começando pela primeira data 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 Hint Response.

Sintaxe

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

Itinerários exatos

Veja a seguir a sintaxe de itinerários exatos em uma mensagem 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 de 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 para estadias predeterminadas em uma mensagem 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 em 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 Hint	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 mensagem de Hint Response de estadia predeterminada. As datas são inclusivas.
<Item>	Required	Object	All	Um contêiner para o 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 uma mensagem de Hint Response de estadia predeterminada. 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 você pode especificar em um único bloco `<Item>` é determinado pelo tipo de mensagem Hint Response: Itinerários exatos: até 100 hotéis. Intervalos de check-in: mais de um se você definir `<MultipleItineraries>` como `"checkin_range"` na sua mensagem `<QueryControl>`. Estadia predeterminada: mais de um se você definir `<MultipleItineraries>` como `"affected_dates"` na sua mensagem `<QueryControl>`.
<Stay>	Required	Object	Itinerários exatos	Um contêiner para os elementos `<CheckinDate>` e `<LengthOfStay>` em uma mensagem de Hint de itinerário exato. 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: 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 alterados e que precisam ser buscados novamente. O Google coleta 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 um único <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 um único <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 inclui atualizações de preços para os hotéis/itinerários especificados.

`<HintRequest>`

O elemento raiz de uma mensagem de solicitação Hint. O Google envia uma mensagem de Hint Request para seu servidor e espera uma resposta que especifique os hotéis e itinerários cujos preços foram alterados desde a última vez em que o Google recebeu uma Hint Response de seu servidor.

Se houver alguma mudança de preço, o Google enviará um <Query> que busca os dados de preços atualizados dos 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 conseguiu receber uma mensagem de Hint Response para uma mensagem de solicitação Hint. Se esse período for anterior à última vez em que você atualizou preços no servidor, responda com uma mensagem Hint Response especificando quais hotéis foram alterados. Se não houver uma busca bem-sucedida recente, o valor será definido como um valor de intervalo fixo (para evitar problemas mais graves com grandes backlogs). O valor de intervalo fixo atual é de 1.000 segundos, mas está sujeito a mudanças. Para mais informações, consulte Mensagens Hint Response.

Elemento filho

Tipo

Descrição

DateTime

A última vez que o Google conseguiu receber uma mensagem de Hint Response para uma mensagem de solicitação Hint.

Se esse período for anterior à última vez em que você atualizou preços no servidor, responda com uma mensagem Hint Response especificando quais hotéis foram alterados.

Se não houver uma busca bem-sucedida recente, o valor será definido como um valor de intervalo fixo (para evitar problemas mais graves com grandes backlogs). O valor de intervalo fixo atual é de 1.000 segundos, mas está sujeito a mudanças.

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

Exemplos

O exemplo a seguir mostra uma mensagem de Hint Request:

Mensagem de solicitação Hint

O exemplo a seguir mostra uma mensagem de solicitação Hint:

<?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. Elas são usadas com os modos de entrega de preços alterados e pull.

Há três tipos de mensagens Query:

Preço 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, eles precisam responder com uma mensagem <Transaction> que contenha as informações de preços solicitadas em elementos <Result>.

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

Para mais informações, acesse a 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 é 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 fornecido e definido como true, ele indica que a consulta é uma Live Pricing Query. Para que o Google envie consultas com o atributo latencySensitive, fale com seu Gerente técnico de contas (TAM).

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 para uma estadia predeterminada. Esse elemento é usado apenas para consultas de preço de estadia predeterminada usadas com os 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 sob os quais a consulta é feita. Os elementos filhos incluem: `<Occupancy>`: o número total de convidados `<OccupancyDetails>`: o tipo de convidados, como adultos ou crianças `<UserCountry>`: o país onde o usuário está localizado. `<UserDevice>`: o tipo de dispositivo que o hóspede 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 um intervalo de itinerários a que o preço se aplica. Este elemento é usado apenas para consultas de preço do Intervalo de datas de check-in usadas com o Preço alterado.
<HotelInfoProperties>	Metadata	string	Uma ou mais propriedades em que o Google quer metadados atualizados de quartos e Categoria de quarto em uma mensagem `Query` de metadados. Esse elemento pode conter um ou mais elementos `<Property>` que especificam os IDs de propriedade do hotel.
<LastDate>	Pricing	Date	A data de término de um intervalo de itinerários a que o preço se aplica. Este elemento é usado apenas para consultas de preço 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ço. Defina cada hotel em um elemento `<Property>`. O valor é uma string que corresponde a um código de 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 dos preços de um conjunto de hotéis, disponível por 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 um 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ços de estadias premiadas e períodos de check-in, confira os exemplos de mensagens do Query.

`<Context>`

O elemento <Context> descreve informações de um 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árias <Context> forem usadas para consultar várias ocupações, forneça cada preço de ocupação 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 obter os detalhes da resposta para a 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 adequadas definidas para cada `<Occupancy>` consultado. Observação:`<Occupancy>` nem sempre aparece em uma consulta. Nesses casos, você precisa retornar os preços de todas as ocupações.
<OccupancyDetails>	Pricing	Object	É precedido por `<Occupancy>`. Especifica convidados por tipo, incluindo: `<NumAdults>`: número de hóspedes adultos `<Children>` e `<Child="age">`: especificam quais convidados são crianças (geralmente de 0 a 17 anos) e, opcionalmente, inclui a idade de cada uma. Embora não sejam obrigatórias, as consultas com `<OccupancyDetails>` precisam resultar em uma mensagem de transação com as Categorias de quarto adequadas definidas para cada `<Occupancy>` consultado. Observação : nem sempre `<OccupancyDetails>` aparece em uma consulta. Nesses casos, considere que todos os hóspedes são adultos.
<UserCountry>	Pricing	string	Filtra as taxas pelo país em que o usuário está localizado. O valor é um código de país de duas letras, como `“US”` para os Estados Unidos, ou um código de região, como `"EU"` para "Europa". Consultas com `<UserCountry>` definido devem resultar em uma mensagem de transação com o bloco `<Rates>` apropriado definido 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` 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 de 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, dois deles crianças, e busca uma tarifa aplicável a uma reserva de hóspedes nos EUA em 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 dica de resposta)

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 Hint

<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 de ocupação

Vários contextos

`<Hint>` (mensagem de dica de resposta)

`<HintRequest>`

`<Query>`

`<Context>`