Получение списка отельных сниппетов с доступными предложениями

В результате запроса метод возвращает ленту сниппетов отелей с доступными предложениями по основным параметрам поиска и, возможно, дополнительным фильтрам. Если в запросе указан только идентификатор региона, будет вычислен bounding box и в ответе вернется список отелей, входящих в этот bounding box.

Метод поддерживает paging и polling.

Формат запроса

GET https://whitelabel.travel.yandex-net.ru/hotels/search/
  ? geo_id=<integer>
  & [bbox=<lon,lat~lon,lat>]
  & checkin_date=<date>
  & checkout_date=<date>
  & adults=<integer>
  & [children_ages=<list of integer>]
  & [order_by=<enum>]
  & [hotel_id=<string>]
  & [page_limit=<integer>]
  & [page_token=<string>]
  & [images_limit=<integer>]
  & [affiliate_clid=<string>]
  & [min_price=<integer>]
  & [max_price=<integer>]
  & [meal_type=<list of string>]
  & [stars=<list of integer>]
  & [nearby_sea=<boolean>]
  & [nearby_park=<boolean>]
  & [nearby_airport=<boolean>]
  & [wi_fi=<boolean>]
  & [air_conditioning=<boolean>]
  & [pool=<boolean>]
  & [car_park=<boolean>]
  & [spa=<boolean>]
  & [pets=<boolean>]
  & [sauna=<boolean>]
  & [bathhouse=<boolean>]
  & [restaurant=<boolean>]
  & [cafe=<boolean>]
  & [gym=<boolean>]
  & [transfer=<boolean>]
  & [min_rating=<enum>]
  & [accomm_type=<list of string>]
  & [free_cancellation=<boolean>]

Authorization: OAuth <OAuth token>
Content-Type: application/JSON

Параметры запроса

Параметр

Описание

geo_id*

Идентификатор региона, заданный пользователем.

bbox

Bounding box — область карты, в которой осуществляется поиск отелей в формате minLon,minLat~maxLon,maxLat.

checkin_date*

Дата заезда в формате YYYY-MM-DD.

checkout_date*

Дата выезда в формате YYYY-MM-DD.

adults*

Количество совершеннолетних гостей.

children_ages

Список возрастов детей, перечисленных через запятую. Например: children_ages=10,7,5.

order_by

Тип сортировки. Возможные значения:

  • relevance-desc — сортировка по релевантности, популярные отели (используется по умолчанию);
  • rating-desc — сортировка по убыванию рейтинга;
  • price-asc — от дешевых к дорогим;
  • price-desc — от дорогих к дешевым.

hotel_id

Идентификатор отеля. Данный отель будет первым в выдаче, независимо от наличия предложения по нему.

page_limit

Размер запрашиваемого блока (страницы). Значение по умолчанию — 10. Максимальное значение — 50.

page_token

Токен начала запрашиваемого блока (страницы). Для первой страницы должен быть пустым. Приходит вместе с предыдущей страницей в поле next_page_token.

images_limit

Максимальное количество изображений (фотографий) отеля, отдаваемое в каждом сниппете. Значение по умолчанию — 10. Максимальное значение — 20.

affiliate_clid

Идентификатор, выданный партнеру сервисом Яндекс Дистрибуция, к которому относится запрос. При отсутствии параметра будет использован clid, установленный партнеру при регистрации в системе.

min_price

Минимальная цена номера в отеле за одну ночь в рублях.

max_price

Максимальная цена номера в отеле за одну ночь в рублях.

meal_type

Тип питания. Можно указать несколько значений с разделителем |, в ответе вернется список отелей с любым из указанных типов питания. Возможные значения:

  • RO — без питания;
  • BB — только завтрак;
  • HB — полупансион;
  • FB — завтрак, обед и ужин;
  • AI — все включено.

Например, чтобы передать запрос на отели с одним из типов — без питания или только с завтраком (без кодирования URL): &meal_type=RO|BB.

