FAQ по API от Авиасейлс

Что такое API и зачем оно нужно?

API Aviasales и Hotellook позволяет отправлять запросы к нашему серверу и получать в ответ полезные данные о билетах и отелях. Партнёры могут получать:

  • данные о самых дешевых билетах по выбранному направлению;
  • информацию об аэропортах и авиакомпаниях;
  • список самых популярных направлений перелёта из выбранного города;
  • подробные сведения об отеле или номере;
  • подборку спецпредложений авиакомпаний и многое другое.

Какие из ваших сервисов представлены в API?

При помощи API партнёры получают доступ к следующим сервисам:

  • подборка спецпредложений;
  • календарь цен;
  • поиск авиабилетов;
  • поиск отелей;
  • карта низких цен.

Как получить доступ к API?

Сразу после регистрации в партнерской программе партнёры получают доступ к API данных, API карты цен, API календаря цен и статическим данным по отелям. Кроме того, при соответствии проекта партнёра требованиям, ему предоставляется доступ к поиску авиабилетов и отелей.

Где может использоваться API?

API рекомендуется использоваться для вывода на страницах сайта:

  • статических данных о городах, аэропортах, авиакомпаниях;
  • стоимости перелётов и номеров в отелях;
  • разработки собственного поиска авиабилетов и отелей.

А также для создания мобильного приложения по поиску авиабилетов.

У вас несколько видов API, в чем их ключевые отличия?

API доступа к данным (открыты сразу после регистрации) предоставляют партнёрам доступ к нашему кэшу, в котором хранится история запросов всех пользователей за период от двух до семи дней в зависимости от типа запроса.

Поиск авиабилетов в реальном времени и поиск отелей позволяют партнёрам получать актуальные данные от агентств и авиакомпаний через наш сервер.

Какие имеются ограничения на запросы к API?

По умолчанию при работе с API поиска билетов один партнер не может отправлять более 200 запросов в час с одного IP. При необходимости это ограничение может быть изменено. Для API доступа к данным ограничения на количество запросов нет. При работе с API данных рекомендуется кэшировать результаты на своей стороне на 24 часа, это уменьшит количество запросов к нашим серверам и увеличит скорость загрузки страниц сайта партнёра.

Существуют ли требования к сайтам для использования на них API?

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

  1. Каждый поисковый запрос должен инициироваться пользователем. Результат запроса должен отображаться пользователю в полном объёме и содержать кнопку «Купить» рядом с каждым вариантом перелета.
  2. Предоставить прототипы/дизайн будущего проекта или существующий проект, где планируется использовать функцию поиска авиабилетов. Описание самого проекта и того, как будет использоваться наш API.
  3. *Минимальный коэффициент конверсии поисков в клики по кнопке «Купить» должен быть 9%. Конверсия кликнувших «Купить» в покупателей — не ниже 5%.

* — не принимается во внимание для проектов в рамках акций и партнёрских марафонов.

Как сформировать сигнатуру (md5-подпись) для запроса к API поиска билетов?

Сигнатура — это закодированный ключ запроса, который формируется из параметров запроса, партнёрского ID (маркера) и токена. Чтобы создать сигнатуру, необходимо выполнить несколько шагов.

Допустим, наш запрос имеет вид:

{
 "marker": "%marker%",
 "host": "%server_host%",
 "user_ip": "%user_ip_address%",
 "locale": "ru",
 "trip_class": "Y",
 "passengers": {
 "adults": "1",
 "children": "0",
 "infants": "0"
 },
 "segments": [
 {
 "origin": "MOW",
 "destination": "LED",
 "date": "2015-11-25"
 },
 {
 "origin": "LED",
 "destination": "MOW",
 "date": "2015-12-18" }]}
  1. Отсортируйте параметры из запроса по алфавиту: host=beta.aviasales.ru&locale=ru&marker=ВпишитеСюдаВашПартнёрскийID(Маркер)&adults=1&children=0&infants=0&date=2015-11-25&destination=LED&origin=MOW&date=2015-12-18&destination=MOW&origin=LED&trip_class=Y&user_ip=127.0.0.1. Обратите внимание, при сортировке учитывается вложенность данных. Если элемент содержит массив (например, segments) или список параметров (например, passengers), то содержимое данного элемента сортируется отдельно и ставится на его место в общем списке. При этом содержимое не сортируется с параметрами верхнего уровня. Параметры внутри массива сортируются в порядке следования фигурных скобок { }. Ваш партнёрский маркер находится в левом нижнем углу личного кабинета партнёра.

  2. После сортировки соберите строку, содержащую только значения параметров (порядок следования остается таким же как в п.1): beta.aviasales.ru:ru:ВпишитеСюдаВашПартнёрскийID(Маркер):1:0:0:2015-11-25:LED:MOW:2015-12-18:MOW:LED:Y:127.0.0.1. Друг от друга значения отделяются двоеточием.
  3. Добавьте в начало строки из п. 2 значение вашего API токена.

    Токен находится в личном кабинете в разделе «Разработчикам».

  4. Используя полученную строку «ВпишитеСюдаВашТокен:beta.aviasales.ru:ru:ВпишитеСюдаВашПартнёрскийID(Маркер):1:0:0:2015-11-25:LED:MOW:2015-12-18:MOW:LED:Y:127.0.0.1», сформируйте md-5 подпись. Полученный результат 0203ccb0c37534cc9d0835ac3bb3cfec и является сигнатурой запроса.
    Внимание! Сигнатура чувствительна к регистру.

