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

В этом разделе содержится справочная информация по сообщениям-запросам подсказок , сообщениям-ответам подсказок и сообщениям-запросам Google XML.

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

Корневой элемент сообщения Hint Response. Сообщения Hint Response определяют, какие комбинации отелей или маршрутов должны быть переоценены. Они являются вашим ответом на сообщение Hint Request от Google.

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

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

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

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

  • Дистанционное пребывание (или дистанционные маршруты )

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

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

Синтаксис

Элемент <Hint> использует разный синтаксис в зависимости от типа сообщения 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>

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

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

<!-- 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>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</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> .
  • Диапазон пребывания: более одного, если вы установили <MultipleItineraries> на "affected_dates" в сообщении <QueryControl> .
<Stay> Required Object Точные маршруты Контейнер для элементов <CheckinDate> и <LengthOfStay> в сообщении Hint Response точного маршрута. Каждый <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 на обновления цен или метаданных. Они используются как с режимами доставки Pull, так и с Changed pricing.

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

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

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

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

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

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

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

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

Синтаксис

Элемент <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 Количество ночей для ранжированного пребывания. Этот элемент используется только для запросов ценообразования ранжированного пребывания, используемых с измененным ценообразованием.
<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 хочет обновить метаданные Room и Room Bundle в сообщении Query метаданных. Этот элемент может содержать один или несколько элементов <Property> , которые указывают идентификаторы объектов недвижимости отеля.
<LastDate> Pricing Date Конечная дата для диапазона маршрутов, к которым применяется цена. Этот элемент используется только для запросов ценообразования Check-in Date Range, используемых с 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>

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

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

Примеры

Занятость

В следующем примере показан запрос ценообразования Live для <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>

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

В следующем примере показан запрос ценообразования Live с <OccupancyDetails> в <Context> . Запрос ценообразования Live предназначен для 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> в запросе цен в реальном времени. 

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