Directions Service

Directions Service представляет собой компонент Google Maps JavaScript API, предназначенный для построения маршрутов между точками, вычисления расстояний и времени в пути с учётом различных транспортных режимов, дорожных условий и промежуточных точек. Он работает в связке с серверной частью Google Maps Platform, которая обрабатывает запросы маршрутизации и возвращает структурированный результат, пригодный для отображения на карте или дальнейшей обработки в приложении.

Основная задача сервиса — преобразование набора координат или адресов в маршрут, содержащий геометрию пути, сегменты, шаги навигации, а также метаданные: продолжительность, расстояние, ограничения и альтернативные варианты.

Directions Service не выполняет вычисление маршрута локально в браузере. Вместо этого он формирует запрос к API Google, передавая параметры маршрута, после чего получает JSON-ответ с результатом. Внутри API используется сложная система графов дорог, учитывающая:

  • дорожную сеть и её актуальное состояние
  • ограничения движения
  • типы дорог
  • среднюю скорость движения
  • транспортный режим

Запрос выполняется через объект google.maps.DirectionsService, который является частью основного пространства имён Google Maps JavaScript API.

Инициализация DirectionsService

Для начала работы создаётся экземпляр сервиса:

const directionsService = new google.maps.DirectionsService();

Этот объект предоставляет единственный ключевой метод — route, который используется для получения маршрута.

Структура запроса DirectionsRequest

Запрос маршрута формируется через объект конфигурации:

const request = {
  origin: "Moscow",
  destination: "Saint Petersburg",
  travelMode: google.maps.TravelMode.DRIVING
};

Ключевые поля запроса:

origin Начальная точка маршрута. Может быть:

  • строкой адреса
  • координатами { lat, lng }
  • объектом LatLng

destination Конечная точка маршрута. Поддерживает те же форматы, что и origin.

travelMode Определяет тип перемещения:

  • DRIVING — автомобиль
  • WALKING — пешком
  • BICYCLING — велосипед
  • TRANSIT — общественный транспорт

Расширенные параметры DirectionsRequest

Помимо базовых параметров, API поддерживает более сложную конфигурацию маршрута.

waypoints

Промежуточные точки маршрута:

waypoints: [
  { location: "Tver", stopover: true },
  { location: "Veliky Novgorod", stopover: true }
]

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

optimizeWaypoints

Позволяет оптимизировать порядок промежуточных точек:

optimizeWaypoints: true

Алгоритм переставляет точки для минимизации общего расстояния или времени пути. Особенно полезно в задачах логистики и маршрутизации доставок.

avoidHighways, avoidTolls, avoidFerries

Флаги, управляющие ограничениями маршрута:

avoidHighways: true,
avoidTolls: true,
avoidFerries: false

Эти параметры позволяют исключить платные дороги, магистрали или паромы.

provideRouteAlternatives

Если включено, API возвращает несколько возможных маршрутов:

provideRouteAlternatives: true

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

drivingOptions

Используется для более точного моделирования движения:

drivingOptions: {
  departureTime: new Date(),
  trafficModel: "bestguess"
}

Параметр trafficModel может принимать значения:

  • bestguess
  • pessimistic
  • optimistic

Вызов метода route

Основной метод работы сервиса:

directionsService.route(request, (result, status) => {
  if (status === "OK") {
    console.log(result);
  }
});

Статусы ответа DirectionsStatus

API возвращает статус выполнения запроса:

  • OK — маршрут успешно построен
  • NOT_FOUND — одна из точек не найдена
  • ZERO_RESULTS — маршрут невозможен
  • MAX_WAYPOINTS_EXCEEDED — превышено количество точек
  • INVALID_REQUEST — некорректный запрос
  • OVER_QUERY_LIMIT — превышен лимит запросов
  • REQUEST_DENIED — доступ запрещён

Обработка статуса является обязательной частью интеграции.

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

Результат содержит комплексную структуру:

routes

Массив маршрутов. Каждый маршрут включает:

  • overview_path — упрощённая геометрия
  • legs — сегменты между точками
  • bounds — границы маршрута
  • summary — краткое описание пути

legs

Каждый leg представляет участок между двумя waypoint или origin/destination. Он включает:

  • distance — расстояние
  • duration — время в пути
  • steps — пошаговая навигация

steps

Наиболее детализированный уровень маршрута. Каждый step содержит:

  • инструкции (html_instructions)
  • координаты начала и конца
  • полилинию сегмента
  • локальную дистанцию и длительность

Отображение маршрута с DirectionsRenderer

Для визуализации используется DirectionsRenderer:

const directionsRenderer = new google.maps.DirectionsRenderer();

directionsRenderer.setMap(map);
directionsRenderer.setDirections(result);

Renderer автоматически строит линию маршрута, добавляет маркеры и управляет отображением legs.

Работа с полилиниями маршрута

Каждый маршрут содержит encoded polyline, который можно декодировать для кастомной отрисовки:

const path = result.routes[0].overview_path;

Этот массив координат используется для построения кастомных визуализаций, анализа геометрии или интеграции с другими системами.

Использование маршрутов с несколькими вариантами

При включённом provideRouteAlternatives результат содержит несколько маршрутов:

result.routes.forEach((route, index) => {
  console.log(route.summary, route.legs[0].distance.text);
});

Каждый маршрут можно отдельно отрисовать или использовать для сравнения.

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

При логистических задачах ключевую роль играет параметр оптимизации:

waypoints: [
  { location: "A", stopover: true },
  { location: "B", stopover: true },
  { location: "C", stopover: true }
],
optimizeWaypoints: true

API возвращает оптимизированный порядок через поле:

result.routes[0].waypoint_order

Это массив индексов, отражающий перестановку точек.

Ограничения Directions Service

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

  • ограничение на количество waypoint (обычно до 25)
  • квоты запросов в зависимости от тарифа
  • невозможность точного контроля всех дорожных условий
  • зависимость от качества геокодирования

Практика обработки ошибок

Корректная обработка ошибок включает проверку статуса и fallback-логику:

if (status !== "OK") {
  switch (status) {
    case "ZERO_RESULTS":
      console.log("Маршрут недоступен");
      break;
    case "OVER_QUERY_LIMIT":
      console.log("Превышен лимит запросов");
      break;
  }
}

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

Directions Service тесно связан с Geocoding API. При передаче строковых адресов система автоматически преобразует их в координаты. При неоднозначных запросах используется наиболее вероятное совпадение, что может влиять на результат маршрута.

Особенности работы с общественным транспортом

При travelMode: TRANSIT структура ответа расширяется дополнительными полями:

  • transit lines
  • stop sequences
  • vehicle type
  • расписания

Каждый step может содержать сегменты пересадок между линиями.

Производительность и кэширование

Несмотря на серверную обработку, производительность зависит от:

  • частоты запросов
  • сложности маршрутов
  • количества waypoint

Часто используется клиентское кэширование результатов маршрутов для уменьшения нагрузки и ускорения повторных запросов.

Типичные сценарии использования

Directions Service применяется в:

  • системах доставки и логистики
  • сервисах такси и каршеринга
  • планировщиках маршрутов
  • туристических приложениях
  • трекинге перемещений

Работа с динамическими маршрутами

При изменении условий (перемещение точки origin, изменение trafficModel) маршрут пересчитывается повторным вызовом route, что позволяет реализовать динамическую навигацию в реальном времени без перезагрузки карты.

Оглавление