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

В этом разделе описаны методы API, которые позволяют получать информацию об отелях и предложения по ним. Эти методы имеют общие свойства:

Определения

Bounding box — область карты (прямоугольник), заданный парой координат (левый верхний угол, правый нижний угол).

Paging — запрос данных пачками, при котором входные параметры определяют первый элемент и размер пачки.

Polling — режим работы, в котором метод API может ответить, что результат работы не готов. В этом случае клиенту API следует повторно вызвать метод с теми же параметрами через некоторое время и периодически повторять вызов до успешного получения результата.

Саджест (suggest) — подсказка пользователю о том, какие объекты система может предложить по введенной строке поиска. Подсказки представляют собой краткую информацию об известных системе объектах (регионах и отелях), названия которых, а иногда и другая информация, подходят под введенную строку поиска.

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

Основные параметры поиска отелей — минимальный обязательный набор параметров, по которым возможен поиск отелей: идентификатор отеля или bounding box, дата заезда, дата выезда, количество взрослых гостей, список возрастов детей.

Сценарии использования

Получение списка отельных сниппетов

По названию региона

С помощью метода GET hotels/suggest можно получить подсказки по введенной строке поиска, чтобы определить регион. Передайте идентификатор региона и основные параметры поиска с помощью метода GET hotels/search для получения списка отельных сниппетов по региону.

По названию отеля

С помощью метода GET hotels/suggest можно получить подсказки по введенной строке поиска, чтобы определить отель. Передайте идентификатор отеля, идентификатор региона и основные параметры поиска с помощью метода GET hotels/search для получения списка отельных сниппетов. В списке первым будет отель, идентификатор которого передан в запросе, далее по списку — отели переданного в запросе региона.

Отель будет передан, даже если в текущее время он недоступен. При этом список оферов по отелю будет пустым.

Виджет отелей

Получение результатов поиска с помощью метода GET hotels/search по идентификатору региона и значениям по умолчанию для остальных основных параметров поиска. Например: через две недели, продолжительность — одна неделя, для двоих взрослых.

Переход к карточке отеля

По идентификатору отеля

Из полученного сниппета возьмите идентификатор отеля и передайте его с помощью метода GET hotels/hotel для получения данных об отеле. Для получения более конкретной информации об отзывах, предложениях отеля и его фотографий используйте связанные методы GET hotels/hotel/reviews, GET hotels/hotel/offers, GET hotels/hotel/images — их можно вызвать параллельно. Также можно повторно вызвать эти методы, когда при скроллинге отзывов и картинок нужно получить следующую пачку объектов.

По названию отеля

С помощью метода GET hotels/suggest можно получить подсказки по введенной строке поиска, чтобы определить идентификатор отеля. Затем с помощью метода GET hotels/hotel и связанных методов GET hotels/hotel/reviews, GET hotels/hotel/offers, GET hotels/hotel/images можно получить необходимую информацию. В указанных методах нужно будет дополнить основные параметры поиска значениями по умолчанию. Например: через две недели, продолжительность — одна неделя, для двоих взрослых.

Скроллинг ленты отелей

С помощью метода GET hotels/search можно запросить следующую пачку сниппетов, когда при скроллинге результатов пользователь приближается к границе запрошенной ленты.

Изменение параметров карты (области видимости карты на экране)

С помощью метода GET hotels/search можно запросить результаты поиска по новому bounding box, который соответствует области видимости карты на экране, и по остальным сохраненным основным параметрам поиска.

Сортировка выдачи

С помощью метода GET hotels/search можно запросить результаты поиска с новым значением параметра order_by.

Заголовки

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

Обязательные заголовки

Заголовок

Описание

Authorization: OAuth <OAuth token>

Токен, полученный от OAuth-сервера Яндекса.

Необязательные заголовки

X-Correlation-Id: <UID запроса к API>

Произвольный идентификатор запроса для логирования и отладки.

Content-Type: application/JSON

Формат содержимого. На данный момент возможно только значение application/JSON — оно используется по умолчанию.

X-YaTravel-PartnerId: <ID партнера>

Идентификатор партнера. Несмотря на то, что сервер API может идентифицировать партнера по токену авторизации, стоит также передавать его в заголовке для поиска проблем. Например: X-YaTravel-PartnerId: aviasales.

X-User-IP: <IP-адрес пользователя>

IP-адрес пользователя. В некоторых сценариях по нему определяется регион пользователя.

X-User-ID: <ID пользователя>

Идентификатор пользователя. В некоторых сценариях на основании этого параметра возможна персонализация.

Написать в службу поддержки