Запрос маршрута между точками

Запрос маршрута в Google Maps JavaScript API строится вокруг сервиса DirectionsService, который отвечает за вычисление маршрута между точками, и DirectionsRenderer, который визуализирует результат на карте. Архитектура разделяет вычисление маршрута и его отображение, что позволяет гибко управлять результатом и интеграцией в интерфейс.

Маршрутизация в Google Maps API опирается на два ключевых объекта:

  • DirectionsService — формирует запрос и получает данные о маршруте
  • DirectionsRenderer — отображает маршрут на карте и в дополнительной панели

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

Инициализация карты и слоя маршрута

Перед построением маршрута создаётся карта и подключается слой отображения:

let map;
let directionsService;
let directionsRenderer;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.748817, lng: -73.985428 },
    zoom: 13,
  });

  directionsService = new google.maps.DirectionsService();
  directionsRenderer = new google.maps.DirectionsRenderer({
    map: map,
    suppressMarkers: false,
  });
}

DirectionsRenderer привязывается к объекту карты, после чего автоматически управляет отображением полилиний маршрута и маркеров.

Формирование запроса маршрута

Запрос маршрута выполняется методом route у DirectionsService. Основная структура запроса включает начальную точку, конечную точку и параметры маршрутизации.

function calculateRoute() {
  const request = {
    origin: "Times Square, New York, NY",
    destination: "Central Park, New York, NY",
    travelMode: google.maps.TravelMode.DRIVING,
  };

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

Параметры запроса

Ключевые поля объекта запроса:

  • origin — начальная точка маршрута (строка, координаты или Place)
  • destination — конечная точка маршрута
  • travelMode — режим передвижения
  • waypoints — промежуточные точки
  • optimizeWaypoints — оптимизация порядка точек
  • provideRouteAlternatives — альтернативные маршруты

Режимы передвижения

Поддерживаются различные типы маршрутов:

  • DRIVING — автомобильный маршрут
  • WALKING — пеший маршрут
  • BICYCLING — велосипедный маршрут
  • TRANSIT — маршрут общественного транспорта
travelMode: google.maps.TravelMode.WALKING

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

Использование промежуточных точек

Промежуточные точки позволяют строить сложные маршруты с несколькими остановками.

const request = {
  origin: "Berlin",
  destination: "Munich",
  travelMode: google.maps.TravelMode.DRIVING,
  waypoints: [
    { location: "Leipzig", stopover: true },
    { location: "Nuremberg", stopover: true }
  ],
};

Каждый waypoint может быть отмечен как остановка (stopover), что влияет на перерасчёт маршрута.

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

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

const request = {
  origin: "City A",
  destination: "City B",
  waypoints: [
    { location: "Point 1" },
    { location: "Point 2" },
    { location: "Point 3" }
  ],
  optimizeWaypoints: true,
  travelMode: google.maps.TravelMode.DRIVING,
};

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

Обработка результата маршрута

Ответ DirectionsService содержит структуру с маршрутами, сегментами и шагами движения.

directionsService.route(request, (result, status) => {
  if (status === "OK") {
    const route = result.routes[0];

    const leg = route.legs[0];
    console.log(leg.distance.text);
    console.log(leg.duration.text);

    directionsRenderer.setDirections(result);
  }
});

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

  • routes — массив возможных маршрутов
  • legs — участки между точками
  • steps — отдельные инструкции движения
  • distance — расстояние
  • duration — время в пути

Каждый leg соответствует сегменту между двумя точками маршрута.

Статусы ответа сервиса

Результат запроса сопровождается статусом:

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

Обработка статусов критична для стабильной работы интерфейса.

Кастомизация отображения маршрута

DirectionsRenderer поддерживает настройку внешнего вида маршрута:

directionsRenderer = new google.maps.DirectionsRenderer({
  map: map,
  polylineOptions: {
    strokeColor: "#1a73e8",
    strokeOpacity: 0.8,
    strokeWeight: 6,
  },
  suppressMarkers: true,
});

Возможные настройки:

  • изменение цвета линии маршрута
  • управление маркерами начала и конца
  • отключение стандартных маркеров
  • вывод текстовых инструкций

Получение альтернативных маршрутов

Сервис способен возвращать несколько вариантов маршрута:

const request = {
  origin: "A",
  destination: "B",
  travelMode: google.maps.TravelMode.DRIVING,
  provideRouteAlternatives: true,
};

В ответе появляется несколько объектов routes, каждый из которых может быть отображён отдельно.

Работа с шагами маршрута

Каждый маршрут разбивается на шаги (steps), содержащие детальные инструкции:

const steps = result.routes[0].legs[0].steps;

steps.forEach(step => {
  console.log(step.instructions);
  console.log(step.distance.text);
});

Инструкции включают HTML-разметку, описывающую повороты, развязки и изменения направления.

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

Вместо строковых адресов могут использоваться координаты:

const request = {
  origin: { lat: 55.7558, lng: 37.6173 },
  destination: { lat: 59.9311, lng: 30.3609 },
  travelMode: google.maps.TravelMode.DRIVING,
};

Такой подход уменьшает зависимость от геокодирования и повышает точность запроса.

Интеграция с динамическими данными

Маршрут может пересчитываться при изменении входных данных, например при перетаскивании маркеров:

marker.addListener("dragend", () => {
  calculateRoute();
});

Это позволяет строить интерактивные интерфейсы с обновлением маршрута в реальном времени.

Ограничения сервиса маршрутизации

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

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

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

Оглавление