Как сформировать сигнатуру (md5-подпись) для запроса к API поиска отелей?

Допустим, наш запрос имеет вид:

http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2015-12-10&checkOut=2015-12-13&adultsCount=2&customerIP=192.168.1.1&childrenCount=1&lang=ru&currency=USD&timeout=20&waitForResult=0

Значит, у нас имеются следующие параметры запроса:

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

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

  • adultsCount=2;
  • checkIn=2015-12-10;
  • checkOut=2015-12-13;
  • childrenCount=1;
  • currency=USD;
  • customerIP=192.168.1.1;
  • iata=HKT;
  • marker=%marker%;
  • lang=ru;
  • timeout=20;
  • waitForResult=0.

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

ВпишитеСюдаВашТокен:ВпишитеСюдаВашПартнёрскийID(Маркер):2:2015-12-10:2015-12-13:1:USD:192.168.1.1:HKT:ru:20:0

Данная строка используется для создания сигнатуры.
Внимание! Сигнатура чувствительна к регистру.

Теперь чтобы создать запрос, необходимо взять параметры запроса, добавить к ним партнёрский маркер, сигнатуру и записать через & в строку поиска: http://engine.hotellook.com/api/v2/search/start.json?iata=HKT&checkIn=2015-12-10&checkOut=2015-12-13&adultsCount=2&customerIP=192.168.1.1&childrenCount=1&lang=ru&currency=USD&timeout=20&waitForResult=0&marker=16886&signature=878c8cdd72222323d925dd8e8a37c6b1

Как определить аэропорт вылета и назначения?

Чтобы в ответе API поиска билетов узнать, является ли аэропорт пунктом назначения или отправления, вам нужно взять данные из двух блоков. Первый — это airports, в нем указан IATA-код города, в котором расположен каждый аэропорт. Второй — блок flight, он содержит параметры arrival и departure — это IATA-коды городов назначения и отправления. Сопоставляя эти значения, вы определите тип аэропорта.

Как узнать IATA-код аэропорта для отправки API запроса?

Список IATA-кодов аэропортов можно скачать здесь.

Почему я получаю меньше билетов, чем в вашем поиске?

Когда вы используете API поиска авиабилетов в реальном времени, вам приходит ответ от тех же агентств и авиакомпаний, что и у нас на сайте. Самый распространенный случай, когда ответ меньше — это недостаточная пауза, между отправкой запроса и получением результата. Дело в том, что для получения ответа ото всех агентств требуется порядка 30 секунд. Если запросить результат раньше, то он может содержать не все данные.

Сколько по времени хранится результат в API поиска авиабилетов?

Результат с вариантами перелетов хранится порядка 15 минут. После чего удаляется с сервера.

Объясните в двух словах, как работает API поиска авиабилетов в реальном времени?

Логика такая:

  1. На адрес http://api.travelpayouts.com/v1/flight_search отправляете запрос с параметрами, которые описаны в документации.
  2. Получаете ответ, который содержит search_id.
  3. Используя этот search_id, отправляете новый запрос на адрес http://api.travelpayouts.com/v1/flight_search_results?uuid=%search_id%
  4. Продолжаете отправлять запрос из п. 3, пока не получите массив с единственным параметром — search_id.
  5. Обрабатываете полученные данные.

Какие языки поддерживаются в API поиска авиабилетов и отелей?

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

  • русский;
  • английский;
  • французкий;
  • испанский;
  • немецкий;
  • итальянский.

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

Что такое автокомплит и как его реализовать при поиске отелей?

Автокомплит — это когда пользователь начинает вводить запрос в строку поиска, а система показывает ему найденные совпадения.

Чтобы реализовать автокомплит при поиске отелей используется запрос вида:

http://engine.hotellook.com/api/v2/lookup.json?query=moscow&lang=ru&lookFor=hotel&limit=1,

где query — основной параметр, задаётся в виде текста, при этом строится автокомплит по тексту; lang — язык вывода; limit — ограничение количества выводимых результатов, от 1 до 100, по умолчанию — 10; convertCase — автоматическое изменение раскладки (актуально для русскоязычных пользователей, например, при запросе «vjcrdf» будет найдена «москва»). Значения — 1 или 0, по умолчанию — 1. Подробнее в документации.

Как реализовать автокомплит при работе с API поиска авиабилетов?

Чтобы реализовать в поиске автокомплит города или аэропорта, используйте запрос следующего вида:

http://autocomplete.travelpayouts.com/places2?term=Mos&locale=ru&types[]=country&callback=function

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

  • term — текст для поиска (основной параметр);
  • locale — язык вывода (список поддерживаемых яызков в конце статьи);
  • types[] — массив, в котором указывается, для чего создается автокомплит (city, airport, country);
  • callback — параметр для обратной совместимости клиентов, работающих на jsonp.

