Public Transport API
Public Transport API позволяет построить маршрут проезда на общественном транспорте.
С помощью Public Transport API можно за один вызов получить несколько вариантов проезда на указанных видах общественного транспорта и выбрать из них наиболее подходящий, исходя из общей продолжительности маршрута, количества пересадок, длины пешеходной части маршрута и других параметров.
Получение ключа
Для доступа к API нужен специальный ключ. Чтобы его получить, заполните форму по адресу dev.2gis.ru/order.
Пример запроса
Чтобы проложить маршрут, нужно отправить 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 A",
"point":
{
"lat": 51.734588,
"lon": 36.149328
}
},
"target":
{
"name": "Point B",
"point":
{
"lat": 51.734183,
"lon": 36.176865
}
},
"transport": ["bus", "tram"]
}'
Параметры source
и target
содержат координаты точек отправления и назначения. Параметр transport
содержит названия видов общественного транспорта, которые будут использованы при построении маршрута.
Полный список поддерживаемых видов транспорта можно посмотреть в Справочнике API.
Пример ответа
Запрос вернет несколько вариантов проезда по маршруту (включая полностью пешеходные). Для каждого варианта проезда можно получить время в пути, используемые транспортные маршруты, количество пересадок, полную геометрию варианта проезда и подробную информацию о каждом перемещении в рамках проезда (путь на транспорте, переход на другую станцию и т.п.).
[
{
"id": "1",
"total_duration": 1772,
"transfer_count": 0,
"crossing_count": 0,
"pedestrian": false,
"total_walkway_distance": "on foot 19 min",
"transport": ["bus"],
"waypoints": [
{
"combined": true,
"routes_names": ["26", "41", "58а", "95", "99"],
"subtype": "bus"
}
],
"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" // маршрутное такси
]
Список возможных транспортных маршрутов для каждого вида транспорта указан в поле 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
.
Например, простой автобусный маршрут без пересадок будет состоять из четырех перемещений:
- Дойти от точки отправления до автобусной остановки.
- Проехать на автобусе несколько остановок.
- Пройти пешком до точки назначения.
- Дополнительное перемещение, содержащее только координаты точки назначения.
Тип перемещения (проезд на транспорте, пересадка или пешеходный участок маршрута) указан в поле type
. Поле waypoint
содержит координаты или название начальной точки перемещения, длину пешеходного участка и название вида транспорта.
"movements": [
{
"alternatives": [...],
"id": "2",
"type": "walkway", // пешеходный участок маршрута
"waypoint": {
"subtype": "start", // начальное движение
"comment": "290 m on foot", // пройти 290 метров...
"name": "36,149328 51,734588" // ...от точки отправления
}
},
{
"alternatives": [...],
"id": "3",
"platforms": {...},
"routes": [...],
"type": "passage", // проезд на транспорте
"waypoint": {
"subtype": "bus", // вид транспорта
"name": "Аэродромная", // название посадочной остановки
"combined": true
}
},
{
"alternatives": [...],
"id": "21",
"type": "walkway",
"waypoint": {
"subtype": "pedestrian",
"comment": "1,3 km on foot", // пройти 1.3 километра...
"name": "Центральный рынок" // ...от указанной остановки
}
},
{
"id": "22",
"type": "walkway",
"waypoint": {
"subtype": "finish", // конечное движение
"comment": "You have arrived!",
"name": "36,176865 51,734183" // координаты точки назначения
}
}
]
Транспорт и остановки
Для транспортных участков маршрута будут указаны дополнительные поля 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
}
],
}
]