stars

Звездность отеля. Можно указать несколько значений с разделителем |. Возможные значения: 1, 2, 3, 4, 5. Например, чтобы передать запрос на отели категории от 3 до 5 звезд (без кодирования URL): &stars=3|4|5.

nearby_sea

Только отели, расположенные рядом с морем. Возможное значение &nearby_sea=1.

nearby_park

Только отели, расположенные рядом с парком. Возможное значение &nearby_park=1.

nearby_airport

Только отели, расположенные рядом с аэропортом. Возможное значение &nearby_airport=1.

wi_fi

Только отели, в которых есть Wi-Fi. Возможное значение &wi_fi=1.

air_conditioning

Только отели, в которых есть номера с кондиционером. Возможное значение &air_conditioning=1.

pool

Только отели с бассейном. Возможное значение &pool=1.

car_park

Только отели с парковкой для автомобилей. Возможное значение &car_park=1.

spa

Только отели, в которых есть SPA. Возможное значение &spa=1.

pets

Только отели, в которых допускается размещение с домашними животными. Возможное значение &pets=1.

sauna

Только отели с сауной. Возможное значение &sauna=1.

bathhouse

Только отели с баней. Возможное значение &bathhouse=1.

restaurant

Только отели, в которых есть ресторан. Возможное значение &restaurant=1.

cafe

Только отели, в которых есть кафе. Возможное значение &cafe=1.

gym

Только отели, в которых для гостей доступен тренажерный зал. Возможное значение &gym=1.

transfer

Только отели, предлагающие услугу трансфера. Возможное значение &transfer=1.

min_rating

Минимальный рейтинг отеля. Возможные значения: 3, 4, 4.5. Например, отели с рейтингом 4.5 и выше: &minRating=4.5.

accomm_type

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

  • hotel — гостиница;
  • hostel — хостел;
  • camping — кемпинг;
  • tourist-resort — турбаза;
  • holiday-home — дом отдыха;
  • sanatorium — санаторий;
  • glamping — глэмпинг;
  • apartment — апартаменты.

Например, чтобы передать запрос на отели с одним из типов размещения — кемпинги или турбазы (без кодирования URL): &accom_type= camping|tourist-resort.

free_cancellation

Только отели с бесплатной отменой брони (действующей в настоящее время). Возможное значение &free_cancellation=1.

* Обязательный параметр

Пример запроса

https://whitelabel.travel.yandex-net.ru/hotels/search/?geo_id=213&checkin_date=2023-01-15
&checkout_date=2023-01-20&adults=2&children_ages=10%2C7&page_limit=25&page_token=50&stars=4%7C5
&max_price=10000&free_cancellation=1

Этот запрос выполнит поиск отелей с доступными предложениями по основным параметрам — город Москва, даты проживания с 15 января 2023 года по 20 января 2023 года, для двоих взрослых. Также указаны дополнительные фильтры: дети в возрасте 10 и 7 лет, категория отеля — 4 и 5 звезд, стоимость до 10 000 рублей, возможность бесплатной отмены брони, а также ограничение на выдачу результатов в 25 страниц.

Формат ответа

