Запрос данных по отелям
В этом разделе описаны методы 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-заголовках передаются общие параметры, которые напрямую не влияют на результат запроса.
Обязательные заголовки
Заголовок |
Описание |
|
Токен, полученный от OAuth-сервера Яндекса. |
Необязательные заголовки
|
Произвольный идентификатор запроса для логирования и отладки. |
|
Формат содержимого. На данный момент возможно только значение |
|
Идентификатор партнера. Несмотря на то, что сервер API может идентифицировать партнера по токену авторизации, стоит также передавать его в заголовке для поиска проблем.
Например: |
|
IP-адрес пользователя. В некоторых сценариях по нему определяется регион пользователя. |
|
Идентификатор пользователя. В некоторых сценариях на основании этого параметра возможна персонализация. |