Public Transport API
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
}
]
}
]