Navigation | Public Transport API | Overview | 2GIS Documentation

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.

Usage of this API requires an API key. To obtain the key, fill out the form at dev.2gis.com/order.

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://catalog.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://catalog.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.

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

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

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.

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:

  1. Walk from the point of departure to the bus stop.
  2. Take the bus for several stops.
  3. Walk to the destination.
  4. 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 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",
        "type": "walkway", // walking section of the route
        "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",
        "platforms": {...},
        "routes": [...],
        "type": "passage", // passage by transport
        "waypoint": {
            "subtype": "bus", // type of transport
            "name": "Aerodromnaya", // boarding stop name
            "combined": true
        }
    },
    {
        "alternatives": [...],
        "id": "21",
        "type": "walkway",
        "waypoint": {
            "subtype": "pedestrian",
            "comment": "1,3 km on foot", // walk 1.3 kilometers...
            "name": "Tsentral’nyy rynok" // ...from the specified stop
        }
    },
    {
        "id": "22",
        "type": "walkway",
        "waypoint": {
            "subtype": "finish", // finishing movement
            "comment": "You have arrived!",
            "name": "36,176865 51,734183" // destination coordinates
        }
    }
]

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.

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