Запрос & Справочник по XML-подсказкам

В этом разделе приведены ссылки на сообщения запроса подсказки на основе XML Google, сообщения ответа на подсказку и сообщения запроса .

<Hint> (Ответное сообщение с подсказкой)

Корневой элемент сообщения Hint Response. В ответных сообщениях с подсказками указывается, какие комбинации отелей или маршрутов должны быть переоценены. Это ваш ответ на сообщение с запросом подсказки от Google.

В сообщении Hint Response должны быть указаны только те отели, цены которых изменились с тех пор, как Google в последний раз получал успешный Hint Response от ваших серверов.

В ответных сообщениях с подсказками используется один из следующих методов, чтобы указать, какие отели и маршруты Google должен переоценить:

  • Точные маршруты : сочетание даты заезда и продолжительности пребывания.

  • Диапазоны дат регистрации : указывает диапазон дат регистрации, начиная с первой даты регистрации и заканчивая датой последней регистрации.

  • Раннее пребывание (или дальние маршруты )

Каждый из этих методов требует разного синтаксиса для сообщения ответа на подсказку.

Для получения дополнительной информации обратитесь к сообщениям Hint Response .

Синтаксис

Элемент <Hint> использует другой синтаксис, в зависимости от типа сообщения-подсказки-ответа:

Точные маршруты

Ниже показан синтаксис точных маршрутов в ответном сообщении с подсказкой: 

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

Диапазоны регистрации

Ниже показан синтаксис диапазонов регистрации в ответном сообщении с подсказкой: 

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

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

Дальнее пребывание

Ниже показан синтаксис для диапазонного пребывания в сообщении ответа на подсказку: 

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

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

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

Атрибуты

Элемент <Hint> содержит необязательный атрибут: id . Если он предоставлен, он включается как hintId в сообщения <Query> , отправляемые на основе этого <Hint> .

Дочерние элементы

Элемент <Hint> имеет следующие дочерние элементы:

Дочерний элемент Необходимый? Тип Тип ответа на подсказку Описание
<CheckInDate> Required Date Точные маршруты Дата заезда по маршруту.
<FirstDate> Required Date Диапазоны регистрации и диапазоны маршрутов Первая дата диапазона дат для диапазона регистрации или интервала пребывания. Подсказка и ответное сообщение. Даты указаны включительно.
<Item> Required Object Все Контейнер для отеля/маршрута, который необходимо обновить.
<LastDate> Required* Date Диапазоны регистрации и диапазоны маршрутов

Последняя дата диапазона дат для диапазона регистрации или интервала пребывания. Подсказка. Ответное сообщение. Даты указаны включительно.

* Этот элемент является необязательным для дальнего пребывания.

<LengthOfStay> Required integer Точные маршруты Количество ночей по маршруту, выраженное как целое положительное число.
<Property> Required string Все

Идентификатор отеля, использующий тот же идентификатор, что и в списке отелей . Количество элементов <Property> , которые вы можете указать в одном блоке <Item> , определяется типом сообщения Hint Response:

  • Точные маршруты: До 100 отелей.
  • Диапазоны регистрации: более одного, если вы установили для <MultipleItineraries> значение "checkin_range" в сообщении <QueryControl> .
  • Диапазон пребывания: более одного, если в сообщении <QueryControl> для параметра <MultipleItineraries> установлено значение "affected_dates" .
<Stay> Required Object Точные маршруты Контейнер для элементов <CheckinDate> и <LengthOfStay> в сообщении с подсказкой и ответом на точный маршрут. Каждый <Item> может содержать только один <Stay> .
<StaysIncludingRange> Required Object Дальние маршруты Контейнер для элементов <FirstDate> и <LastDate> в ответном сообщении с подсказкой о пребывании в диапазоне.

Примеры

Точные маршруты

В следующем примере определяется несколько маршрутов для одного свойства и сообщение ответа на подсказку: 

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

Диапазоны регистрации

В следующем примере указаны два отеля, цены которых изменились и их необходимо получить снова. Google получает все маршруты с 3 по 6 июля для объектов 12345 и 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>

Дальнее пребывание

В следующем примере показаны два различных варианта использования интервального пребывания: один для диапазона ночей, а другой для одной ночи:

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

На каждый из этих примеров Google отвечает <Query> , а вам следует затем ответить <Transaction> , который включает обновления цен для указанных отелей/маршрутов.

<HintRequest>

Корневой элемент сообщения запроса подсказки. Google отправляет сообщение с запросом подсказки на ваш сервер и ожидает ответа, в котором будут указаны отели и маршруты, цены на которые изменились с тех пор, как Google в последний раз получал успешный ответ с подсказкой от вашего сервера.

