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 возвращает только краткую информацию о маршруте (расстояние и время). Для получения полной геометрии маршрута используйте Routing 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],
                    transport: '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 сервиса, нужно получить ключ доступа:

Зарегистрируйтесь в личном кабинете Менеджер Платформы.
Создайте демо-ключ или купите ключ для доступа к API: см. инструкцию Ключи доступа.

Важно

При отправке запросов к Distance Matrix API оплачивается количество не запросов, а расчётов для каждой пары точек отправления и прибытия. Например, в одном запросе вы указываете 2 точки отправления и 3 точки прибытия, поэтому оплачиваются 6 расчётов.

Работать с ключами можно в Менеджере Платформы: подробнее см. в документации личного кабинета.

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

Чтобы получить информацию о маршруте, отправьте 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
        }
    ]
}

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

По умолчанию ответы имеют формат 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.

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

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

По умолчанию прокладывается кратчайший по времени автомобильный маршрут с учётом текущих пробок. Чтобы указать тип маршрута явно, добавьте в запрос поле 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"
}

Для грузового транспорта

Чтобы построить маршрут для грузового транспорта, укажите параметр transport со значением truck:

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

Дополнительное ограничение скорости движения

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

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

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

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

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

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

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

Пешеходный

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

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

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

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

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

Самокатный

Чтобы построить самокатный маршрут, укажите параметр transport со значением scooter:

{
    "points": [...],
    "transport": "scooter" // самокатный маршрут
}

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

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

Высота маршрута

Чтобы получить в ответе информацию о высоте пешеходного или велосипедного маршрута, добавьте в запрос поле need_altitudes со значением true:

{
    "points": [...],
    "transport": "walking", //или "transport": "bicycle"
    "need_altitudes": true
}

Пример ответа с информацией о высоте маршрута:

{
    "routes": [
        {
            ...
            "altitudes_info": {
                "elevation_gain": 0,
                "elevation_loss": 0,
                "max_altitude": 0,
                "min_altitude": 0,
                "max_road_angle": 0
                }
        },
        ...
    ]
}

Где:

elevation_gain — суммарное увеличение высоты в см;
elevation_loss — суммарное снижение высоты в см;
max_altitude — максимальная высота над уровнем моря в см;
min_altitude — минимальная высота над уровнем в см;
max_road_angle — максимальный угол наклона.

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

При использовании большого количества точек (больше 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 — идентификатор задачи;
key — ваш ключ API.

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).