Public Transport API
Public Transport API allows you to build a route for public transport.
In one call to Public Transport API, you can get several options for travel on the specified types of public transport and then choose the most suitable one based on the total route duration, the number of transfers, the length of the pedestrian part of the route, and other parameters.
Getting an access key
To work with the API of the service, you need to get an access key:
- Sign in to the Platform Manager.
- Create a demo key or purchase an access key for using API: see the Access keys instruction.
To work with access keys, you can use the Platform Manager: see the Platform Manager section.
Request example
To calculate a route, send a POST request to the /public_transport/2.0 endpoint. Specify your API key as the key parameter in the query string.
https://routing.api.2gis.com/public_transport/2.0?key=YOUR_KEY
Route points coordinates and public transport types must be sent as a JSON string in the request body.
For example, to get travel options from point A to point B by bus or tram, you can send a request similar to the following:
curl --request POST \
--url 'https://routing.api.2gis.com/public_transport/2.0?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"locale": "en",
"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"]
}'
The source and target parameters contain the coordinates of the starting and ending route points. The transport parameter contains the names of public transport types that will be used when building the route.
For a complete list of supported transport types, see API Reference.
Intermediate points
In addition to the starting and ending route points, you can specify up to 10 intermediate points that the route must pass through. Add the intermediate_points parameter with points coordinates and names. Example for extending the request above:
"intermediate_points": [
{
"name": "Intermediate point",
"point": {
"lat": 51.745605,
"lon": 36.166322
}
}
],
In the response body, passing this point is labelled with the comment: You have reached an intermediate point.
Response example
The response will return several travel options for the route (including completely pedestrian). For each travel option, you can get the travel time, the public transport routes used, the number of transfers, the complete geometry of the travel option and detailed information about each movement within the travel (passage by transport, transition to another station, etc.).
[
{
"id": "1",
"total_distance": 2893,
"total_duration": 2367,
"transfer_count": 1,
"crossing_count": 0,
"pedestrian": false,
"total_walkway_distance": "on foot 9 min",
"transport": ["bus"],
"waypoints": [
{
"combined": false,
"routes_names": ["55"],
"subtype": "bus"
}
],
"movements": [...]
}
]
Travel duration
For each travel option, the total route length (total_distance) and the total travel time (total_duration) are specified. The duration of the walking part is specified as a localized string in the total_walkway_distance field.
"total_distance": 2893, // total route length is 2893 meters
"total_duration": 2367, // total travel time is about 40 minutes
"total_walkway_distance": "on foot 9 min" // 9 minutes of which is a walking route
Duration of moving and waiting for each route section is specified inside the movements response field (see List of movements and route geometry).
Transport routes and transfers
A travel option can include several types of transport (in case of transfers or if different types of transport can be used on the same route section). All used types of transport are listed in the transport field.
"transport": ["bus", "trolleybus", "tram", "shuttle_bus"]
The list of possible transport routes for each type of transport is specified in the waypoints field:
"waypoints": [
{
// bus numbers
"routes_names": ["26", "41", "58a", "95", "99"],
"subtype": "bus",
"combined": true
},
{
// shuttle bus numbers
"routes_names": ["206", "226", "227", "228", "277", "278", "287"],
"subtype": "shuttle_bus",
"combined": true
}
]
The number of transfers used in the travel option is specified in two fields:
transfer_count- number of transfers without changing the platformcrossing_count- number of transfers that require walking to another platform
"transfer_count": 1,
"crossing_count": 0
If the travel option is completely pedestrian, the pedestrian field will contain the value true.
List of movements and route geometry
General information
Each travel option is divided into several movements (route sections). The list of movements is specified in the movements field.
For example, a direct bus route has four movements:
- Walk from the point of departure to the bus stop.
- Take the bus for several stops.
- Walk to the destination.
- An additional movement containing only the coordinates of the destination point.
The distance traveled during each movement is specified in the distance field. The type of movement (passage by transport, transfer to a different platform, or walking section of the route) is specified in the type field. The waiting_duration and moving_duration fields specify the waiting time and moving time (in seconds) respectively. The waypoint field contains the name or coordinates of the starting point of movement, the duration of the walking part, and the type of transport used.
"movements": [
{
"alternatives": [...],
"id": "2",
"distance": 426, // distance of the route section
"moving_duration": 306, // duration of moving along the route section
"type": "walkway", // walking section of the route
"waiting_duration": 0, // always equals zero for walking sections
"waypoint": {
"subtype": "start", // starting movement
"comment": "430 m on foot", // walk 430 meters...
"name": "Point A" // ...from the departure point
}
},
{
"alternatives": [...],
"id": "3",
"distance": 2304,
"moving_duration": 412, // duration of moving along the route section
"platforms": {...},
"routes": [...],
"type": "passage", // passage by transport
"waiting_duration": 90, // duration of waiting for the transport
"waypoint": {
"subtype": "bus", // type of transport
"name": "Aerodromnaya", // boarding stop name
"combined": false
}
},
{
"alternatives": [...],
"id": "19",
"distance": 163,
"moving_duration": 147,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "pedestrian",
"comment": "170 m on foot", // walk 170 meters...
"name": "Verhnaya Lugovaya" // ...from the specified stop
}
},
{
"id": "20",
"distance": 0,
"moving_duration": 0,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "pedestrian",
"comment": "You have reached an intermediate point.",
"name": "Intermediate point"
}
},
{
"alternatives": [...],
"id": "2",
"distance": 1904,
"moving_duration": 1371,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "start", // starting movement
"comment": "2 km on foot", // walk 2 kilometers...
"name": "Intermediate point" // from the intermediate point
}
},
{
"id": "3",
"distance": 0,
"moving_duration": 0,
"type": "walkway",
"waiting_duration": 0,
"waypoint": {
"subtype": "finish", // finishing movement
"comment": "You have arrived!",
"name": "Point B" // destination point name
}
}
]
Transport and stops
For transport sections of the route, additional fields are specified: routes, platforms, and metro (in case of travel by metro).
The routes field contains a list of all transport routes that can be used to travel the current section. For example, if the current section can be traveled by buses #26 and #41 or by shuttle bus #206, the routes field will look like this:
"routes": [
{
"names": ["26", "41"], // route names
"subtype": "bus", // type of transport
"subtype_name": "bus" // localized name for the transport type
},
{
"names": ["206"],
"subtype": "shuttle_bus",
"subtype_name": "shuttle bus"
}
]
The platforms field contains the names of all intermediate stops on the route, i.e. those that are after the boarding stop and before the alighting stop. The last stop on the list is the one after which you need to get off.
"platforms": {
"names": [
"Boytsov 9 Divizii",
"Bol’shevikov (bus)",
"Magazin Kolos",
"50 let Oktyabrya",
"Pavlunovskogo",
"Kinoteatr im.Shchepkina"
]
}
If a route section can be traveled by metro, the metro field will contain information about the metro line (name, color), the train car number recommended for boarding, tips on the direction of movement and exiting the metro, and other information. For a complete list of fields, see API Reference.
Route section geometry
You can get the geometry of a route section in WKT format using the alternatives field.
In general, the geometry is specified in the alternatives.geometry field as a line or a set of lines (LINESTRING).
"alternatives": [
{
"geometry": [
{
"selection": "LINESTRING(36.149328 51.734588, 36.149343 51.734574, ...)",
"z_first": 0,
"z_last": 0
}
]
}
]
If the route section uses transport, the coordinates of stops will be listed in the alternatives.platforms field (as 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
}
]
}
]