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": "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"]
}'

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_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", "58a", "95", "99"],
                "subtype": "bus"
            }
        ],
        "movements": [...]
    }
]

Travel duration

The total travel time in seconds for the travel option is specified in the total_duration response field. The duration of the walking part is specified as a localized string in the total_walkway_distance field.

"total_duration": 1772, // total travel time is about 29 minutes
"total_walkway_distance": "on foot 19 min" // 19 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 platform
crossing_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 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",
        "moving_duration": 208, // 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": "290 m on foot", // walk 290 meters...
            "name": "36,149328 51,734588" // ...from the departure point
        }
    },
    {
        "alternatives": [...],
        "id": "3",
        "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": true
        }
    },
    {
        "alternatives": [...],
        "id": "21",
        "moving_duration": 860,
        "type": "walkway",
        "waiting_duration": 0,
        "waypoint": {
            "subtype": "pedestrian",
            "comment": "1,3 km on foot", // walk 1.3 kilometers...
            "name": "Tsentral’nyy rynok" // ...from the specified stop
        }
    },
    {
        "id": "22",
        "moving_duration": 0,
        "type": "walkway",
        "waiting_duration": 0,
        "waypoint": {
            "subtype": "finish", // finishing movement
            "comment": "You have arrived!",
            "name": "36,176865 51,734183" // destination coordinates
        }
    }
]

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
            }
        ]
    }
]