overview
Public Transport API позволяет построить маршрут проезда на общественном транспорте.
С помощью Public Transport API можно за один вызов получить несколько вариантов проезда на указанных видах общественного транспорта и выбрать из них наиболее подходящий, исходя из общей продолжительности маршрута, количества пересадок, длины пешеходной части маршрута и других параметров.
Получение ключа доступа
Чтобы работать с API сервиса, нужно получить ключ доступа:
- Зарегистрируйтесь в личном кабинете Менеджер Платформы.
- Создайте демо-ключ или купите подписку для доступа к API.
Работать с ключами можно в Менеджере Платформы: подробнее см. в документации личного кабинета.
Пример запроса
Чтобы проложить маршрут, нужно отправить POST-запрос на endpoint /public_transport/2.0. В строке запроса укажите ваш ключ API в качестве значения параметра key.
https://routing.api.2gis.com/public_transport/2.0?key=YOUR_KEY
Координаты точек маршрута и виды общественного транспорта нужно передать в виде JSON в теле запроса.
Например, чтобы получить варианты проезда из точки A в точку B на автобусе или трамвае, отправьте следующий запрос:
curl --request POST \
--url 'https://routing.api.2gis.com/public_transport/2.0?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"locale": "ru",
"source":
{
"name": "Точка А",
"point":
{
"lat": 51.734588,
"lon": 36.149328
}
},
"target":
{
"name": "Точка Б",
"point":
{
"lat": 51.734183,
"lon": 36.176865
}
},
"transport": ["bus", "tram"]
}'
Параметры source и target содержат координаты точек отправления и назначения. Параметр transport содержит названия видов общественного транспорта, которые будут использованы при построении маршрута.
Полный список поддерживаемых видов транспорта можно посмотреть в Справочнике API.
Промежуточные точки
Помимо точек отправления и назначения вы можете указать до 10 промежуточных точек, через которые должен проходить маршрут. Добавьте параметр intermediate_points с координатами и названиями точек. Пример для дополнения запроса выше:
"intermediate_points": [
{
"name": "Промежуточная точка",
"point": {
"lat": 51.745605,
"lon": 36.166322
}
}
],
В теле ответа прохождение этой точки будет помечено комментарием Вы достигли промежуточной точки.
Пример ответа
Запрос вернет несколько вариантов проезда по маршруту (включая полностью пешеходные). Для каждого варианта проезда можно получить время в пути, используемые транспортные маршруты, количество пересадок, полную геометрию варианта проезда и подробную информацию о каждом перемещении в рамках проезда (путь на транспорте, переход на другую станцию и т.п.).
[
{
"id": "1",
"total_distance": 2893,
"total_duration": 2367,
"transfer_count": 1,
"crossing_count": 0,
"pedestrian": false,
"total_walkway_distance": "пешком 9 мин",
"transport": ["bus"],
"waypoints": [
{
"combined": false,
"routes_names": ["55Г"],
"subtype": "bus"
}
],
"movements": [...]
}
]
Продолжительность маршрута
Для каждого варианта проезда указывается общая длина маршрута (total_distance) и общее время в пути (total_duration). Продолжительность пешеходной части указана в виде локализованной строки в поле total_walkway_distance.
"total_distance": 2893 // общая длина маршрута 2893 метра
"total_duration": 2367, // общее время в пути составляет около 40 минут
"total_walkway_distance": "пешком 9 мин" // из них 9 минут - пешеходный маршрут
Продолжительность движения и ожидания на каждом участке маршрута указывается внутри поля movements (см. Список перемещений и геометрия маршрута).
Транспортные маршруты и пересадки
В одном варианте проезда может использоваться несколько видов транспорта (в случае пересадок или если один участок маршрута можно проехать на разных видах транспорта). Все используемые виды транспорта перечислены в поле transport.
"transport": [
"bus", // автобус
"trolleybus", // троллейбус
"tram", // трамвай
"shuttle_bus" // маршрутное такси
]
Список возможных транспортных маршрутов для каждого вида транспорта указан в поле waypoints:
"waypoints": [
{
// номера автобусов
"routes_names": ["26", "41", "58а", "95", "99"],
"subtype": "bus",
"combined": true
},
{
// номера маршрутных такси
"routes_names": ["206", "226", "227", "228", "277", "278", "287"],
"subtype": "shuttle_bus",
"combined": true
}
]
Количество пересадок, используемых во варианте проезда, указано в двух полях:
transfer_count- количество пересадок без перехода на другую платформу (остановку);crossing_count- количество пересадок, для которых нужно перейти на другую платформу.
"transfer_count": 1, // количество пересадок в рамках одной платформы
"crossing_count": 0 // количество переходов с одной платформы на другую
Если маршрут полностью пешеходный, то поле pedestrian будет содержать значение true.
Список перемещений и геометрия маршрута
Общая информация
Каждый вариант проезда разделен на несколько перемещений (участков маршрута). Список перемещений указан в поле movements.
Например, простой автобусный маршрут без пересадок будет состоять из четырех перемещений:
- Дойти от точки отправления до автобусной остановки.
- Проехать на автобусе несколько остановок.
- Пройти пешком до точки назначения.
- Дополнительное перемещение, содержащее только координаты точки назначения.
Длина каждого перемещения указана в поле distance. Тип перемещения (проезд на транспорте, пересадка или пешеходный участок маршрута) указан в поле type. Поля waiting_duration и moving_duration обозначают время ожидания и время перемещения (в секундах) соответственно. Поле waypoint содержит координаты или название начальной точки перемещения, длину пешеходного участка и название вида транспорта.
"movements": [
{
"alternatives": [...],
"id": "2",
"distance": 426, // длина участка маршрута
"moving_duration": 306, // время движения по участку маршрута
"type": "walkway", // пешеходный участок маршрута
"waiting_duration": 0, // для пеших перемещений время ожидания всегда равно нулю
"waypoint": {
"subtype": "start", // начало движения
"comment": "пешком 430 м", // пройти 430 метров...
"name": "Точка A" // ...от точки отправления
}
},
{
"alternatives": [...],
"id": "3",
"distance": 2304,
"moving_duration": 453, // время движения по участку маршрута
"platforms": {...},
"routes": [...],
"type": "passage", // проезд на транспорте
"waiting_duration": 90, // время ожидания транспорта
"waypoint": {
"subtype": "bus", // вид транспорта
"name": "Аэродромная", // название посадочной остановки
"combined": false
}
},
{
"alternatives": [...],
"id": "19",
"distance": 163,
"moving_duration": 147,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "pedestrian",
"comment": "пешком 170 м", // пройти 170 метров...
"name": "Верхняя Луговая" // ...от указанной остановки
}
},
{
"id": "20",
"distance": 0,
"moving_duration": 0,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "pedestrian",
"comment": "Вы достигли промежуточной точки.",
"name": "Промежуточная точка"
}
},
{
"alternatives": [...],
"id": "2",
"distance": 1904,
"moving_duration": 1371,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "start", // начало движения
"comment": "пешком 2 км", // пройти 2 километра...
"name": "Промежуточная точка" // от промежуточной точки
}
},
{
"id": "3",
"distance": 0,
"moving_duration": 0,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "finish", // конец движения
"comment": "Вы на месте!",
"name": "Точка Б" // название точки назначения
}
}
]
Транспорт и остановки
Для транспортных участков маршрута будут указаны дополнительные поля 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.
Геометрия участка маршрута
Геометрию участка маршрута в формате WKT можно получить с помощью поля alternatives.
В общем случае геометрия указана в поле alternatives.geometry в виде линии или набора линий (LINESTRING).
"alternatives": [
{
"geometry": [
{
"selection": "LINESTRING(36.149328 51.734588, 36.149343 51.734574, ...)",
"z_first": 0,
"z_last": 0
}
]
}
]
В случае проезда на транспорте, в поле alternatives.platforms также будут указаны координаты остановок (POINT).
"alternatives": [
{
"geometry": [
{
"selection": "LINESTRING(36.153062 51.735441, 36.154328 51.733844, ...)",
"z_first": 0,
"z_last": 0
}
],
"platforms": [
{
"geometry": "POINT(36.153062 51.735441)",
"id": 5
},
{
"geometry": "POINT(36.155369 51.731910)",
"id": 6
},
{
"geometry": "POINT(36.185592 51.727166)",
"id": 12
}
]
}
]