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 сервиса, нужно получить ключ доступа:
- Зарегистрируйтесь в личном кабинете Platform Manager.
- Создайте демо-ключ или купите ключ для доступа к 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 точек прибытия) нужно использовать асинхронный подход:
- Создать задачу на построение маршрута.
- Периодически проверять статус задачи, пока не завершится расчёт маршрута.
- Получить готовый маршрут после завершения задачи.
Создание задачи на построение маршрута
Для создания задачи на построение маршрута нужно отправить 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
).