Navigation | Pairs Directions API | Overview | 2GIS Documentation

Pairs Directions API

Directions Pairs API allows you to calculate multiple routes in a single call. For each route you can get its length, travel time, and geometry.

Each route can only consist of two points: departure and arrival. You can calculate pedestrian and car routes, taking into account public transport lanes and traffic situation. Additionally, you can specify the road filter to avoid, for example, all dirt roads when calculating a route.

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

To get route information, send a POST request to the /get_pairs/1.0/{routing_type} endpoint, where routing_type is the required type of route:

  • car - car route
  • taxi - car route, including public transport lanes
  • pedestrian - pedestrian route

Specify your API key as the value of the key parameter in the query string.

https://catalog.api.2gis.com/get_pairs/1.0/car?key=API_KEY

Coordinates of route points and all other parameters should be sent as a JSON string in the request body.

In the simplest case, the JSON object may contain only three fields:

  • points - array of routes. Each object in the array must contain four fields: the latitude and longitude of the point of departure (lat1 and lon1) and the latitude and longitude of the point of arrival (lat2 and lon2).
  • type - route type (the optimal route taking traffic into consideration or just the shortest route between the points).
  • output - output format (simplified or full).
{
    "points": [
        {
            "lon1": 82.933328,
            "lat1": 55.102268,
            "lon2": 82.958722,
            "lat2": 55.032594
        }
    ],
    "type": "jam",
    "output": "simple"
}

In this case, the server will return brief information about a single car route taking into account the current traffic situation. The response will include the length of that route in meters (distance) and estimated travel time in seconds (duration).

[
    {
        "lon1": 82.933328,
        "lat1": 55.102268,
        "lon2": 82.958722,
        "lat2": 55.032594,
        "distance": 11146,
        "duration": 1509,
        "status": "OK"
    }
]

As a more complex example, we can change the output format to full, specify multiple routes, and use two optional fields: filters to avoid certain types of roads and utc, which is a Unix time that will be used instead of the current date and time to determine the status of traffic.

{
    "points": [
        {
            "lon1": 82.933328,
            "lat1": 55.102268,
            "lon2": 82.958722,
            "lat2": 55.032594
        },
        {
            "lon1": 82.92952,
            "lat1": 55.079794,
            "lon2": 82.907189,
            "lat2": 54.981836
        }
    ],
    "type": "statistics",
    "output": "full",
    "filters": ["dirt_road"],
    "utc": 1606826131
}

In addition to the length and travel time, the server will return the geometry of each route (the route field). When calculating each route, the server will try to avoid dirt roads ("filters": ["dirt_road"]) and will use statistical data for the specified period instead of the current traffic situation ("type": "statistics" and "utc": 1606826131).

[
    {
        "lon1": 82.933328,
        "lat1": 55.102268,
        "lon2": 82.958722,
        "lat2": 55.032594,
        "distance": 11146,
        "duration": 1509,
        "route": {...},
        "status": "OK"
    },
    {
        "lon1": 82.92952,
        "lat1": 55.079794,
        "lon2": 82.907189,
        "lat2": 54.981836,
        "distance": 13712,
        "duration": 1708,
        "route": {...},
        "status": "OK"
    }
]

When the jam and statistics route types are calculated, the main priority is to minimize the travel time. If you need to calculate the shortest route between two points, no matter how long it would take because of traffic, use the shortest route type. The estimated travel time (the duration field) will include expected traffic congestion regardless of the chosen route type.

For more information about the fields and possible values, see API Reference.