Navigation | Distance Matrix API | Overview | 2GIS Documentation
Distance Matrix API
Maps
Search
Navigation
Urbi Pro
CityLens
Account
On‑Premise

Distance Matrix API

Distance Matrix API allows you to get information about travel time and distance between points on the map.

You can specify multiple starting and ending points and get distance and travel time between each possible pair of starting and ending points. For example, for three starting points (A, B, C) and three ending points (D, E, F), Distance Matrix API calculates distance and travel time of nine route options: AD, AE, AF, BD, BE, BF, CD, CE, CF.

Thus, you can use Distance Matrix API to determine the most effective routes of traveling between multiple staring and ending points and implement your own algorithms for solving routing problems.

Distance Matrix API returns only brief information about the route (distance and travel time). To get the full geometry of a route, use Routing API.

Move your mouse over a marker on the map to find out the distance and driving time to it.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Distance matrix API</title>
        <meta name="description" content="Several destination points example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            #tooltip {
                padding: 12px 16px;
                background: #fff;
                box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.2);
                border-radius: 4px;
                display: none;
                position: fixed;
                pointer-events: none;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <div id="tooltip"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const reqUrl = `https://routing.api.2gis.com/get_dist_matrix?key=Your directions API access key&version=2.0`;

            const map = new mapgl.Map('container', {
                center: [37.668598, 55.76259],
                zoom: 10,
                key: 'Your API access key',
            });

            function renderMarkersWithData(routes) {
                function generateTooltipText(index) {
                    const data = routes.find((item) => item.target_id === index);
                    if (!data) return undefined;
                    return `distance: ${data.distance.toLocaleString()} m.<br>by car: ${Math.round(
                        data.duration / 60,
                    )} min.`;
                }
                const tooltipEl = document.getElementById('tooltip');

                const startPoint = points.shift();
                const marker = new mapgl.Marker(map, {
                    coordinates: [startPoint.lon, startPoint.lat],
                    label: {
                        text: 'Point of departure',
                        fontSize: 13,
                    },
                });

                points.forEach((point, index) => {
                    const marker = new mapgl.Marker(map, {
                        coordinates: [point.lon, point.lat],
                        icon: 'https://docs.2gis.com/img/dotMarker.svg',
                    });
                    marker.on('mouseover', (event) => {
                        // Offset in pixels
                        const offset = 5;
                        tooltipEl.style.top = `${event.point[1] + offset}px`;
                        tooltipEl.style.left = `${event.point[0] + offset}px`;
                        tooltipEl.innerHTML = generateTooltipText(index + 1);
                        tooltipEl.style.display = 'block';
                    });
                    marker.on('mouseout', (e) => {
                        tooltipEl.style.display = 'none';
                    });
                });
            }

            const points = [
                {
                    lat: 55.716226,
                    lon: 37.729171,
                },
                {
                    lat: 55.723976,
                    lon: 37.624403,
                },
                {
                    lat: 55.71893,
                    lon: 37.564967,
                },
                {
                    lat: 55.730375,
                    lon: 37.483024,
                },
            ];

            fetch(reqUrl, {
                method: 'POST',
                body: JSON.stringify({
                    points,
                    sources: [0],
                    targets: [1, 2, 3],
                    transport: 'driving',
                    start_time: new Date().toISOString(),
                }),
            })
                .then((res) => res.json())
                .then((parsed) => renderMarkersWithData(parsed.routes))
                .catch((err) => console.error('error', err));
        </script>
    </body>
</html>

Distance Matrix API supports two modes of operation:

  • Calculating requests that contain up to 25 starting or ending points in synchronous mode. In this mode, the request returns the result of calculation.
  • Calculating requests that contain up to 1000 starting or ending points in asynchronous mode. In this mode, the request returns the task ID, which should be used to periodically check if the calculation is complete (see Large number of points).

Getting an access key

To work with the API of the service, you need to get an access key:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase an access key for using API: see the Access keys instruction.

Important

When you send requests to the Distance Matrix API, calculations for each pair of starting and ending points are charged, not the number of requests. For example, in one request, you specify 2 starting points and 3 ending points, so that 6 calculations are charged.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

