tv-search-gateway (1.1.0)

Download OpenAPI specification:

Сервис поиска туров

API Tourvisor предоставляет возможность осуществлять поиск туров, получать горящие туры и информацию по отелям (описание отелей).
Ответы API возвращаются в формате JSON, в кодировке UTF-8 (Unicode).

Авторизация

Авторизация осуществляется по JWT-токену.

  1. Получить JWT-токен можно в личном кабинете турагента - см. инструкцию
  2. При каждом запросе к методам API нужно добавлять JWT-токен в заголовок "Authorization" с добавлением в значение параметра текста "Bearer " + JWT-токен. Пример Authorization: Bearer eyJhbGciOiJIUzUx

Общее описание

В API доступны следующие разделы, каждый из которых оплачивается отдельно (см.описание)

  1. Поиск туров - основной сервис, содержит:

    • Справочники (список городов вылета, стран, курортов, отелей и т.д.). Используются для отображения в поисковой форме, а также для передачи параметров в поиск туров и другие сервисы.
    • Поиск туров. Позволяет по заданным параметрам найти туры у всех подключенных туроператоров.
    • Данные тура. Позволяет получить детальную информацию о туре по его идентификатору (полученному из поиска). Используется, например, для отображения карточки тура.
    • Получение авиарейсов (актуализация). Метод позволяет получить список авиарейсов, а также окончательную (актуализированную) стоимость тура из корзины туроператора.
  2. Описания отелей (оплачивается отдельно).

    • Позволяет по идентификатору отеля получить его детальное описание, фотографии, координаты и т.п. (список отелей с идентификаторами можно получить в справочнике отелей)
  3. Описания номеров отелей (оплачивается отдельно).

    • Позволяет получить список номеров отелей с их описаниями.
  4. Горящие туры (оплачивается отдельно).

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

Тарификация

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

Поисковым запросом считаются:

  1. Старт поиска туров (запросы на получение результатов поиска не учитываются).
  2. Продолжение поиска туров.
  3. Получение авиарейсов (актуализация) - так как в этом случае также осуществляются запросы туроператору.

Все остальные типы запросов (справочники, данные тура, информация по отелю, горящие туры) отдельно не тарифицируются и в суточном лимите не учитываются.

Ограничения

Для защиты от возможных ошибок также предусмотрены ограничения на количество запросов в минуту.

Для справочников (а также описания отелей и номеров отелей) - 120 запросов в минуту.

Все остальные методы - 300 запросов в минуту:

  1. Поиск туров
  2. Результаты поискового запроса
  3. Поиск туров (продолжение)
  4. Статус поискового запроса
  5. Данные тура
  6. Авиарейсы тура и актуальные цены
  7. Горящие туры

Нововведения по сравнению со старой версией API

  1. Получение списка городов вылета по стране вылета.
  2. Добавление справочника городов прибытия (аэропортов) и возможности фильтрации по ним.
  3. Добавление справочника валют и расширение справочника курсов валют.
  4. Добавление справочника списка услуг в отелях и возможности фильтрации по услугам.
  5. Добавление справочника типов отелей и возможности фильтрации по типам.
  6. Добавление справочника номеров отелей.

departure

Города вылета

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

Authorizations:
ApiKeyAuth
query Parameters
departureCountryId
integer
Enum: 1 2 3 4 5 99

Идентификатор страны вылета:
1 - Россия
2 - Беларусь
3 - Казахстан
4 - Узбекистан
5 - Кыргызстан
99 - Другие страны

Responses

Response samples

Content type
application/json
[
  • {
    }
]

country

Страны

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

Authorizations:
ApiKeyAuth
query Parameters
departureId
integer

Идентификатор города вылета

onlyCharter
boolean

Признак получения результатов только для чартерных перелётов

Responses

Response samples

Content type
application/json
[
  • {
    }
]

arrival

Города прилёта

Метод получения списка городов прилёта (аэропорт) для конкретного города вылета.
Данный справочник необходим для запуска поиска туров в определенный аэропорт. Например, возможно запустить поиск туров по Турции с прилётом в аэропорт города Анталья.

Authorizations:
ApiKeyAuth
query Parameters
departureId
required
integer

Идентификатор города вылета

onlyCharter
required
boolean
Default: false

Признак получения результатов только для чартерных перелётов

