Навигация | Distance Matrix API | Обзор | 2GIS Documentation
Distance Matrix API
Личный кабинет

Distance Matrix API

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

Вы можете задать несколько пунктов отправления (начальных точек) и пунктов назначения (конечных точек) и получить расстояние и время в пути между каждой возможной парой точек отправления и назначения. Например, для трёх точек отправления (А, B, C) и трёх точек прибытия (D, E, F) Distance Matrix API рассчитает расстояние и время для девяти вариантов маршрутов: AD, AE, AF, BD, BE, BF, CD, CE, CF.

Таким образом, вы можете использовать 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" />
        <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>

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

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

Чтобы работать с API сервиса, нужно получить ключ доступа:

  1. Зарегистрируйтесь в личном кабинете Platform Manager.
  2. Создайте демо-ключ или купите ключ для доступа к API: см. инструкцию Ключи доступа.

Работать с ключами можно в личном кабинете Platform Manager: подробнее см. в разделе Личный кабинет.

Чтобы получить информацию о маршруте, нужно отправить 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.
  • Расстояние между точками не превышает 2000 км по прямой.

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

Запрос вернет длину маршрута в метрах (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": 1,
            "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 со значением truck.

{
    "points": [...],
    "mode": "truck" // грузовой транспорт
}

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

Например, в ПДД для грузовиков установлены следующие ограничения скорости: 90 км/ч на автомагистралях и 60 км/ч в населённых пунктах. Если установить дополнительное ограничение скорости движения 75 км/ч, то время маршрута будет рассчитываться для скорости не более 75 км/ч на автомагистралях и не более 60 км/ч в населённых пунктах.

Чтобы установить ограничение, нужно указать в поле vehicle_speed_limit ограничение скорости движения в км/ч.

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

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

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

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

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

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

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

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

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

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

Для создания задачи на построение маршрута нужно отправить 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    'https://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).