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.

Например, простой автобусный маршрут без пересадок будет состоять из четырех перемещений:

1. Дойти от точки отправления до автобусной остановки.
2. Проехать на автобусе несколько остановок.
3. Пройти пешком до точки назначения.
4. Дополнительное перемещение, содержащее только координаты точки назначения.

Тип перемещения (проезд на транспорте, пересадка или пешеходный участок маршрута) указан в поле 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
            }
        ],
    }
]