Если есть какие-либо изменения цен, Google отправляет <Query> , который получает обновленные данные о ценах для указанных отелей и маршрутов.

Для получения дополнительной информации обратитесь к Сообщениям с запросами на подсказки .

Синтаксис

Элемент <HintRequest> использует следующий синтаксис:

Синтаксис 

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

Атрибуты

Элемент <HintRequest> не имеет атрибутов.

Дочерние элементы

Элемент <HintRequest> имеет следующие дочерние элементы:

Дочерний элемент Тип Описание
<LastFetchTime> DateTime В последний раз Google удалось получить сообщение ответа на подсказку на сообщение с запросом подсказки.

Если это время старше, чем время последнего обновления цен на вашем сервере, вам следует ответить сообщением с подсказкой и указанием того, какие отели были изменены.

Если недавней успешной выборки не было, для этого параметра будет установлено фиксированное значение интервала (чтобы избежать более серьезных проблем с большими задержками). Текущее фиксированное значение интервала составляет 1000 секунд, но может быть изменено.

Для получения дополнительной информации см. Сообщения- подсказки-ответы .

Примеры

В следующем примере показано сообщение с запросом подсказки :

Сообщение с запросом подсказки

В следующем примере показано сообщение с запросом подсказки: 

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

Корневой элемент сообщения Query . Сообщения Query – это запросы от Google об обновлении цен или метаданных. Они используются как в режимах доставки по запросу, так и в режиме измененной цены.

Сообщения с запросами цен

В сообщениях запроса цен указываются комбинации объектов недвижимости и маршрутов, для которых вы предоставляете цены.

Когда ваш сервер получает сообщение с запросом цен , он должен ответить сообщением <Transaction> , содержащим запрошенную информацию о ценах.

Дополнительную информацию см. в разделе Обзор цен .

Существует три специальных типа сообщений Query :

  • Цены в реальном времени: Google отвечает на конкретный запрос пользователя, запрашивая обновление цен в режиме реального времени. Когда партнеры получают сообщение Live pricing query , партнеры должны ответить сообщением <Transaction> , которое содержит запрошенную информацию о ценах в элементах <Result> .

  • С контекстным ценообразованием: Google обновляет свой кеш цен на основе контекстов, которые исторически популярны. Когда вы получаете сообщение With context query , вы должны ответить сообщением <Transaction> , которое содержит запрошенную информацию о ценах в элементах <Result> .

  • Метаданные: Google запрашивает обновления метаданных для номеров и пакетов номеров для указанных отелей. Когда вы получаете сообщение Metadata Query , вы должны ответить сообщением <Transaction> , в котором указаны данные о комнатах и ​​пакетах комнат в элементах <PropertyDataSet> . Дополнительную информацию см. в метаданных Room Bundle .

Синтаксис

Элемент <Query> использует следующий синтаксис:

Ценовой запрос 

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</Query>

Текущие цены 

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

С контекстом 

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

Метаданные 

<HotelInfoProperties>
  <Property>property_ID</Property>
  ...
</HotelInfoProperties>

Атрибуты

Элемент <Query> может содержать один атрибут: latencySensitive .

Атрибут latencySensitive является необязательным. Если этот параметр указан и ему присвоено значение true , это указывает на то, что запрос является Live Pricing Query . Чтобы Google отправлял запросы с атрибутом latencySensitive , обратитесь к своему техническому менеджеру по работе с клиентами (TAM).

Дочерние элементы

Элемент <Query> имеет следующие дочерние элементы:

Дочерний элемент Тип запроса Тип Описание
<AffectedNights> Pricing integer Количество ночей при длительном пребывании. Этот элемент используется только для запросов ценообразования Ranged Stay, используемых с измененными ценами.
<Checkin> Pricing Date Даты изменения конкретной цены.
<Context> Pricing (Live Pricing Queries only) <Context> Для запросов с ценами в реальном времени указываются определенные параметры, в соответствии с которыми выполняется запрос. Дочерние элементы включают в себя:
  • <Occupancy> : общее количество гостей.
  • <OccupancyDetails> : тип гостей, например взрослые или дети.
  • <UserCountry> : страна, в которой находится пользователь.
  • <UserDevice> : тип устройства, которое гость использовал для поиска отеля, например "mobile », « tablet » или « desktop ».

Элемент <Context> может повторяться в одном запросе, что позволяет выполнять запросы для разных заполнений. Обратитесь к <Context> для получения списка дочерних элементов, синтаксиса и примеров.

