Distance Matrix API

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

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

Distance Matrix API поддерживает два режима работы:

Расчёт небольшого количества точек (до 25 точек отправления или прибытия) в синхронном режиме. В этом режиме запрос сразу возвращает результат.
Расчёт запросов, содержащих до 1000 точек отправления или прибытия, в асинхронном режиме. В этом режиме запрос возвращает идентификатор задачи, который нужно использовать для периодической проверки готовности результата (см. Расчёт большого количества точек).

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" />
        <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],
                    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://routing.api.2gis.com/get_dist_matrix?key=API_KEY&version=2.0

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

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

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

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]
}'

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

Внимание!

Если количество точек в массиве sources или в массиве targets превышает 25, запрос вернёт ошибку. Для расчёта маршрутов с большим количеством точек нужно использовать асинхронный метод.

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

Запрос вернет длину маршрута в метрах (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.

Формат ответа

По умолчанию, ответы приходят в формате JSON. Чтобы получить ответ в формате Protocol Buffers, укажите параметр response_format=protobuf в строке запроса:

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

Схему формата protobuf можно скачать по ссылке: DistanceMatrix.proto.

Расчёт большого количества точек

⚠ В настоящее время эта функциональность находится в стадии бета-тестирования. Условия использования можно узнать, написав нам на почту api@2gis.ru

При использовании большого количества точек (больше 25 точек отправления или 25 точек прибытия) нужно использовать асинхронный подход:

Создать задачу на построение маршрута.
Периодически проверять статус задачи, пока не завершится расчёт маршрута.
Получить готовый маршрут после завершения задачи.

Создание задачи на построение маршрута

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

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

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

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]
}'

Запрос вернёт информацию о созданной задаче, включая её идентификатор (task_id), который нужно будет использовать для проверки статуса.

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

Проверка статуса задачи

Чтобы проверить статус задачи, нужно отправить GET-запрос на endpoint /async_matrix/result/get_dist_matrix/{task_id}?key=API_KEY, где task_id - это идентификатор созданной задачи.

curl --request GET \
  --url    'http://routing.api.2gis.com/async_matrix/result/get_dist_matrix/TASK_ID?key=API_KEY' \
  --header 'accept: application/json'

Запрос вернёт текущий статус задачи и ссылку на файл с решением, если задача была успешно завершена. Структура файла с решением совпадает со структурой ответа при использовании синхронного запроса.

{
    // Идентификатор задачи.
    "task_id": "TASK_ID",
    // Статус задачи.
    "status": "TASK_DONE",
    // Код ответа.
    "code": 200,
    // Дополнительная информация о статусе задачи.
    "message": "start_time_ms=16516816106601123 calc_time_ms=14419 attract_time=4 build_time=28 points_count=3 source_count=1 target_count=2",
    // Ссылка на файл с решением.
    "result_link": "http://storage_host:port/dm/TASK_ID.response.json"
}

Возможные статусы задачи:

TASK_CREATED - задача создана;
TASK_IN_QUEUE - задача находится в очереди на обработку;
TASK_IN_PROGRESS - задача находится в процессе выполнения;
TASK_DONE - задача успешно завершена;
TASK_CANCELED - задача была отменена (см. поле message).