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" />
<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&version=2.0`;
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.