Directions API в контексте веб-карт представляет собой слой маршрутизации, отвечающий за построение оптимального пути между точками, возврат геометрии маршрута, инструкций для навигации и метаданных о времени и расстоянии. В связке с MapLibre GL JS Directions API не является встроенным компонентом, а подключается через внешние сервисы маршрутизации, такие как OSRM, GraphHopper или коммерческие API, совместимые с форматом GeoJSON и маршрутов.
Типичная схема работы строится вокруг трёх уровней:
1. Клиентский слой (MapLibre GL JS) Отвечает за отображение карты, источников данных (sources) и слоёв (layers). Здесь визуализируется маршрут, точки старта и финиша, а также промежуточные остановки.
2. Сервис маршрутизации (Directions API) Принимает координаты точек и возвращает маршрут в виде:
3. Геопространственный сервер Например:
Запрос обычно включает:
Пример REST-запроса:
GET /route/v1/driving/13.388860,52.517037;13.397634,52.529407?overview=full&geometries=geojsonОтвет возвращается в формате JSON:
{
"routes": [
{
"geometry": {
"type": "LineString",
"coordinates": [
[13.38886, 52.517037],
[13.392, 52.521],
[13.397634, 52.529407]
]
},
"distance": 2300.5,
"duration": 420,
"legs": [
{
"steps": [
{
"name": "Main Street",
"distance": 500,
"maneuver": {
"type": "turn",
"instruction": "Turn right"
}
}
]
}
]
}
]
}Визуализация маршрута в MapLibre GL JS строится через добавление GeoJSON-источника и слоя линии.
map.addSource('route', {
type: 'geojson',
data: {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: []
}
}
});map.addLayer({
id: 'route-line',
type: 'line',
source: 'route',
layout: {
'line-join': 'round',
'line-cap': 'round'
},
paint: {
'line-color': '#3b82f6',
'line-width': 5
}
});После получения ответа от сервиса маршрутизации необходимо обновить GeoJSON источник:
fetch(url)
.then(res => res.json())
.then(data => {
const route = data.routes[0];
map.getSource('route').setData({
type: 'Feature',
geometry: route.geometry
});
});В этой модели MapLibre выступает исключительно как рендерер, а вся логика маршрутизации находится вне клиента.
Directions API поддерживает waypoints, что позволяет строить сложные маршруты.
Пример структуры:
A → B → C → DЗапрос:
/route/v1/driving/A;B;C;DНа клиентской стороне важно:
Некоторые API возвращают несколько вариантов маршрута:
"routes": [
{ "distance": 2300 },
{ "distance": 2500 },
{ "distance": 2700 }
]В MapLibre GL JS это обычно реализуется через несколько GeoJSON источников:
map.addSource('route-alt-1', {...});
map.addSource('route-alt-2', {...});И отображение с разной стилизацией:
Некоторые Directions API возвращают геометрию в виде encoded polyline вместо GeoJSON. В этом случае требуется декодирование.
Алгоритм:
Пример:
const coordinates = decodePolyline(encoded);
map.getSource('route').setData({
type: 'Feature',
geometry: {
type: 'LineString',
coordinates
}
});Directions API часто возвращает массив steps:
Пример структуры:
{
"steps": [
{
"instruction": "Turn left onto Second Street",
"distance": 300,
"maneuver": {
"type": "turn",
"modifier": "left"
}
}
]
}Интеграция с MapLibre GL JS обычно включает:
В интерактивных приложениях маршрут пересчитывается при:
Оптимизация включает:
const controller = new AbortController();
fetch(url, { signal: controller.signal })
.then(res => res.json())
.then(updateRoute);
controller.abort();Directions API обычно поддерживает профили:
Каждый профиль использует разные правила графа:
В MapLibre GL JS профиль влияет только на визуализацию, но не на расчёт маршрута.
Метаданные маршрута используются для UI-слоёв:
Пример:
const route = data.routes[0];
const distanceKm = route.distance / 1000;
const durationMin = route.duration / 60;Эти значения часто отображаются как overlay поверх карты.
MapLibre GL JS позволяет гибко стилизовать линию маршрута:
Пример динамического изменения:
map.setPaintProperty('route-line', 'line-color', [
'interpolate',
['linear'],
['zoom'],
10, '#60a5fa',
15, '#1d4ed8'
]);Для продвинутых сценариев маршрут разбивается на:
Это требует:
Типичные проблемы Directions API:
Обработка:
if (!data.routes || data.routes.length === 0) {
console.error('Route not found');
}При работе с большим количеством маршрутов важно:
Directions API часто комбинируется с GPS-потоком:
Алгоритм:
Вместо публичных API часто разворачиваются собственные серверы:
Это позволяет:
Ключевая особенность интеграции заключается в разделении ответственности:
Это разделение позволяет: