Afficher des itinéraires sur une carte 3D

Développeurs de l'Espace économique européen (EEE)

Vous pouvez calculer et afficher des itinéraires sur un élément <gmp-map-3d> de deux manières :

  • De manière déclarative avec Route3DElement (<gmp-route-3d>) : ajoutez un composant Web qui demande un itinéraire à l'API Routes et affiche des polylignes d'itinéraire en 3D, des repères de départ et de destination, ainsi qu'un popover de résumé de l'itinéraire.
  • Par programmation avec les méthodes d'assistance Route : appelez Route.computeRoutes et transmettez l'itinéraire à create3DPolylines, createWaypointMarkers et createPopover lorsque vous avez besoin de points de cheminement intermédiaires, de masques de champ personnalisés ou de styles de polylignes personnalisés.

Les deux approches sont disponibles dans le canal v=beta de l'API Maps JavaScript. Pour savoir comment charger la version bêta, consultez Gestion des versions.

Prérequis et facturation

Avant d'afficher des itinéraires en 3D, configurez votre projet Google Cloud, puis activez l'API Maps JavaScript et l'API Routes pour ce projet. Chargez les bibliothèques maps3d et routes.

Le rendu de <gmp-map-3d> est facturé sous Cartes 3D dynamiques (Immersive Maps Pro). Chaque requête d'itinéraire effectuée par <gmp-route-3d> ou Route.computeRoutes est facturée sous un SKU Compute Routes de l'API Routes en fonction des fonctionnalités demandées :

Configuration Niveau de SKU Routes
Requêtes d'itinéraires par défaut (TRAFFIC_UNAWARE, ou modes de transport WALKING, BICYCLING et TRANSIT sans polylignes de trafic) Compute Routes Essentials
routing-preference défini sur traffic-aware ou traffic-aware-optimal avec traffic-polylines-disabled activé Compute Routes Pro
routing-preference défini sur traffic-aware ou traffic-aware-optimal avec les polylignes colorées en fonction du trafic activées (par défaut lorsqu'une préférence tenant compte du trafic est définie) Compute Routes Enterprise

Pour en savoir plus sur les SKU, consultez Utilisation et facturation de l'API Maps JavaScript.

Ajouter un itinéraire 3D en utilisant le HTML

Pour afficher un itinéraire entre un point de départ et une destination avec un minimum de code, imbriquez <gmp-route-3d> dans <gmp-map-3d> et ajoutez autofits-camera pour que la carte encadre automatiquement l'itinéraire :

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

Remplacez YOUR_API_KEY par votre clé API Google Maps Platform.

Route3DElement adapte automatiquement les couleurs de sa polyligne et de son popover récapitulatif au jeu de couleurs clair ou sombre du <gmp-map-3d> parent, et accepte les attributs et propriétés suivants :

  • origin et destination : acceptent une chaîne de coordonnées "lat,lng", un nom de ressource de lieu tel que "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s" ou une chaîne d'adresse. En JavaScript, ces propriétés acceptent également les objets LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral et Place.
  • travel-mode (travelMode) : accepte driving (par défaut), walking, bicycling ou transit (affiche les segments de marche et de transports en commun multimodaux).
  • routing-preference (routingPreference) : accepte traffic-unaware, traffic-aware ou traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled) : désactive la coloration des polylignes en fonction de la vitesse du trafic sur les itinéraires tenant compte du trafic, de sorte que la requête soit facturée au tarif Compute Routes Pro au lieu de Compute Routes Enterprise.
  • departure-time (departureTime) : accepte une chaîne d'horodatage ISO 8601 en HTML, telle que "2027-03-15T16:00:00Z", ou un objet Date en JavaScript.
  • autofits-camera (autofitsCamera) : encadre l'itinéraire chargé dans la fenêtre d'affichage <gmp-map-3d>.

Gérer les événements d'itinéraire et lire les données d'itinéraire

Route3DElement envoie gmp-load lorsqu'un itinéraire a fini d'être affiché et gmp-error si le calcul de l'itinéraire échoue ou ne renvoie aucun itinéraire. Une fois que gmp-load se déclenche, vous pouvez lire les propriétés calculées routes, fallbackInfo et 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.');
});

Quand utiliser les méthodes d'assistance Route au lieu de gmp-route-3d

<gmp-route-3d> affiche l'itinéraire principal entre un seul origin et un seul destination avec un style de repère et de polyligne par défaut. Utilisez Route.computeRoutes avec les méthodes d'assistance 3D lorsque vous avez besoin de points de cheminement intermédiaires, d'une sélection d'itinéraires alternatifs, de masques de champ de réponse personnalisés ou de styles de polylignes et de repères personnalisés.

Personnaliser l'affichage des itinéraires en 3D avec la classe Route

Pour les workflows d'itinéraires 3D personnalisés, appelez Route.computeRoutes et affichez l'instance Route renvoyée sur <gmp-map-3d> à l'aide de ses méthodes d'assistance 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>

Remplacez YOUR_API_KEY par votre clé API Google Maps Platform.

Incluez les champs obligatoires dans ComputeRoutesRequest.fields pour chaque méthode d'assistance que vous appelez :

  • create3DPolylines : demandez 'path' ou 'legs' pour les polylignes standards, 'path' et 'legs' lorsque travelMode est défini sur 'TRANSIT', ou 'speedPaths' avec extraComputations: ['TRAFFIC_ON_POLYLINE'] pour les polylignes colorées en fonction du trafic. Transmettez RoutePolyline3DOptions pour personnaliser polylineOptions ou définir trafficPolylinesDisabled.
  • createWaypointMarkers : demandez 'path' dans fields. Crée des repères d'origine et de destination (Marker3DElement par défaut, ou MarkerElement, MarkerInteractiveElement ou Marker3DInteractiveElement lorsqu'ils sont spécifiés avec markerClass dans CreateWaypointMarkersOptions). Les points de cheminement intermédiaires ne sont pas générés par cette méthode.
  • createPopover : demandez 'path' et 'localizedValues' (ainsi que 'legs' pour les itinéraires en transports en commun) pour ancrer un résumé PopoverElement à mi-chemin de l'itinéraire.

Étapes suivantes