API поиска отелей

Условия использования API поиска отелей

  1. Каждый поисковый запрос к поисковому API должен быть инициирован пользователем, результат запроса должен быть показан пользователю в полном объёме. В результатах каждого запроса должна быть кнопка «купить» рядом с каждым найденным вариантом.
  2. Коэффициент конверсии поисков в клики по кнопке «Купить» не должен быть ниже 9%. Конверсия кликнувших «Купить» в покупателей — не ниже 5%.
  3. Отправлять запрос можно только с locationId городов. Этот Id получается с помощью запроса «Города». Отправлять запросы с locationId стран запрещено (в ответ будет приходить ошибка).

Подробней о том, как получить доступ к API поиска отелей, читайте в статье Условия предоставления доступа к API поиска отелей.

Описание API поиска отелей и условия получения доступа

С помощью API для поиска отелей партнёр может разработать собственный сервис поиска отелей. Доступ к API ограничен и предоставляется в индивидуальном порядке по запросу от партнёра. API работает на поисковом движке сайта hotellook.ru.

Для получения доступа к API поиска отелей отправьте заявку на support@travelpayouts.com с указанием следующей информации:

  • URL вашего проекта.
  • Как именно будет использоваться API поиска?
  • Почему вам не подходят стандартные методы интеграции (поисковые формы, White Label, API доступа к данным)?
  • Предоставить прототип/дизайн поисковой страницы будущего проекта или существующий проект, где планируется использовать функцию поиска отелей, описание самого проекта и того, как будет использоваться наш поисковый API.

Обратите внимание! В архитектуре API поиска гостиниц отсутствуют данные от компании booking.com. Это связано с политикой компании в вопросе работы через API и White Label. Кроме того, данное API включает в себя только поиск и не содержит API бронирования отелей.

URL запроса

Начинается каждый запрос одинаково: http://engine.hotellook.com 

Работа с API поиска

Поисковая логика: поиск отеля по IATA-коду или cityId (id локации), или hotelId (id отеля). Могут быть указаны как все параметры вместе, так и какой-то один. Если указан hotelId и cityId — будет использован только hotelId, если указан iata и cityId — будет использован iata.

При использовании данного поиска существует возможность обращаться к его результату не сразу, а спустя некоторый период времени, не превышающий 15 минут. Обращение происходит по id запроса — searchId.

Обратите внимание! По умолчанию установлено ограничение: 200 запросов в час для одного IP-адреса пользователя. Если требуется обрабатывать больше запросов, напишите на support@travelpayouts.com.

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

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

  • cityId — идентификатор локации (из static/locations.json);
  • hotelId — идентификатор отеля (из static/hotels.json);
  • iata — код IATA (либо аэропорта, либо города). IATA-код указывается буквами верхнего регистра, например, MOW.

Примечание. В запросе должен использоваться хотя бы один из обязательных параметров iata, cityId или hotelId.

  • checkIn — дата заезда в формате 2021-08-30 (yyyy-MM-dd).
  • checkOut — дата выезда в формате 2021-08-31 (yyyy-MM-dd).
  • adultsCount — количество взрослых.
  • customerIP — IP-адрес пользователя, инициировавшего запрос.
  • childrenCount — количество детей, возможные значения — от 0 до 3.
  • childAge1, childAge2, childAge3 — возрасты детей. Указывается, если childrenCount больше 0. По умолчанию возраст детей равен 1 году.
  • lang — язык результата поиска. Указывается вместе с регионом:
    • en_US — Америка;
    • en_GB — Англия;
    • ru_RU — Россия;
    • de_DE — Германия;
    • en_AU — Австралия;
    • en_CA — Канада;
    • en_IE — Ирландия;
    • es_ES — Испания;
    • fr_FR — Франция;
    • it_IT — Италия;
    • pl_PL — Польша;
    • th_TH — Таиланд.
  • currency — валюта, значения как на сайте:
    • Австралийский доллар (AUD);
    • Азербайджанский манат (AZN);
    • Белорусский рубль (BYN);
    • Канадский доллар (CAD);
    • Швейцарский франк (CHF);
    • Китайский юань (CNY);
    • Египетский фунт (EGP);
    • Евро (EUR);
    • Фунт стерлингов (GBP);
    • Гонконгский доллар (HKD);
    • Индонезийская рупия (IDR);
    • Индийская рупия (INR);
    • Норвежская крона (KOK);
    • Казахстанский тенге (KZT);
    • Новозеландский доллар (NZD);
    • Филиппинское песо (PHP);
    • Пакистанская рупия (PKR);
    • Российский рубль (RUB);
    • Сингапурский доллар (SGD);
    • Тайский бат (THB);
    • Украинская гривна (UAH);
    • Доллар США (USD);
    • Южноафриканский ранд (ZAR).
  • waitForResult — ожидать завершения всех поисков по партнёрам, возможные значения 0 и 1.
    • 1 — соединение открыто до получения всех данных от партнёров, но не дольше timeout’а. Пользователю возвращается результат запроса и его searchId.
    • 0 — соединение завершается сразу, пользователю возвращается searchId (значение по умолчанию).