{
  "complete": (boolean),
  "hotel_snippets" : [
    {
      "hotel_id": "(string)",
      "name": "(string)",
      "location": {
        "country_name": "(string)",
        "settlement": {
          "type": "(string)",
          "name": "(string)"
          },
        "address": "(string)",
        "lon": (double),
        "lat": (double),
      },
      "stars": (integer),
      "rating": "(string)",
      "total_review_count": (integer),
      "total_image_count": (integer),
      "images" : [
        {
          "url_template": "(string)",
          "sizes": [
            {
              "size": "(string)",
              "height": (integer),
              "width": (integer)
            },
          ]
        }
      ],
      "top_offers": [
        {
          "name": "(string)",
          "price": {
            "value": (integer),
            "currency": "(string)"
          },
          "meal_type": {
            "id": "(string)",
            "name": "(string)"
          },
          "cancellation": {
            "refund_type": "(string)",
            "refund_rules": [
              {
                "type": "(string)",
                "penalty": {
                  "value": (integer),
                  "currency": "(string)"
                },
                "starts_at": "(string)",
                "ends_at": "(string)"
              },
            ]
          },
          "discount": {
            "strikethrough_price": (integer),
            "percent": (integer),
            "reason": "(string)"
          }
        }
      ],
      "landing_url": "(string)",
    },
  ],
  "next_page_token": "(string)",
  "bbox": {
    "lower_left": { "lat": (double), "lon": (double) },
    "upper_right": { "lat": (double), "lon": (double) }
  },
}

Параметры ответа

Параметр

Тип

Описание

complete

boolean

Если значение "complete": true — это означает, что поиск предложений полностью завершен (polling).

hotel_snippets

array

Список отельных сниппетов. Список может быть отсортирован по типу, который указан в параметре запроса order_by.

next_page_token

string

Токен следующей страницы. Значение передается в параметре запроса page_token для получения следующей страницы. not null — означает, что есть еще отели. Параметр может отсутствовать.

bbox

object

Актуальный bounding box на карте, ограничивающий найденные отели.

hotel_snippets object

hotel_id

string

Идентификатор отеля.

name

string

Название отеля.

location

object

Географическое расположение отеля.

stars

integer

Количество звезд. Принимает значение от 1 до 5 или может отсутствовать.

rating

string

Рейтинг отеля. Принимает значение от 1 до 5 в формате: дробное число, один знак после запятой, или может отсутствовать.

total_review_count

integer

Количество отзывов.

total_image_count

integer

Количество изображений (фотографий) отеля.

images

array

Список изображений (фотографий) отеля.

top_offers

array

Список лучших предложений на номер отеля.

landing_url

string

Ссылка на страницу отеля с подставленными основными параметрами поиска. Параметр может отсутствовать.

bbox object

lower_left

object

Координаты нижнего левого угла bounding box.

upper_right

object

Координаты правого верхнего угла bounding box.

location object

country_name

string

Страна.

settlement

object

Населенный пункт.

address

string

Адрес отеля.

lon

double

Долгота координат отеля.

lat

double

Широта координат отеля.

images object

url_template

string

Шаблон URL изображения, в котором %s нужно заменить на код определенного размера для получения URL изображения.

sizes

array of objects

Список доступных размеров изображения.

top_offers object

name

string

Название предложения. Параметр может отсутствовать.

price

object

Цена предложения.

meal_type

object

Тип питания. Если параметр отсутствует, то значение по умолчанию: RO — без питания.

cancellation

object

Правила отмены брони. Если параметр отсутствует, это означает, что предложение без возможности отмены и деньги не возвращаются.

discount

object

Скидка. Параметр может отсутствовать.

lower_left / upper_right object

lon

double

Долгота координат отеля.

lat

double

Широта координат отеля.

settlement object

type

string

Тип населенного пункта. Возможные значения:

  • CITY — город;
  • VILLAGE — деревня/село.

name

string

Название населенного пункта.

sizes object

size

string

Код размера изображения, который подставляется в шаблон URL.

height

integer

Высота в пикселях.

width

integer

Ширина в пикселях.

price object

value

integer

Цена предложения.

currency

string

Валюта предложения. Возможное значение — RUB.

meal_type object

id

string

Код типа питания. Возможные значения:

  • RO — без питания;
  • BB — только завтрак;
  • HB — полупансион;
  • FB — завтрак, обед и ужин;
  • AI — все включено.

name

string

Название типа питания.

cancellation object

refund_type

string

