Как показать маршруты на 3D-карте

Разработчики из Европейской экономической зоны (ЕЭЗ)

Рассчитать и отобразить маршруты на элементе <gmp-map-3d> можно двумя способами:

  • Декларативно с помощью Route3DElement (<gmp-route-3d>). Добавьте веб-компонент, который запрашивает маршруты из Routes API и отрисовывает трехмерные ломаные линии маршрутов, маркеры начальной и конечной точек, а также всплывающее окно со сводными данными о маршруте.
  • Программно с помощью вспомогательных методов Route. Вызовите Route.computeRoutes и передайте маршрут в create3DPolylines, createWaypointMarkers и createPopover, если вам нужны промежуточные путевые точки, специальные маски полей или стили ломаных линий.

Оба подхода доступны в канале v=beta Maps JavaScript API. Инструкции по загрузке бета-канала приведены в разделе Версии.

Требования и оплата

Прежде чем показывать 3D-маршруты, настройте облачный проект Google Cloud и включите в нем Maps JavaScript API и Routes API. Загрузите библиотеки maps3d и routes.

Отрисовка <gmp-map-3d> оплачивается по тарифу "Динамические 3D-карты" (Immersive Maps Pro). Каждый запрос маршрута, сделанный <gmp-route-3d> или Route.computeRoutes, оплачивается по коду Compute Routes Routes API в зависимости от запрошенных функций:

Конфигурация Уровень SKU Routes
Запросы маршрутов по умолчанию (TRAFFIC_UNAWARE или способы передвижения WALKING, BICYCLING и TRANSIT без полилиний трафика) Compute Routes Essentials
Для параметра routing-preference задано значение traffic-aware или traffic-aware-optimal, а параметр traffic-polylines-disabled включен. Compute Routes Pro
routing-preference со значением traffic-aware или traffic-aware-optimal с включенными ломаными линиями, цвет которых зависит от загруженности дорог (по умолчанию, если заданы настройки с учетом трафика). Compute Routes Enterprise

Подробную информацию о кодах SKU вы найдете в статье Статистика использования и оплата Maps JavaScript API.

Как добавить 3D-маршрут с помощью HTML

Чтобы показать маршрут между пунктами отправления и назначения с минимальным количеством кода, вложите <gmp-route-3d> в <gmp-map-3d> и добавьте autofits-camera, чтобы маршрут автоматически вписывался в границы карты.

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-route-3d
    origin="Space Needle, Seattle, WA"
    destination="Tacoma Dome, Tacoma, WA"
    travel-mode="driving"
    routing-preference="traffic-aware"
    autofits-camera>
  </gmp-route-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d,routes">
</script>

Замените YOUR_API_KEY ключом API платформы Google Карт.

Route3DElement автоматически подбирает цвета ломаной линии и всплывающего окна со сводными данными в соответствии со светлой или темной цветовой схемой родительского элемента <gmp-map-3d> и поддерживает следующие атрибуты и свойства:

  • origin и destination. Принимают строку координат "lat,lng", название ресурса места, например "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", или строку адреса. В JavaScript эти свойства также принимают объекты LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral и Place.
  • travel-mode (travelMode). Допустимые значения: driving (по умолчанию), walking, bicycling или transit (отображает мультимодальные пешеходные и транзитные сегменты).
  • routing-preference (routingPreference): принимает значения traffic-unaware, traffic-aware или traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): отключает выделение цветом ломаных линий, обозначающих скорость движения, на маршрутах с учетом трафика, чтобы запрос оплачивался по тарифу Compute Routes Pro, а не Compute Routes Enterprise.
  • departure-time (departureTime) – принимает строку временной метки ISO 8601 в HTML, например "2027-03-15T16:00:00Z", или объект Date в JavaScript.
  • autofits-camera (autofitsCamera) – помещает загруженный маршрут в область просмотра <gmp-map-3d>.

Обработка событий маршрута и чтение данных маршрута

Route3DElement отправляет gmp-load, когда маршрут отрисован, и gmp-error, если расчет маршрута не удался или не дал результатов. После срабатывания gmp-load вы можете прочитать вычисленные свойства routes, fallbackInfo и geocodingResults:

const routeElement = document.querySelector('gmp-route-3d');

routeElement.addEventListener('gmp-load', () => {
  const primaryRoute = routeElement.routes?.[0];
  console.log('Distance (m):', primaryRoute?.distanceMeters);
  console.log('Duration:', primaryRoute?.localizedValues?.duration);
});

routeElement.addEventListener('gmp-error', () => {
  console.error('Failed to load the 3D route.');
});

Когда использовать вспомогательные методы Route вместо gmp-route-3d

<gmp-route-3d> отрисовывает основной маршрут между одной точкой origin и одной точкой destination с маркером и ломаной линией по умолчанию. Используйте Route.computeRoutes со вспомогательными методами 3D, если вам нужны промежуточные путевые точки, выбор альтернативного маршрута, специальные маски полей ответа или специальные стили ломаных линий и маркеров.

Настройка отрисовки 3D-маршрута с помощью класса Route

Для пользовательских рабочих процессов с 3D-маршрутами вызовите Route.computeRoutes и отрисуйте возвращенный экземпляр Route на <gmp-map-3d>, используя вспомогательные методы 3D:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const { Map3DElement, MapMode } =
      await google.maps.importLibrary('maps3d');
    const { Route } = await google.maps.importLibrary('routes');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
    });
    document.getElementById('map-container').append(map);

    const { routes } = await Route.computeRoutes({
      origin: '1800 Amphibious Blvd., Mountain View, CA 94045',
      destination: 'San Francisco Ferry Building, San Francisco, CA',
      travelMode: 'DRIVING',
      routingPreference: 'TRAFFIC_AWARE',
      extraComputations: ['TRAFFIC_ON_POLYLINE'],
      fields: ['path', 'speedPaths', 'localizedValues'],
    });

    const route = routes?.[0];
    if (!route) return;

    const [polylines, markers, popover] = await Promise.all([
      route.create3DPolylines({
        polylineOptions: {
          strokeWidth: 10,
          autofitsCamera: true,
        },
      }),
      route.createWaypointMarkers(),
      route.createPopover(),
    ]);

    map.append(...polylines, ...markers, popover);
  }
</script>
<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>

Замените YOUR_API_KEY ключом API платформы Google Карт.

Для каждого вспомогательного метода, который вы вызываете, укажите обязательные поля в ComputeRoutesRequest.fields:

  • create3DPolylines: запросите 'path' или 'legs' для стандартных ломаных линий, 'path' и 'legs', когда travelMode – 'TRANSIT', или 'speedPaths' с extraComputations: ['TRAFFIC_ON_POLYLINE'] для ломаных линий с цветовым обозначением загруженности дорог. Передайте RoutePolyline3DOptions, чтобы настроить polylineOptions или задать trafficPolylinesDisabled.
  • createWaypointMarkers: запрос 'path' в fields. Создает маркеры начальной и конечной точек (Marker3DElement по умолчанию или MarkerElement, MarkerInteractiveElement или Marker3DInteractiveElement, если указано с помощью markerClass в CreateWaypointMarkersOptions). Промежуточные путевые точки этим методом не генерируются.
  • createPopover: запросите 'path' и 'localizedValues' (а также 'legs' для маршрутов общественного транспорта), чтобы закрепить сводку PopoverElement в середине маршрута.

Дальнейшие действия