Routes API
Routes API позволяет построить комбинированный маршрут проезда на общественном транспорте и автомобиле.
В отличие от Public Transport API, Routes API соединяет получившиеся варианты проезда на общественном транспорте с точкой отправления или назначения не пешеходным маршрутом, а автомобильным (если остановка находится достаточно далеко).
Routes API может использоваться, например, для построения маршрута, который включает проезд на автомобиле до станции пригородного поезда и дальнейший путь на поезде.
Получение ключа
Для доступа к API нужен специальный ключ. Чтобы его получить, заполните форму по адресу dev.2gis.ru/order.
Пример запроса
Чтобы проложить маршрут, нужно отправить POST-запрос на endpoint /combo_routes/2.0
. В строке запроса укажите ваш ключ API в качестве значения параметра key
.
https://routing.api.2gis.com/combo_routes/2.0?key=YOUR_KEY
Координаты точек маршрута и виды общественного транспорта нужно передать в виде JSON в теле запроса.
Например, чтобы получить варианты комбинированного проезда из точки A в точку B с использованием автобуса или трамвая, можно отправить следующий запрос:
curl --request POST \
--url 'https://routing.api.2gis.com/combo_routes/2.0?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"enable_schedule": true,
"locale": "ru",
"source": {
"name": "A",
"point": {
"lat": 55.74791305339228,
"lon": 37.664326671417626
}
},
"target": {
"name": "B",
"point": {
"lat": 55.65143816549758,
"lon": 37.559748347634866
}
},
"transport": [
"bus",
"trolleybus",
"tram",
"shuttle_bus",
"metro",
"suburban_train",
"funicular_railway",
"monorail",
"cable_car",
"aeroexpress",
"mcd",
"mcc"
]
}'
Параметры source
и target
содержат координаты точек отправления и назначения. Параметр transport
содержит названия видов общественного транспорта, которые будут использованы при построении маршрута.
Полный список поддерживаемых видов транспорта можно посмотреть в Справочнике API.
Пример ответа
Запрос вернет несколько вариантов проезда по маршруту. Для каждого варианта проезда можно получить время в пути, используемые транспортные маршруты, количество пересадок и подробную информацию о каждом перемещении в рамках проезда (путь на транспорте, переход на другую станцию и т.п.).
[
{
"id": "1",
"route_id": "123",
"total_duration": 1772,
"transfer_count": 0,
"crossing_count": 0,
"pedestrian": false,
"total_walkway_distance": "on foot 19 min",
"transport": ["bus"],
"schedules": [...],
"schedules_events": [...],
"movements": [...],
}
]
Продолжительность маршрута
Общее время в пути в секундах для варианта проезда указано в поле ответа total_duration
. Продолжительность пешеходной части указана в виде локализованной строки в поле total_walkway_distance
.
"total_duration": 1772, // общее время в пути составляет около 29 минут
"total_walkway_distance": "on foot 19 min" // из них 19 минут - пешеходный маршрут
Транспортные маршруты и пересадки
В одном варианте проезда может использоваться несколько видов транспорта (в случае пересадок или если один участок маршрута можно проехать на разных видах транспорта). Все используемые виды транспорта перечислены в поле transport
.
"transport": [
"bus", // автобус
"trolleybus", // троллейбус
"tram", // трамвай
"shuttle_bus" // маршрутное такси
]
Количество пересадок, используемых во варианте проезда, указано в двух полях:
transfer_count
- количество пересадок без перехода на другую платформу (остановку);crossing_count
- количество пересадок, для которых нужно перейти на другую платформу.
"transfer_count": 1, // количество пересадок в рамках одной платформы
"crossing_count": 0 // количество переходов с одной платформы на другую
Список перемещений
Общая информация
Каждый вариант проезда разделен на несколько перемещений (участков маршрута). Список перемещений указан в поле movements
.
Например, комбинированный маршрут с использованием пригородного поезда без дополнительных пересадок будет состоять из пяти перемещений:
- Проехать на автомобиле до станции пригородного поезда.
- Выйти из автомобиля и дойти до станции.
- Проехать на поезде несколько остановок.
- Пройти пешком до точки назначения.
- Дополнительное перемещение, содержащее только координаты точки назначения.
Тип перемещения (проезд на общественном транспорте, пересадка или автомобильный/пешеходный участок маршрута) указан в поле type
. Поле waypoint
содержит координаты или название начальной точки перемещения, длину автомобильного/пешеходного участка маршрута и название вида транспорта.
"movements": [
{
"id": "1",
"type": "driving", // автомобильный участок маршрута
"auto": {
"distance": 100, // длина участка маршрута в метрах
"geometry": "POINT 3.123 4.515"
}
},
{
"id": "2",
"type": "walkway", // пешеходный участок маршрута
"geometry": {
"selection": "LINESTRING(37.642032 55.750778, ...",
"z_first": 0,
"z_last": 0
},
"waypoint": {
"comment": "290 m on foot", // пройти 290 метров...
"name": "36,149328 51,734588"
}
},
{
"id": "3",
"platforms": {...},
"routes": [...],
"type": "passage", // проезд на общественном транспорте
"geometry": {
"selection": "LINESTRING(37.642032 55.750778, ...",
"z_first": 0,
"z_last": 0
},
"waypoint": {
"subtype": "train", // вид транспорта
"name": "Аэродромная", // название посадочной остановки
"combined": true
}
}
]
Транспорт и остановки
Для транспортных участков маршрута будут указаны дополнительные поля routes
, platforms
и metro
(в случае метро).
Поле routes
содержит список всех транспортных маршрутов, которые можно использовать для прохождения текущего участка. Например, если текущий участок можно проехать на автобусах №26 и №41 или на маршрутном такси №206, поле routes
будет выглядеть следующим образом:
"routes": [
{
"names": ["26", "41"], // номера маршрутов
"subtype": "bus", // название вида транспорта
"subtype_name": "bus" // локализованное название вида транспорта
},
{
"names": ["206"],
"subtype": "shuttle_bus",
"subtype_name": "shuttle bus"
}
]
Поле platforms
содержит названия всех промежуточных остановок маршрута, т.е. остановок после посадочной и перед остановкой высадки. Последняя остановка в списке - та, после которой нужно выйти.
"platforms": {
"names": [
"Бойцов 9 Дивизии",
"Большевиков (автобус)",
"Магазин Колос",
"50 лет Октября",
"Павлуновского",
"Кинотеатр им.Щепкина"
]
}
Если участок маршрута можно проехать на метро, в поле metro
будет указана информация о линии метро (название, цвет), рекомендованный номер вагона для посадки, подсказки по направлению движения и выходу из метро и другая информация. Полный список полей можно посмотреть в Справочнике API.