Request example

To get the information about a route, send a POST request to the /get_dist_matrix endpoint. Specify your API key as the key parameter in the query string and the required API version as the version parameter (2.0 by default):

https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0

Pass coordinates for the route and other parameters as a JSON string in the request body.

You can specify several starting and end points in the request body. For each specified starting point, a route is built to each specified end point.

For example, to build routes for two starting points and two end points, send the following request:

curl --request POST \
 --url 'https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0' \
 --header 'Content-Type: application/json' \
 --data '{
    "points": [
        {
            "lat": 54.99770587584445,
            "lon": 82.79502868652345
        },
        {
            "lat": 54.99928130973027,
            "lon": 82.92137145996095
        },
        {
            "lat": 55.04533538802211,
            "lon": 82.98179626464844
        },
        {
            "lat": 55.072470687600536,
            "lon": 83.04634094238281
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}'

The points parameter is an array of route points. The sources and targets parameters are arrays of indices that determine which points of the points array are starting and end points, respectively.

Important

This query works with the following restrictions:

  • The number of points in the sources array or in the targets array does not exceed 25.
  • The distance between points does not exceed 2000 km in a straight line.

If at least one of these restrictions is not satisfied, the request will return an error. To make requests with this input data, use the asynchronous method.

Response example

For each pair of starting and ending points, the request will return route information including the route length in meters (distance) and travel time in seconds (duration). The point indices from the points array will be specified in the source_id and target_id fields. If a route could not be built for a particular pair of points, the status field will contain the string "FAIL".

More detailed information about response fields can be found in API Reference.

{
    "generation_time": 3349,
    "routes": [
        {
            "distance": 11287,
            "duration": 1319,
            "source_id": 0,
            "status": "OK",
            "target_id": 2
        },
        {
            "distance": 3839,
            "duration": 603,
            "source_id": 0,
            "status": "OK",
            "target_id": 3
        },
        {
            "distance": 12245,
            "duration": 1094,
            "source_id": 1,
            "status": "OK",
            "target_id": 2
        },
        {
            "distance": 11418,
            "duration": 931,
            "source_id": 1,
            "status": "OK",
            "target_id": 3
        }
    ]
}

Response format

By default, responses are in the JSON format. To get a response in the Protocol Buffers format, specify the response_format=protobuf parameter in the query string:

https://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0&response_format=protobuf

A schema of the protobuf format is available at DistanceMatrix.proto.

Route types

Shortest route in time

By default, the server returns the shortest car route in time using current traffic data. To build a specific type of route, specify the type parameter in the request:

{
    "points": [...],
    "type": "jam" // car route using current traffic data
}

Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the statistics route type and the required date and time in RFC 3339 format as the start_time parameter:

{
    "points": [...],
    "type": "statistics", // car route using statistical traffic data...
    "start_time": "2020-05-15T15:52:01Z"    // ...as of 15 May 2020, 15:52:01 UTC
}

Shortest route in distance

To build the shortest route in distance, even if it is not the fastest one, specify the shortest route type:

{
    "points": [...],
    "type": "shortest"
}

Cargo route

To build a cargo route, specify the transport parameter with the value truck:

{
    "points": [...],
    "transport": "truck" // cargo transport
}

Additional speed limit

By default, routes are built considering the speed limits set by the driving regulations. You can set a speed value, which the vehicle must not exceed on any road part.

For example, the speed limits set by the driving regulations for trucks are 80 km/h on highways and 40 km/h in residential areas. If you set the 75 km/h speed limit, the route time is calculated for the following speeds: no more than 75 km/h on highways and no more than 40 km/h in residential areas.

To set a limit, specify the speed limit in km/h in the vehicle_speed_limit field:

{
    "points": [...],
    "transport": "truck",
    "vehicle_speed_limit": 75
}

Public transport lanes

You can also include public transport lanes when building a car route, which can be useful for taxi and bus routes. To do this, specify the transport parameter with the value taxi in the request:

{
    "points": [...],
    "transport": "taxi", // car route including public transport lanes
    "type": "shortest" // shortest in distance
}

Pedestrian route

To build a pedestrian route, specify the transport parameter with the value walking:

{
    "points": [...],
    "transport": "walking" // pedestrian route
}

Bicycle route

To build a bicycle route, specify the transport parameter with the value bicycle:

{
    "points": [...],
    "transport": "bicycle" // bicycle route
}

Scooter route

To build a scooter route, specify the transport parameter with the value scooter:

{
    "points": [...],
    "transport": "scooter" // scooter route
}

Avoiding areas and road types

When building a route, you can exclude certain types of roads, such as toll roads or dirt roads, using the filters parameter, and exclude specific areas using the exclude parameter. For more information on using these parameters, see the corresponding sections of Routing API.

Route altitude

To get the altitude information for a pedestrian or bicycle route in the response, specify the need_altitudes parameter with the value true in the request:

{
    "points": [...],
    "transport": "walking", //or "transport": "bicycle"
    "need_altitudes": true
}

Response example with the information on a route altitude:

{
    "routes": [
        {
            ...
            "altitudes_info": {
                "elevation_gain": 0,
                "elevation_loss": 0,
                "max_altitude": 0,
                "min_altitude": 0,
                "max_road_angle": 0
                }
        },
        ...
    ]
}

Where:

  • elevation_gain - total elevation gain in cm.
  • elevation_loss - total elevation loss in cm.
  • max_altitude - maximum height above mean sea level in cm.
  • min_altitude - minimum height above mean sea level in cm.
  • max_road_angle - maximum tilt angle.

Large number of points

When using a large number of starting or ending points (more than 25), you need to use the asynchronous approach:

  1. Create a route building task.
  2. Periodically check the status of the task until the route calculation is complete.
  3. Get the calculated route when the task is complete.

Creating a route building task

To create a task, send a POST request to the /async_matrix/create_task/get_dist_matrix endpoint. Specify your API key as the key parameter in the query string and the required API version as the version parameter (2.0 by default):

https://routing.api.2gis.com/async_matrix/create_task/get_dist_matrix?key=API_KEY&version=2.0

Pass coordinates for the route and other parameters as a JSON string in the request body.

For example, to build routes for two starting points and two end points, send the following request:

curl --request POST \
 --url 'https://routing.api.2gis.com/async_matrix/create_task/get_dist_matrix?key=API_KEY&version=2.0' \
 --header 'Content-Type: application/json' \
 --data '{
    "points": [
        {
            "lat": 54.99770587584445,
            "lon": 82.79502868652345
        },
        {
            "lat": 54.99928130973027,
            "lon": 82.92137145996095
        },
        {
            "lat": 55.04533538802211,
            "lon": 82.98179626464844
        },
        {
            "lat": 55.072470687600536,
            "lon": 83.04634094238281
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}'

The request will return information about the created task, including the task identifier (task_id), which is used to check the task status:

{
    "task_id": "TASK_ID",
    "status ": "TASK_CREATED"
}

Check task status

To check the status of the task, send a GET request to the /async_matrix/result/get_dist_matrix/{task_id}?key=API_KEY endpoint. Specify two parameters in the query string:

  • task_id - task ID
  • key - your API key
curl --request GET \
  --url    'https://routing.api.2gis.com/async_matrix/result/get_dist_matrix/TASK_ID?key=API_KEY' \
  --header 'accept: application/json'

The request will return the current status of the task and a link to the solution file if the task has been completed successfully. The structure of the solution file is identical to the structure of a response to a synchronous request:

{
    // Task identifier.
    "task_id": "TASK_ID",
    // Task status.
    "status": "TASK_DONE",
    // Status code.
    "code": 200,
    // Additional information about the task status.
    "message": "start_time_ms=16516816106601123 calc_time_ms=14419 attract_time=4 build_time=28 points_count=3 source_count=1 target_count=2",
    // Link to the solution file.
    "result_link": "http://storage_host:port/dm/TASK_ID.response.json"
}

Tasks can have the following statuses:

  • TASK_CREATED - task has been created.
  • TASK_IN_QUEUE - task is in a queue, waiting to be processed.
  • TASK_IN_PROGRESS - task is being processed.
  • TASK_DONE - task was completed.
  • TASK_CANCELED - task was cancelled (see the message field for more details).