Distance Matrix API

Обзор

Distance Matrix API позволяет получить информацию о времени и расстоянии между точками на карте.

Distance Matrix позволяет вам получить информацию о достижимости конкретных точек, выбрать точки с необходимым временем достижения и реализовать поверх этих данных ваши собственные алгоритмы для решения транспортных задач.

Как это работает

Запросы осуществляются методом POST, все необходимые параметры передаются в формате JSON. Ответы формируются в формате JSON.

В запросе передаются координаты точек. В ответ приходят расстояние между парами точек и время в пути. Все параметры запроса и ответа приведены в Справочнике API.

Этот метод не возвращает геометрии построенных маршрутов, для этого нужно воспользоваться Directions API.

Наведите курсор на метку на карте, чтобы узнать расстояние и время езды до неё на автомобиле от точки отправления.

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

Пример запроса

Данные можно получить с помощью POST-запроса на URL https://catalog.api.2gis.com/get_dist_matrix?key=YOUR_KEY и payload'а с Content-Type application/json.

В запросе используются следующие параметры:

key=YOUR_KEY — ваш ключ API.

{
    "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"
}

Пример ответа

{
    "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
        }
    ]
}

Начало работы

Получите ключ доступа к API. Для этого заполните анкету.
Посмотрите все параметры форматов запроса и ответа.