Routes API

Routes API allows you to build a combined car and public transport route.

Routes API works exactly like Public Transport API, except it uses a car route instead of a pedestrian route (when it is faster) to connect the starting or ending point to different public transport travel options.

Routes API can be used, for example, to build a route that starts with driving to a commuter train station and continues by train.

Getting an access key

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

Request example

To calculate a route, send a POST request to the /combo_routes/2.0 endpoint. Specify your API key as the key parameter in the query string.

https://routing.api.2gis.com/combo_routes/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/combo_routes/2.0?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
  "enable_schedule": true,
  "locale": "ru",
  "source": {
    "name": "A",
    "point": {
      "lat": 55.74791305339228,
      "lon": 37.664326671417626
    }
  },
  "target": {
    "name": "B",
    "point": {
      "lat": 55.65143816549758,
      "lon": 37.559748347634866
    }
  },
  "transport": [
    "bus",
    "trolleybus",
    "tram",
    "shuttle_bus",
    "metro",
    "suburban_train",
    "funicular_railway",
    "monorail",
    "cable_car",
    "aeroexpress",
    "mcd",
    "mcc"
]
}'

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.

Response example

The response will return several travel options for the route. For each travel option, you can get the travel time, the public transport routes used, the number of transfers, and detailed information about each movement within the travel (passage by transport, transition to another station, etc.).

[
    {
      "id": "1",
      "route_id": "123",
      "total_duration": 1772,
      "transfer_count": 0,
      "crossing_count": 0,
      "pedestrian": false,
      "total_walkway_distance": "on foot 19 min",
      "transport": ["bus"],
      "schedules": [...],
      "schedules_events": [...],
      "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

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

List of movements

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 simple route by car and train will consist of five movements:

Drive from the departure point to the train station.
Exit the car and walk to the train station.
Travel several stops by train.
Walk to the destination point.
An additional movement containing only the coordinates of the destination point.

The type of movement (passage by public transport, transfer to a different platform, walking or driving 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": [
    {
        "id": "1",
        "type": "driving", // driving section of the route
        "auto": {
          "distance": 100, // length of the section in meters
          "geometry": "POINT 3.123 4.515"
        }
    },
    {
        "id": "2",
        "type": "walkway", // walking section of the route
        "geometry": {
            "selection": "LINESTRING(37.642032 55.750778, ...",
            "z_first": 0,
            "z_last": 0
        },
        "waypoint": {
            "comment": "290 m on foot",
            "name": "36,149328 51,734588"
        }
    },
    {
        "id": "3",
        "platforms": {...},
        "routes": [...],
        "geometry": {
            "selection": "LINESTRING(37.642032 55.750778, ...",
            "z_first": 0,
            "z_last": 0
        },
        "type": "passage", // passage by public transport
        "waypoint": {
            "subtype": "train", // type of transport
            "name": "Aerodromnaya", // boarding stop name
            "combined": true
        }
    }
]

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.