Display routes on a 3D map

European Economic Area (EEA) developers

You can compute and render routes on a <gmp-map-3d> element in two ways:

  • Declaratively with Route3DElement (<gmp-route-3d>): Add a web component that requests directions from the Routes API and renders 3D route polylines, origin and destination markers, and a route summary popover.
  • Programmatically with Route helper methods: Call Route.computeRoutes and pass the route to create3DPolylines, createWaypointMarkers, and createPopover when you need intermediate waypoints, custom field masks, or custom polyline styles.

Both approaches are available in the v=beta channel of the Maps JavaScript API. For instructions on loading the beta channel, see Versioning.

Prerequisites and billing

Before displaying 3D routes, set up your Google Cloud project and enable both the Maps JavaScript API and the Routes API for that project. Load both the maps3d and routes libraries.

Rendering <gmp-map-3d> is billed under Dynamic 3D Maps (Immersive Maps Pro). Each route request made by <gmp-route-3d> or Route.computeRoutes is billed under a Routes API Compute Routes SKU based on the features requested:

Configuration Routes SKU tier
Default route requests (TRAFFIC_UNAWARE, or WALKING, BICYCLING, and TRANSIT travel modes without traffic polylines) Compute Routes Essentials
routing-preference set to traffic-aware or traffic-aware-optimal with traffic-polylines-disabled enabled Compute Routes Pro
routing-preference set to traffic-aware or traffic-aware-optimal with traffic-colored polylines enabled (default when a traffic-aware preference is set) Compute Routes Enterprise

For SKU details, see Maps JavaScript API Usage and Billing.

Add a 3D route using HTML

To display a route between an origin and a destination with minimal code, nest <gmp-route-3d> inside <gmp-map-3d> and add autofits-camera so that the map frames the route automatically:

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

Replace YOUR_API_KEY with your Google Maps Platform API key.

Route3DElement automatically matches its polyline and summary popover colors to the light or dark color scheme of the parent <gmp-map-3d>, and supports the following attributes and properties:

  • origin and destination: Accept a "lat,lng" coordinate string, a place resource name such as "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", or an address string. In JavaScript, these properties also accept LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral, and Place objects.
  • travel-mode (travelMode): Accepts driving (default), walking, bicycling, or transit (renders multimodal walking and transit line segments).
  • routing-preference (routingPreference): Accepts traffic-unaware, traffic-aware, or traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): Disables traffic-speed polyline coloring on traffic-aware routes so the request is billed under Compute Routes Pro instead of Compute Routes Enterprise.
  • departure-time (departureTime): Accepts an ISO 8601 timestamp string in HTML such as "2027-03-15T16:00:00Z", or a Date object in JavaScript.
  • autofits-camera (autofitsCamera): Frames the loaded route within the <gmp-map-3d> viewport.

Handle route events and read route data

Route3DElement dispatches gmp-load when a route finishes rendering and gmp-error if route computation fails or returns zero routes. After gmp-load fires, you can read the computed routes, fallbackInfo, and geocodingResults properties:

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

When to use Route helper methods instead of gmp-route-3d

<gmp-route-3d> renders the primary route between a single origin and destination with default marker and polyline styling. Use Route.computeRoutes with the 3D helper methods when you need intermediate waypoints, alternative route selection, custom response field masks, or custom polyline and marker styles.

Customize 3D route rendering with the Route class

For custom 3D route workflows, call Route.computeRoutes and render the returned Route instance onto <gmp-map-3d> using its 3D helper methods:

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

Replace YOUR_API_KEY with your Google Maps Platform API key.

Include the required fields in ComputeRoutesRequest.fields for each helper method you call:

  • create3DPolylines: Request 'path' or 'legs' for standard polylines, 'path' and 'legs' when travelMode is 'TRANSIT', or 'speedPaths' with extraComputations: ['TRAFFIC_ON_POLYLINE'] for traffic-colored polylines. Pass RoutePolyline3DOptions to customize polylineOptions or set trafficPolylinesDisabled.
  • createWaypointMarkers: Request 'path' in fields. Creates origin and destination markers (Marker3DElement by default, or MarkerElement, MarkerInteractiveElement, or Marker3DInteractiveElement when specified with markerClass in CreateWaypointMarkersOptions). Intermediate waypoints aren't generated by this method.
  • createPopover: Request 'path' and 'localizedValues' (plus 'legs' for transit routes) to anchor a summary PopoverElement halfway along the route path.

Next steps