Responses

Response samples

Content type
application/json
[
  • {
    }
]

currency

Методы получения информации по валютам.

Валюты

Метод получения списка (справочника) валют с ISO-кодом.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Курсы валют

Метод получения курсов валют операторов на текущую дату.

Authorizations:
ApiKeyAuth
path Parameters
currencyId
required
string

Идентификатор валюты

Responses

Response samples

Content type
application/json
[
  • {
    }
]

hotel-group-service

Услуги в отелях

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

Authorizations:
ApiKeyAuth
query Parameters
countryId
integer

Идентификатор страны

regionIds
Array of integers

Идентификаторы курортов

Responses

Response samples

Content type
application/json
[
  • {
    }
]

hotel-type

Типы отелей

Метод получения типов отелей (отель, апартаменты, вилла, санаторий и т.д.) по конкретной стране. Нужные типы отелей можно использовать в поиске (например, искать только по санаториям), а также получать список отелей нужного типа.

Authorizations:
ApiKeyAuth
query Parameters
countryId
required
integer

Идентификатор страны

Responses

Response samples

Content type
application/json
[
  • {
    }
]

hotel

Методы получения информации по отелям.

Отели

Метод получения списка отелей по конкретной стране. Также можно задать дополнительные параметры фильтрации (курорт, категория, тип отеля и т.п.), если требуется получить список с учетом нужных параметров. В списке выдается только базовая информация (идентификатор отеля, название, курорт, рейтинг, координаты и т.п.).

Authorizations:
ApiKeyAuth
query Parameters
countryId
required
integer

Идентификатор страны

regionId
integer

Идентификатор курорта

category
integer <= 5

Категория (от и выше)

types
Array of integers

Тип отеля

rating
number <= 5

Рейтинг (от и выше)

page
integer
Default: 1

Страница

limit
integer
Default: 20

Количество элементов на странице

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Описание отеля

Метод получения детальной информации по отелю. Выдается полное описание, фотографии, координаты и т.п. Данный метод доступен только при подключении API Описания отелей (не входит в API Поиск туров и оплачивается отдельно). Подробнее см. тарифы.

Authorizations:
ApiKeyAuth
path Parameters
hotelId
required
integer

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

room

Номера отелей

Получение описаний номеров отелей по их идентификаторам (идентификатор roomId из результатов поиска).

Authorizations:
ApiKeyAuth
query Parameters
ids
required
Array of integers

Идентификаторы (не более 30)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

meal

Типы питания

Метод получения списка доступных типов питания.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

operator

Операторы

Получение списка туроператоров. Выдает полный список активных туроператоров с кодами.

Authorizations:
ApiKeyAuth
query Parameters
departureId
integer

Идентификатор города вылета

countryId
integer

Идентификатор страны

Responses

Response samples

Content type
application/json
[
  • {
    }
]

region

Курорты

Метод получения перечня курортов. Без параметров выдает полный список курортов.

Authorizations:
ApiKeyAuth
query Parameters
countryId
integer

Идентификатор страны

arrivalId
integer

Идентификатор города прилёта

Responses

Response samples

Content type
application/json
[
  • {
    }
]

subregion

Субкурорты

Метод получения субкурортов (вложенный уровень детализации некоторых курортов). Без параметров выдается полный список субкурортов (субрегионов). В одном курорте может быть несколько субкурортов, либо для каких-то курортов может вообще не быть субкурортов.

Authorizations:
ApiKeyAuth
query Parameters
countryId
integer

Идентификатор страны

regionId
integer

Идентификатор курорта

Responses

Response samples

Content type
application/json
[
  • {
    }
]

tour-date

Доступные даты

Получение списка доступных дат туров (вылетов) для конкретного города и страны. Данный список можно использовать, например, для отображения доступных дат в календарике формы поиска. Возможно отфильтровать только чартеры, а также можно задать конкретный аэропорт (например, можно получить доступные даты вылета на чартерах из Екатеринбурга в Хургаду).

Authorizations:
ApiKeyAuth
query Parameters
departureId
required
integer

Идентификатор города вылета

countryId
required
integer

Идентификатор страны

arrivalId
integer

Идентификатор города прилёта

onlyCharter
boolean

Признак получения результатов только для чартерных перелётов

Responses

Response samples

Content type
application/json
[
  • "string"
]

