Directions API

Directions API в экосистеме Mapbox GL JS и платформы Mapbox представляет собой сервис маршрутизации, предназначенный для построения маршрутов между точками, расчёта расстояний, времени в пути и получения пошаговых инструкций. Он интегрируется как с чистыми HTTP-запросами, так и с визуализацией маршрутов на интерактивных картах.

Directions API функционирует как удалённый сервис, принимающий координаты в виде набора точек и возвращающий структурированный маршрут. Основные этапы обработки запроса:

  • получение списка координат (waypoints)
  • выбор транспортного профиля
  • построение маршрута на графе дорог
  • расчёт оптимального пути
  • формирование геометрии маршрута
  • генерация инструкций манёвров

Результат возвращается в формате JSON, где содержатся линии маршрута, сегменты, шаги и метаданные.

Поддерживаемые профили маршрутизации

Directions API поддерживает несколько типов профилей, определяющих поведение алгоритма построения маршрута:

  • driving — автомобильные маршруты
  • walking — пешеходные маршруты
  • cycling — велосипедные маршруты
  • traffic-aware driving — маршруты с учётом пробок (в зависимости от региона и тарифа)

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

Базовый формат запроса

Запрос к Directions API формируется через HTTP GET:

https://api.mapbox.com/directions/v5/mapbox/{profile}/{coordinates}

Пример:

https://api.mapbox.com/directions/v5/mapbox/driving/37.6173,55.7558;30.3141,59.9386
  ?alternatives=true
  &geometries=geojson
  &steps=true
  &access_token=YOUR_ACCESS_TOKEN

Ключевые параметры:

  • profile — тип маршрута
  • coordinates — список координат в формате lon,lat;lon,lat
  • alternatives — возврат альтернативных маршрутов
  • geometries — формат геометрии (geojson, polyline)
  • steps — включение пошаговых инструкций
  • access_token — ключ доступа к API

Структура ответа API

Ответ Directions API представляет собой JSON-объект с массивом маршрутов:

  • routes — список возможных маршрутов
  • waypoints — точки маршрута
  • code — статус выполнения запроса

Каждый маршрут (route) содержит:

  • geometry — линия маршрута
  • distance — длина в метрах
  • duration — время в секундах
  • legs — сегменты маршрута

Структура legs

legs разбивают маршрут между точками и включают:

  • summary — краткое описание
  • steps — пошаговые инструкции

Steps (пошаговые инструкции)

Каждый шаг содержит:

  • instruction — текст манёвра
  • maneuver — тип действия (turn, depart, arrive)
  • distance — расстояние шага
  • duration — время выполнения
  • geometry — геометрия сегмента

Использование Directions API в Mapbox GL JS

В контексте Mapbox GL JS маршруты, полученные через Directions API, обычно отображаются как GeoJSON-слой на карте.

Добавление слоя маршрута

map.on('load', () => {
  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': '#3b9ddd',
      'line-width': 5
    }
  });
});

После получения ответа от API геометрия маршрута подставляется в источник:

const route = response.routes[0].geometry;

map.getSource('route').setData({
  type: 'Feature',
  geometry: route
});

Форматы геометрии маршрута

Directions API поддерживает несколько форматов:

GeoJSON

Используется для прямой интеграции с Mapbox GL JS:

geometries=geojson

Преимущество — отсутствие необходимости декодирования.

Polyline

Компактный формат, требующий декодирования:

geometries=polyline

или

geometries=polyline6

Polyline6 обеспечивает более высокую точность.

Декодирование polyline

При использовании polyline требуется преобразование в координаты:

import polyline from '@mapbox/polyline';

const coords = polyline.decode(encodedString);

После декодирования координаты преобразуются в формат [lon, lat]:

const geojson = {
  type: 'Feature',
  geometry: {
    type: 'LineString',
    coordinates: coords.map(c => [c[1], c[0]])
  }
};

Альтернативные маршруты

При включении параметра alternatives=true API возвращает несколько маршрутов. Это позволяет реализовать выбор маршрута по критериям:

  • минимальное время
  • минимальное расстояние
  • избегание платных дорог
  • альтернативные пути объезда

Пример обработки:

const routes = response.routes;

routes.forEach((route, index) => {
  console.log(index, route.distance, route.duration);
});

Манёвры и навигационные инструкции

Directions API предоставляет структурированные манёвры, которые используются в навигационных интерфейсах:

  • turn left / right
  • go straight
  • roundabout exit
  • merge
  • depart / arrive

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

Оптимизация маршрутов

Directions API поддерживает оптимизацию через дополнительные параметры:

  • waypoint optimization (reorder=true)
  • avoidance rules (tolls, highways, ferries)
  • traffic-based routing

Пример:

&overview=full
&steps=true
&annotations=distance,duration

Параметр annotations добавляет метаданные по сегментам дороги.

Интеграция с пользовательским вводом

Типичный сценарий включает:

  • получение координат через клик по карте
  • геокодирование адресов
  • динамическое обновление маршрута

Пример логики:

map.on('click', (e) => {
  points.push([e.lngLat.lng, e.lngLat.lat]);

  if (points.length >= 2) {
    fetchRoute(points);
  }
});

Работа с асинхронными запросами

Directions API всегда используется асинхронно:

async function fetchRoute(coords) {
  const query = await fetch(url);
  const json = await query.json();
  return json.routes[0];
}

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

Ограничения и особенности

Directions API имеет ряд технических ограничений:

  • максимальное число точек маршрута
  • лимиты на количество запросов
  • зависимость от тарифного плана Mapbox
  • возможные расхождения с реальной дорожной ситуацией

Использование в сложных сценариях

В продвинутых приложениях Directions API используется вместе с:

  • geolocation API для отслеживания пользователя
  • Mapbox Geocoding API для поиска адресов
  • Mapbox Navigation SDK (в мобильных приложениях)

Комбинация этих инструментов позволяет строить полноценные навигационные системы с визуализацией маршрута в Mapbox GL JS.

Оглавление