Distance Matrix API

Overview

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

The Distance Matrix gives you information about the reachability of certain points and allows you to choose the points with the required time to reach. You can use this data to implement your own algorithms for solving routing problems.

How It Works

Requests are made using the POST method, all required parameters should be passed in the JSON format. The responses are also generated in the JSON format.

The request takes the coordinates of the points. You will get the distances between the pairs of points and the travel time in response. You can view all request and response parameters in the API Reference.

This method does not return the geometry of the routes. In order to obtain it, use the Directions API.

Move your mouse over a marker on the map to learn the distance and the 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">
    </head>
    <body>
        <div id="container"></div>
        <div id="tooltip"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
    </body>
</html>

// API key can be used on jsfiddle.net only!
// You can get more info on https://docs.2gis.com/

const reqUrl = `https://catalog.api.2gis.com/get_dist_matrix?key=rubfpx2151`;
const map = new mapgl.Map('container', {
    center: [82.795, 55.04],
    zoom: 10,
    key: 'bfd8bbca-8abf-11ea-b033-5fa57aae2de7',
});
function renderMarkersWithData(routes) {
    function generateTooltipText(index) {
        const data = routes.find((item) => item.target_id === index);
        if (!data) return undefined;
        return `расстояние: ${data.distance.toLocaleString()} м.<br>ехать на машине: ${Math.round(
            data.duration / 60,
        )} мин.`;
    }
    const tooltipEl = document.getElementById('tooltip');
    const startPoint = points.shift();
    const marker = new mapgl.Marker(map, {
        coordinates: [startPoint.lon, startPoint.lat],
        label: {
            text: 'Точка отправления',
            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: 54.99770587584445,
        lon: 82.79502868652345,
    },
    {
        lat: 54.99928130973027,
        lon: 82.92137145996095,
    },
    {
        lat: 55.04533538802211,
        lon: 82.98179626464844,
    },
    {
        lat: 55.072470687600536,
        lon: 83.04634094238281,
    },
];
fetch(reqUrl, {
    method: 'POST',
    body: JSON.stringify({
        points,
        sources: [0],
        targets: [1, 2, 3],
        mode: 'driving',
        start_time: new Date().toISOString(),
    }),
})
    .then((res) => res.json())
    .then((parsed) => renderMarkersWithData(parsed.routes))
    .catch((err) => console.error('error', err));

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

<!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://catalog.api.2gis.com/get_dist_matrix?key=Your directions API access key`;

            const map = new mapgl.Map('container', {
                center: [82.795, 55.04],
                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 `расстояние: ${data.distance.toLocaleString()} м.<br>ехать на машине: ${Math.round(
                        data.duration / 60,
                    )} мин.`;
                }
                const tooltipEl = document.getElementById('tooltip');

                const startPoint = points.shift();
                const marker = new mapgl.Marker(map, {
                    coordinates: [startPoint.lon, startPoint.lat],
                    label: {
                        text: 'Точка отправления',
                        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: 54.99770587584445,
                    lon: 82.79502868652345,
                },
                {
                    lat: 54.99928130973027,
                    lon: 82.92137145996095,
                },
                {
                    lat: 55.04533538802211,
                    lon: 82.98179626464844,
                },
                {
                    lat: 55.072470687600536,
                    lon: 83.04634094238281,
                },
            ];

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

Example of Request

To retrieve the data, make a POST request to https://catalog.api.2gis.com/get_dist_matrix?key=YOUR_KEY with Content-Type application/json.

The request takes the following parameters:

key=YOUR_KEY — your API key

{
    "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],
    "start_time": "2020-04-26T07:05:30Z"
}

Example of Response

{
    "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": 0,
            "status": "OK",
            "target_id": 3
        }
    ]
}

Getting Started

To get your key, fill in the application form.
Learn about the request and response formats.