Подробнее в документации.

Как определить местоположения пользователя?

Запрос вида:

http://www.travelpayouts.com/whereami?locale=ru&callback=useriata&ip=62.105.128.0

возвращает IATA-код и название ближайшего от пользователя города. Подробнее смотрите в статье API определения местоположения по IP-адресу.

Как определить города отправления и назначения из ответа API поиска авиабилетов?

В каждом ответе содержатся параметры original_destination и original_origin — это значения городов отправления и назначения.

Например, мы сформировали запрос на перелет Мурманск-Барнаул-Мурманск, на который получили ответ с вариантами перелётов.

Рассмотрим один перелёт туда-обратно из этого ответа:

{
"proposals":[
    {
    "sign":"ce23f75099cc3756c1396362061e379b",
    "max_stops":2,
    "carriers":[
        "SU"
    ],
    "min_stop_duration":110,
    "terms":{
        "183":{
            "currency":"rub",
            "price":"28855",
            "unified_price":28855,
            "url":18300000
        }
    },
    "segment":[
        {
        "flight":[
            {
                "departure_time":"11:25",
                "departure_timestamp":1432542300,
                "departure":"MMK",
                "local_departure_timestamp":1432553100,
                "duration":125,
                "operating_carrier":"SU",
                "arrival":"LED",
                "number":6342,
                "delay":0,
                "arrival_time":"13:30",
                "aircraft":"319",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-25",
                "arrival_timestamp":1432549800,
                "local_arrival_timestamp":1432560600
            },
            {
                "departure_time":"18:45",
                "departure_timestamp":1432568700,
                "departure":"LED",
                "local_departure_timestamp":1432579500,
                "duration":75,
                "operating_carrier":"SU",
                "arrival":"SVO",
                "number":39,
                "delay":315,
                "arrival_time":"20:00",
                "aircraft":"320",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-25",
                "arrival_timestamp":1432573200,
                "local_arrival_timestamp":1432584000
            },
            {
                "departure_time":"21:50",
                "departure_timestamp":1432579800,
                "departure":"SVO",
                "local_departure_timestamp":1432590600,
                "duration":250,
                "operating_carrier":"SU",
                "arrival":"BAX",
                "number":1430,
                "delay":110,
                "arrival_time":"05:00",
                "aircraft":"321",
                "departure_date":"2015-05-25",
                "arrival_date":"2015-05-26",
                "arrival_timestamp":1432594800,
                "local_arrival_timestamp":1432616400
            }
            ]
        },
        {
        "flight":[
            {
                "departure_time":"09:00",
                "departure_timestamp":1434596400,
                "departure":"BAX",
                "local_departure_timestamp":1434618000,
                "duration":260,
                "operating_carrier":"SU",
                "arrival":"SVO",
                "number":1433,
                "delay":0,
                "arrival_time":"10:20",
                "aircraft":"320",
                "departure_date":"2015-06-18",
                "arrival_date":"2015-06-18",
                "arrival_timestamp":1434612000,
                "local_arrival_timestamp":1434622800
            },
            {
                "departure_time":"15:05",
                "departure_timestamp":1434629100,
                "departure":"SVO",
                "local_departure_timestamp":1434639900,
                "duration":155,
                "operating_carrier":"SU",
                "arrival":"MMK",
                "number":1324,
                "delay":285,
                "arrival_time":"17:40",
                "aircraft":"SU9",
                "departure_date":"2015-06-18",
                "arrival_date":"2015-06-18",
                "arrival_timestamp":1434638400,
                "local_arrival_timestamp":1434649200
            }
        ]
        }
    ],
    "is_direct":false,
    "total_duration":1575,
    "segment_durations":[
        875,
        700
    ],
    "stops_airports":[
        "LED",
        "SVO",
        "BAX",
        "SVO",
        "MMK"
    ],
    "segments_time":[
        [
            1432542300,
            1432594800
        ],
        [
            1434596400,
            1434638400
        ]
    ],
    "segments_airports":[
        [
            "MMK",
            "BAX"
        ],
        [
            "BAX",
            "MMK"
        ]
    ],
    "validating_carrier":"SU",
    "max_stop_duration":315
    }]
}

В ответе содержится параметр max_stops — он показывает, сколько максимально пересадок в данном результате.

В массиве segment содержится информация о перелётах в массивах flight.

Первый массив flight — это перелёт туда, второй — обратно. В каждом из массивов с перелетами находятся параметры departure и arrival — это IATA-коды аэропортов отправления и назначения.

В нашем примере мы видим, что найдены:

  • рейс туда: «Мурманск (MMK) — Санкт-Петербург (LED) — Москва (SVO) — Барнаул (BAX)»;
  • рейс обратно: «Барнаул (BAX) — Москва (SVO) — Мурманск (MMK)».

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

К слову, в ответе ещё содержится параметр segments_airports, который содержит IATA-коды аэропортов отправления и назначения без аэропортов пересадок.