Distance Matrix API

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

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

Distance Matrix 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: [55.26553, 25.23399],
    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 `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: 25.16184629215101,
        lon: 55.288509640285845,
    },
    {
        lat: 25.2395871098727,
        lon: 55.340674378221166,
    },
    {
        lat: 25.32097657667498,
        lon: 55.39079344410564,
    },
    {
        lat: 25.32097657667498,
        lon: 55.521205293543126,
    },
];
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: [55.26553, 25.23399],
                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: 25.16184629215101,
                    lon: 55.288509640285845,
                },
                {
                    lat: 25.2395871098727,
                    lon: 55.340674378221166,
                },
                {
                    lat: 25.32097657667498,
                    lon: 55.39079344410564,
                },
                {
                    lat: 25.32097657667498,
                    lon: 55.521205293543126,
                },
            ];

            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>

Получение ключа

Для доступа к API нужен специальный ключ. Чтобы его получить, заполните форму по адресу dev.2gis.ru/order.

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

Чтобы получить информацию о маршруте, нужно отправить POST-запрос на endpoint /get_dist_matrix. В строке запроса укажите ваш ключ API в качестве значения параметра key и параметр version, (по умолчанию 2.0) указывающий на версию API.

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

Координаты точек маршрута и другие параметры нужно передать в виде JSON в теле запроса.

В запросе можно указать несколько точек отправления и несколько точек прибытия. Для каждой указанной точки отправления будет рассчитан маршрут до каждой указанной точки прибытия.

Например, чтобы рассчитать маршруты для двух точек отправления и двух точек прибытия, можно отправить следующий запрос:

curl --request POST \
 --url 'https://catalog.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]
}'

Параметр points содержит массив точек маршрута. Параметры sources и targets определяют, какие из точек массива являются точками отправления и точками прибытия соответственно.

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

Запрос вернет длину маршрута в метрах (distance) и время в пути в секундах (duration) для каждой пары точек отправления-прибытия. В полях source_id и target_id будут указаны индексы точек отправления и прибытия из массива points. Если для конкретной пары точек не удалось построить маршрут, поле status будет содержать строку "FAIL".

Подробную информацию о полях ответа можно посмотреть в Справочнике API.

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

Типы маршрутов

Кратчайший по времени

По умолчанию прокладывается кратчайший по времени автомобильный маршрут с учётом текущих пробок. Чтобы указать тип маршрута явно, нужно добавить в запрос поле type.

{
    "points": [...],
    "type": "jam" // автомобильный маршрут по текущим пробкам
}

Вместо текущих пробок можно использовать статистическую информацию по пробкам. Для этого нужно указать тип маршрута statistics и нужную дату-время в формате RFC 3339 в поле start_time.

{
    "points": [...],
    "type": "statistics", // автомобильный маршрут на основе статистических данных по пробкам...
    "start_time": "2020-05-15T15:52:01Z"    // ...на 15 мая 2020 года, 15:52:01 UTC
}

Кратчайший по расстоянию

Чтобы построить самый короткий маршрут, даже если он не является оптимальным по времени из-за пробок, нужно указать тип shortest.

{
    "points": [...],
    "type": "shortest" // автомобильный маршрут без учёта пробок
}

С учётом полос общественного транспорта

Также можно строить маршруты с учётом полос общественного транспорта (удобно для такси и автобусов). Для этого нужно добавить в запрос поле mode со значением taxi.

{
    "points": [...],
    "mode": "taxi", // автомобильный маршрут, включающий полосы общественного транспорта...
    "type": "shortest" // ...без учёта пробок
}

Пешеходный

Чтобы проложить пешеходный маршрут, нужно указать параметр mode со значением walking.

{
    "points": [...],
    "mode": "walking" // пешеходный маршрут
}

Велосипедный

Чтобы проложить велосипедный маршрут, нужно указать параметр mode со значением bicycle.

{
    "points": [...],
    "mode": "bicycle" // велосипедный маршрут
}

Исключение областей и типов дорог

При построении маршрута можно исключить определенные типы дорог, такие как грунтовые или платные, и указать области, которые будут избегаться. Для этого используются параметры filters и exclude. Подробнее про работу с этими параметрами можно посмотреть в соответствующих разделах Directions API.