Получение md5-подписи (сигнатуры)

Пусть у нас имеются следующие параметры запроса:

  • iata=HKT; 
  • checkIn=2021-12-10; 
  • checkOut=2021-12-13; 
  • adultsCount=2; 
  • customerIP=192.168.1.1; 
  • childrenCount=1; 
  • childAge1=10;
  • lang=ru; 
  • currency=USD; 
  • waitForResult=0.

Отсортируем его по алфавиту:

  • adultsCount=2; 
  • checkIn=2021-12-10; 
  • checkOut=2021-12-13; 
  • childAge1=10;
  • childrenCount=1; 
  • currency=USD; 
  • customerIP=109.252.191.186; 
  • iata=HKT; 
  • lang=ru; 
  • waitForResult=0.

Теперь запишем значения отсортированных параметров через двоеточие и добавим перед ними партнёрский токен и маркер (найти их можно здесь):

ВашТокен:ВашМаркер:2:2021-12-10:2021-12-13:10:1:USD:109.252.191.186:HKT:ru:0

Данная строка используется для создания сигнатуры. В результате получим: 84f6ce98a14c0039b7bc2a546ae6109d.

Теперь чтобы создать запрос, необходимо взять параметры запроса, добавить к ним партнёрский маркер, сигнатуру и записать через & в строку поиска: http://engine.hotellook.com/api/v2/search/start.json?.

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

http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2021-08-10&checkOut=2021-08-13&adultsCount=2&customerIP=109.252.191.186&childrenCount=1&childAge1=10&lang=ru&currency=USD&waitForResult=0&marker=УкажитеВашМаркер&signature=84f6ce98a14c0039b7bc2a546ae6109d

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

{
   "searchId": "5201179",
   "status": "ok"
}

searchId — идентификатор поиска, возвращается запросом.

Параметры вывода результата

После получения searchId нужно отправить запрос для получения результатов поиска. В запросе можно передать дополнительные параметры сортировки и фильтрации. Запрос отправляется на адрес http://engine.hotellook.com/api/v2/search/getResult.json.

Обратите внимание! Для получения ответа по searchId формируется новая сигнатура.

"YourToken:YourMarker:limit:offset:roomsCount:searchId:sortAsc:sortBy". 

  • searchId — идентификатор поиска.
  • limit — получаемое количество отелей, от 0 до бесконечности, где 0 — нет лимита. По умолчанию — 0.
  • offset — количество пропускаемых отелей (начиная с первого), от 0 до бесконечности, где 0 — ни один отель не пропускается. По умолчанию — 0.
  • sortBy — способ сортировки:
    • popularity — по популярности;
    • price — по цене;
    • name — по названию;
    • guestScore — по пользовательскому рейтингу;
    • stars — по количеству звёзд.

По умолчанию — popularity.

  • sortAsc — способ сортировки значений
    • 1 — по возрастанию;
    • 0 — по убыванию.

По умолчанию - 1.

  • roomsCount — максимальное количество комнат, возвращаемых в каждом отеле, от 0 до бесконечности, где 0 — нет лимита. По умолчанию — 0.

Пример запроса на вывод результата

http://engine.hotellook.com/api/v2/search/getResult.json?searchId=4034914&limit=10&sortBy=price&sortAsc=1&roomsCount=0&offset=0&marker=УкажитеВашМаркер&signature=364c38baee5cf11b382297bfd4338ce6

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