<FirstDate> Pricing Date Дата начала ряда маршрутов, к которым применяются цены. Этот элемент используется только для запросов цен на диапазон дат регистрации, используемых с измененными ценами.
<HotelInfoProperties> Metadata string Один или несколько объектов, для которых Google хочет обновить метаданные о номере и пакете номеров в сообщении Query метаданных. Этот элемент может содержать один или несколько элементов <Property> , определяющих идентификаторы свойств отеля.
<LastDate> Pricing Date Конечная дата для диапазона маршрутов, к которым применяются указанные цены. Этот элемент используется только для ценовых запросов диапазона дат регистрации, используемых с Pull + Hints.
<Nights> Pricing integer Количество ночей по конкретному маршруту – до 30.
<PropertyList> Pricing Object

Один или несколько идентификаторов отеля, для которого требуется обновление цен.

Определите каждый отель в элементе <Property> . Значением является строка, соответствующая идентификатору отеля в вашем списке отелей . Например: 

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

Примеры

Ценовой запрос

В следующем примере показано сообщение с запросом цен, в котором запрашивается обновление цен для набора отелей, доступных на 3 ночи и начиная с 23 мая 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>

Запрос цен в реальном времени

В следующем примере показан запрос Live Pricing с ограничением времени ответа 500 миллисекунд: 

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

С контекстным запросом 

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

Запрос метаданных

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

Дополнительные примеры, в том числе запросы цен на диапазон дат проживания и дат заезда, см. в примерах сообщений Query .

<Context>

Элемент <Context> описывает информацию для Live pricing query , включая количество и тип гостей, страну пользователя и устройство пользователя.

Множественный <Context> никогда не будет использоваться с разными странами пользователей или пользовательскими устройствами. Если для запроса нескольких номеров используется несколько <Context> , укажите цену каждого номера в качестве дополнительного пакета номеров для соответствующего объекта размещения или маршрута. Каждый объект размещения или маршрут должен иметь один блок <Result> , в который включены цены на несколько вариантов размещения.

Подробности ответа на запрос <Context> см. в разделе <OccupancyDetails> .

Синтаксис

Элемент <Context> использует следующий синтаксис:

Синтаксис 

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

Дочерние элементы

Элемент <Context> имеет следующие дочерние элементы:

Дочерний элемент Тип запроса Тип Описание
<Occupancy> Pricing integer Указывает общее количество гостей.

Хотя это и не обязательно, запросы с <Occupancy> должны приводить к сообщению транзакции с соответствующими пакетами помещений, определенными для каждого <Occupancy> , но если пакеты помещений недоступны, рекомендуется указать элемент <Occupancy> .

Примечание. <Occupancy> может не всегда присутствовать в запросе. В таких случаях вам следует вернуть цены на все помещения.

<OccupancyDetails> Pricing Object Ему предшествует <Occupancy> . Определяет гостей по типу, в том числе:
  • <NumAdults> : количество взрослых гостей.
  • <Children> и <Child=" age "> : указывает, какие гости являются детьми (обычно в возрасте 0–17 лет), и при необходимости включает возраст каждого ребенка.

Хотя это и не является обязательным, запросы с <OccupancyDetails> должны приводить к сообщению транзакции с соответствующими пакетами помещений, определенными для каждого <Occupancy> , но если пакеты помещений недоступны, рекомендуется указать элемент <OccupancyDetails> .

Примечание. <OccupancyDetails> не всегда может присутствовать в запросе. В таких случаях следует исходить из того, что все гости — взрослые.

<UserCountry> Pricing string

Фильтрует тарифы по стране, в которой находится пользователь. Значение представляет собой двухбуквенный код страны, например "US" для США, или код региона, например "EU" для «Европа».

Запросы с определенным <UserCountry> должны привести к сообщению транзакции с соответствующим блоком <Rates> , определенным для запрашиваемой страны.

<UserDevice> Pricing string

Фильтрует тарифы по типу устройства, с которого пользователь выполняет поиск. Возможные значения:

  • mobile
  • desktop
  • tablet

Запросы с определенным <UserDevice> должны приводить к сообщению транзакции с соответствующим блоком <Rates> определенным для запрашиваемого типа устройства.

Примеры

Размещение

В следующем примере показан запрос цен в реальном времени для <Occupancy> в <Context> . Запрос цены Live рассчитан на 3 взрослых гостей. 

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

Подробности о размещении

В следующем примере показан запрос цен в реальном времени с <OccupancyDetails> в <Context> . Запрос цен в реальном времени рассчитан на 4 гостей, 2 из которых — дети, и ищет тариф, применимый к бронированию гостей из США с мобильного устройства: 

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

Несколько контекстов

В следующем примере показано использование дополнительного элемента <Context> в запросе цен Live.

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