Routen auf einer 3D-Karte anzeigen

Entwickler im Europäischen Wirtschaftsraum (EWR)

Sie können Routen auf einem <gmp-map-3d>-Element auf zwei Arten berechnen und rendern:

  • Deklarativ mit Route3DElement (<gmp-route-3d>): Fügen Sie eine Webkomponente hinzu, die Wegbeschreibungen von der Routes API anfordert und 3D-Routenpolylinien, Start- und Zielmarkierungen sowie ein Pop-over mit einer Routenzusammenfassung rendert.
  • Programmatisch mit Route-Hilfsmethoden: Rufen Sie Route.computeRoutes auf und übergeben Sie die Route an create3DPolylines, createWaypointMarkers und createPopover, wenn Sie Zwischenwegpunkte, benutzerdefinierte Feldmasken oder benutzerdefinierte Polylinienstile benötigen.

Beide Ansätze sind im v=beta-Kanal der Maps JavaScript API verfügbar. Eine Anleitung zum Laden der Betaversion finden Sie unter Versionsverwaltung.

Voraussetzungen und Abrechnung

Bevor Sie 3D-Routen anzeigen können, müssen Sie Ihr Google Cloud-Projekt einrichten und sowohl die Maps JavaScript API als auch die Routes API für dieses Projekt aktivieren. Laden Sie die Bibliotheken maps3d und routes.

Das Rendern von <gmp-map-3d> wird unter „Dynamische 3D-Karten (Immersive Maps Pro)“ abgerechnet. Jede Routenanfrage, die von <gmp-route-3d> oder Route.computeRoutes gestellt wird, wird gemäß einer Routes API-Compute Routes-SKU abgerechnet, die auf den angeforderten Funktionen basiert:

Konfiguration Routes-SKU-Stufe
Standardmäßige Routenanfragen (TRAFFIC_UNAWARE oder die Mobilitätsformen WALKING, BICYCLING und TRANSIT ohne Polylinien für die Verkehrslage) Compute Routes Essentials
routing-preference auf traffic-aware oder traffic-aware-optimal mit aktiviertem traffic-polylines-disabled festgelegt Compute Routes Pro
routing-preference auf traffic-aware oder traffic-aware-optimal gesetzt, wobei Polylinien mit Verkehrsfarben aktiviert sind (Standard, wenn eine verkehrsabhängige Einstellung festgelegt ist) Compute Routes Enterprise

Details zu SKUs finden Sie unter Maps JavaScript API: Nutzung und Abrechnung.

3D-Route mithilfe von HTML hinzufügen

Wenn Sie eine Route zwischen einem Start- und einem Zielpunkt mit minimalem Code anzeigen möchten, verschachteln Sie <gmp-route-3d> in <gmp-map-3d> und fügen Sie autofits-camera hinzu, damit die Route automatisch auf der Karte dargestellt wird:

<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>

Ersetzen Sie YOUR_API_KEY durch Ihren Google Maps Platform-API-Schlüssel.

Route3DElement passt die Farben der Polylinie und des Popovers für die Zusammenfassung automatisch an das helle oder dunkle Farbschema des übergeordneten <gmp-map-3d> an und unterstützt die folgenden Attribute und Eigenschaften:

  • origin und destination: Akzeptieren einen "lat,lng"-Koordinatenstring, einen Ortsressourcennamen wie "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s" oder einen Adressstring. In JavaScript akzeptieren diese Attribute auch LatLng-, LatLngLiteral-, LatLngAltitude-, LatLngAltitudeLiteral- und Place-Objekte.
  • travel-mode (travelMode): Akzeptiert driving (Standard), walking, bicycling oder transit (rendert multimodale Fußgänger- und ÖPNV-Segmente).
  • routing-preference (routingPreference): Akzeptiert traffic-unaware, traffic-aware oder traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): Deaktiviert die Polylinienfärbung für die Verkehrsgeschwindigkeit auf verkehrsabhängigen Routen, sodass die Anfrage unter Compute Routes Pro statt unter Compute Routes Enterprise abgerechnet wird.
  • departure-time (departureTime): Akzeptiert einen ISO 8601-Zeitstempelstring in HTML, z. B. "2027-03-15T16:00:00Z", oder ein Date-Objekt in JavaScript.
  • autofits-camera (autofitsCamera): Die geladene Route wird im <gmp-map-3d>-Darstellungsbereich eingerahmt.

Routenereignisse verarbeiten und Routendaten lesen

Route3DElement sendet gmp-load, wenn das Rendern einer Route abgeschlossen ist, und gmp-error, wenn die Routenberechnung fehlschlägt oder keine Routen zurückgibt. Nachdem gmp-load ausgelöst wurde, können Sie die berechneten Attribute routes, fallbackInfo und geocodingResults lesen:

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.');
});

Wann sollten Hilfsmethoden für Routen anstelle von gmp-route-3d verwendet werden?

<gmp-route-3d> rendert die primäre Route zwischen einem einzelnen origin und destination mit Standardmarkierungen und Polylinien-Stil. Verwenden Sie Route.computeRoutes mit den 3D-Hilfsmethoden, wenn Sie Zwischenwegpunkte, eine alternative Routenauswahl, benutzerdefinierte Antwortfeldmasken oder benutzerdefinierte Polylinien- und Markierungsstile benötigen.

3D-Routenrendering mit der Klasse „Route“ anpassen

Rufen Sie für benutzerdefinierte 3D-Routen-Workflows Route.computeRoutes auf und rendern Sie die zurückgegebene Route-Instanz mit den 3D-Hilfsmethoden auf <gmp-map-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>

Ersetzen Sie YOUR_API_KEY durch Ihren Google Maps Platform-API-Schlüssel.

Fügen Sie die erforderlichen Felder in ComputeRoutesRequest.fields für jede Hilfsmethode ein, die Sie aufrufen:

  • create3DPolylines: Fordern Sie 'path' oder 'legs' für Standard-Polylinien an, 'path' und 'legs', wenn travelMode den Wert 'TRANSIT' hat, oder 'speedPaths' mit extraComputations: ['TRAFFIC_ON_POLYLINE'] für Polylinien mit Verkehrsinformationen. Übergeben Sie RoutePolyline3DOptions, um polylineOptions anzupassen oder trafficPolylinesDisabled festzulegen.
  • createWaypointMarkers: Fordert 'path' in fields an. Erstellt Start- und Zielmarkierungen (standardmäßig Marker3DElement oder MarkerElement, MarkerInteractiveElement oder Marker3DInteractiveElement, wenn mit markerClass in CreateWaypointMarkersOptions angegeben). Zwischenwegpunkte werden mit dieser Methode nicht generiert.
  • createPopover: Fordern Sie 'path' und 'localizedValues' (plus 'legs' für Routen mit öffentlichen Verkehrsmitteln) an, um eine Zusammenfassung PopoverElement in der Mitte des Routenpfads zu verankern.

Nächste Schritte