При попытке получить результат поиска до его окончания возникает ошибка errorCode 4. Это означает, что результаты поиска еще не готовы. При этом поиск не прерывается и для получения результата нужно повторить запрос позже.

{
   "status":"ok",
   "result":[{
      "fullUrl":"http://search.hotellook.com/?language=ru&marker=16886&hotelId=362691",
      "maxPricePerNight":46,
      "maxPrice":138,
      "photoCount":50,
      "guestScore":63,
      "address":"23/8 Soi Hub-Aik, Phuket Road, Muang District",
      "minPriceTotal":40,
      "id":362691,
      "price":13,
      "name":"Rome Place Hotel",
      "url":"/search/?marker=16886&hotelId=362691",
      "popularity":47,
      "location":{
         "lon":98.39146,
         "lat":7.878922
      },
      "stars":3,
      "distance":10.6,
      "amenities":[],
      "rooms":[{
         "bookingURL":"/r/?language=ru&checkIn=2015-06-10¤cy=USD&children=5&host=v2%3A16886&marker=16886&transparent=1&roomId=0&adults=2&locationId=30553&checkOut=2015-06-13&gateId=43&hotelId=362691",
         "options":{
            "available":5,
            "deposit":true,
            "refundable":false,
            "breakfast":false
         },
         "type":"",
         "tax":0,
         "desc":"Double or Twin STANDARD",
         "fullBookingURL":"http://search.hotellook.com/r?language=ru&checkIn=2015-06-10&cy=USD&children=5&host=v2%3A16886&marker=16886&transparent=1&roomId=0&adults=2&locationId=30553&checkOut=2015-06-13&gateId=43&hotelId=362691",
         "agencyName":"Travel.ru",
         "agencyId":"43",
         "total":40,
         "price":13,
         "internalTypeId":"1"
      }],
      "rating":63
}]}

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

Блок result содержит:

  • fullUrl — ссылка на отель с вашим партнерским маркером;
  • maxPrice — максимальная цена номера за весь период;
  • maxPricePerNight — максимальная цена за ночь;
  • price — средняя цена за номер;
  • minPriceTotal — минимальная стоимость за весь период;
  • photoCount — количество фотографий отеля;
  • guestScore — рейтинг туристов;
  • id — id отеля в базе;
  • name — название отеля;
  • distance — расстояние от отеля до центра города;
  • amenities — удобства в отеле (расшифровку значений вы можете найти здесь);
  • address — адрес отеля;
  • location — местоположение отеля:
    • lat — широта отеля;
    • lon — долгота отеля.
  • stars — количество звезд у отеля;
  • url — ссылка на отель без адреса сайта hotelook.com;

Блок rooms содержит:

  • type, desc — тип номера;
  • total — стоимость проживания за всё время;
  • price — стоимость номера в сутки;
  • tax — налоги и сборы;
  • options — дополнительные услуги (питание, wi-fi и т. д.):
    • available — (int) количество оставшихся комнат;
    • breakfast — (bool) включён ли завтрак;
    • refundable — (bool) возможность возврата;
    • deposit — (bool) оплата на сайте OTA (при бронировании);
    • cardRequired — (bool) обязательно наличие банковской карты;
    • smoking — (bool) можно ли курить в номере;
    • freeWifi — (bool) есть ли бесплатный Wi-Fi в номере;
    • hotelWebsite — (bool) предложение ведёт на официальный сайт отеля.
  • bookingURL — ссылка на бронирование с заполненными данными без адреса сайта hotellook.com;
  • fullBookingURL — полный адрес на бронирование с заполненными данными;
  • internalTypeId — группировка по типам комнат;
  • agencyId — id агентства по бронированию;
  • agencyName — название агентства по бронированию;
  • rating — рейтинг посетителей. Параметры рассчитывается на основе рейтинга гостей, который составляется на основе голосования.

Вы можете получить фотографии отелей и другую информацию об отелях с помощью API данных отелей.

Ошибки запросов

API поиска отелей возвращает следующие ошибки:

  • errorCode 1 — не все обязательные параметры указаны или указаны неверно;
  • errorCode 2 — как минимум один из параметров не соответствует формату;
  • errorCode 3 — доступ запрещён;
  • errorCode 4 — поиск еще не закончен.

При наличии любой из ошибок запрос завершается с http-статусом, отличным от 200 (например 409, 403, 400 и др.).