Тип отмены брони на текущий момент. Возможные значения:

  • FULLY_REFUNDABLE — полная отмена;
  • REFUNDABLE_WITH_PENALTY — отмена со штрафом;
  • NON_REFUNDABLE — отмена невозможна.

refund_rules

object

Подробные правила отмены брони.

discount object

strikethrough_price

integer

Базовая цена до скидки в рублях.

percent

integer

Процент скидки от 0 до 100. Может отсутствовать, если скидка не выражается в процентах.

reason

string

Основание скидки. Параметр может отсутствовать, если основание неизвестно.

refund_rules object

type

string

Тип отмены брони. Возможные значения:

  • FULLY_REFUNDABLE — полная отмена;
  • REFUNDABLE_WITH_PENALTY — отмена со штрафом;
  • NON_REFUNDABLE — отмена невозможна.

penalty

object

Сумма, которая будет потеряна при отказе от брони в период действия правила. Если тип отмены брони отличается от REFUNDABLE_WITH_PENALTY, то параметр примет значение null или будет отсутствовать.

starts_at

string

Дата и время начала действия правила в формате UTC (стандарт ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ.

ends_at

string

Дата и время окончания действия правила в формате UTC (стандарт ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ.

penalty object

value

integer

Сумма штрафа.

currency

string

Валюта. Возможное значение — RUB.

Пример ответа

{
  "complete": true,
  "hotel_snippets" : [
    {
      "hotel_id": "1019057204",
      "name": "Марриотт Москва Гранд Отель",
      "location": {
        "country_name": "Россия",
        "settlement": {
          "type": "CITY",
          "name": "Москва"
          },
        "address": "Москва, ул. Добролюбова, д. 11",
        "lon": 37.599343,
        "lat": 55.768301,
      },
      "stars": 5,
      "rating": "4.9",
      "total_review_count": 158,
      "total_image_count": 79,
      "images" : [
        {
          "url_template": "https://avatars.mds.yandex.net/get-altay/200322/2a0000015b0b6a243dc584f534df710b4480/%s",
          "sizes": [
            {
              "size": "XXXS",
              "height": 29,
              "width": 50
            },
            {
              "size": "XXL",
              "height": 640,
              "width": 1024
            },
          ]
        }
      ],
      "top_offers": [
        {
          "name": "Двухместный номер Deluxe (двуспальная кровать) (кровать king size)",
          "price": {
            "value": 53500,
            "currency": "RUB"
          },
          "meal_type": {
            "id": "RO",
            "name": "Без питания"
          },
          "cancellation": {
            "refund_type": "FULLY_REFUNDABLE",
            "refund_rules": [
              {
                "type": "FULLY_REFUNDABLE",
                "penalty": null,
                "starts_at": null,
                "ends_at": "2022-09-30T07:30:00Z"
              },
              {
                "type": "REFUNDABLE_WITH_PENALTY",
                "penalty": {
                  "value": 6500,
                  "currency": "RUB"
                },
                "starts_at": "2022-09-30T11:00:00Z",
                "ends_at": "2022-10-01T11:00:00Z"
              },
              {
                "type": "NON_REFUNDABLE",
                "penalty": null,
                "starts_at": "2022-10-01T11:00:00Z",
                "ends_at":
              }
            ]
          },
          "discount": {
            "strikethrough_price": 8125,
            "percent": 20,
            "reason": "Летнее предложение",
          }
        }
      ],
      "landing_url": "https://travel.yandex.ru/hotels/moscow/moskva-marriott-novyi-arbat/?checkin_date=2022-10-01&checkout_date=2022-10-10&adults=2&children_ages=10%2C7",
    },
  ],
  "next_page_token": "50",
  "bbox": {
    "lower_left": { "lat": 66.7712, "lon": 44.441234 },
    "upper_right": { "lat": 66.7901, "lon": 44.460123 }
  },
}
Написать в службу поддержки
Предыдущая
Получение списка отельных сниппетов
Следующая
Получение информации об отеле по идентификатору