Результаты поискового запроса

Метод получения результатов поиска.
Если поиск еще не окончен, то выдаются результаты, найденные на текущий момент.

Authorizations:
ApiKeyAuth
path Parameters
searchId
required
integer

Идентификатор поискового запроса

query Parameters
limit
required
integer
Default: 25

Количество получаемых отелей с турами

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Поиск туров (продолжение)

Метод продолжения поиска.
Используется для получения дополнительных результатов поиска в случае, если туров, найденных за первый (основной) запрос недостаточно. Продолжение поиска идет по идентификатору поискового запроса, который был получен при старте поиска. Можно вызвать несколько раз. При этом каждый раз делаются запросы к операторам, результаты поиска дополняются.
Метод "результаты поискового запроса" выдает полные результаты поиска с учетом всех продолжений (накопительно).

Authorizations:
ApiKeyAuth
path Parameters
searchId
required
integer

Идентификатор поискового запроса

Responses

Response samples

Content type
application/json
{
  • "requestCount": 0
}

Статус поискового запроса

Метод получения статуса выполнения поискового запроса.

Authorizations:
ApiKeyAuth
path Parameters
searchId
required
integer

Идентификатор поискового запроса

query Parameters
operatorStatus
required
boolean
Default: false

Признак отображения расширенного статуса по операторам

Responses

Response samples

Content type
application/json
{
  • "minPrice": 0,
  • "operatorStatus": [
    ],
  • "progress": 0,
  • "searchId": 0,
  • "status": "string",
  • "timePassed": 0
}

tour

Тур

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

Authorizations:
ApiKeyAuth
path Parameters
tourId
required
integer

Идентификатор тура

query Parameters
currency
required
string

ISO-код валюты

Responses

Response samples

Content type
application/json
{
  • "adults": 0,
  • "childs": 0,
  • "currency": "string",
  • "date": "string",
  • "departure": {
    },
  • "flightNights": 0,
  • "flightPlace": 0,
  • "fuelCharge": 0,
  • "hotel": {
    },
  • "hotelDescription": "string",
  • "hotelPlace": 0,
  • "id": "string",
  • "isCharter": true,
  • "isPromo": true,
  • "meal": {
    },
  • "name": "string",
  • "nights": 0,
  • "operator": {
    },
  • "operatorLink": "string",
  • "picture": "string",
  • "placement": "string",
  • "price": 0,
  • "roomId": 0,
  • "roomType": "string"
}

tour-flights

Авиарейсы тура

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

Authorizations:
ApiKeyAuth
path Parameters
tourId
required
integer

Идентификатор тура

query Parameters
currency
required
string

ISO-код валюты

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "flights": [
    ],
  • "info": {
    }
}

tour-hot

Горящие туры

Метод получения горящих туров.

Authorizations:
ApiKeyAuth
query Parameters
departureId
required
integer

Идентификатор города вылета

countryIds
Array of integers

Идентификаторы стран

dateFrom
string
Example: dateFrom=2000-12-31

Начало диапазона дат, на которые выдаются горящие туры

dateTo
string
Example: dateTo=2000-12-31

Конец диапазона дат, на которые выдаются горящие туры (диапазон дат не более 21 дня)

meal
integer

Минимальный тип питания

hotelCategory
integer <= 5

Минимальная категория отеля

noVisa
boolean

Признак получения туров по странам без виз (только для России)

regionIds
Array of integers

Идентификаторы курортов

operatorIds
Array of integers

Идентификаторы операторов

currency
required
string

ISO-код валюты

onlyCharter
required
boolean
Default: false

Признак получения результатов только для чартерных перелётов

limit
required
integer [ 1 .. 200 ]

Количество получаемых горящих туров (от 1 до 200)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

versions

1.1.0

  • Добавление справочника номеров отелей.

1.0.6

  • Добавление параметра для поиска туров только с прямыми перелётами.

1.0.5

  • Добавление ссылки на сайт оператора в детальную информацию о туре.

1.0.4

  • Исправление ошибки при отображении минимальных цен по отелю в результатах поискового запроса.

1.0.3

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

1.0.1

  • Замена параметра тип перелёта на признак наличия чартерных перелётов.
  • Оптимизация метода получения перечня услуг в отелях по группам услуг.
  • Дополнение документации в части поискового запроса.