**European Economic Area (EEA) developers**

> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt).

<br />

> [!WARNING]
> This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google
> Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage
> descriptions](https://developers.google.com/maps/launch-stages).

<br />

You can compute and render routes on a [`<gmp-map-3d>`](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#Map3DElement) element in
two ways:

- **Declaratively with [`Route3DElement`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#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`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route) helper methods** : Call [`Route.computeRoutes`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.computeRoutes) and pass the route to [`create3DPolylines`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.create3DPolylines), [`createWaypointMarkers`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.createWaypointMarkers), and [`createPopover`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.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](https://developers.google.com/maps/documentation/javascript/versions.md.txt#beta-channel).

## 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](https://developers.google.com/maps/documentation/javascript/usage-and-billing.md.txt).

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

```html
<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 <var translate="no">YOUR_API_KEY</var> 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`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.origin) and [`destination`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.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`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.travelMode) (`travelMode`)** : Accepts `driving` (default), `walking`, `bicycling`, or `transit` (renders multimodal walking and transit line segments).
- **[`routing-preference`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.routingPreference) (`routingPreference`)** : Accepts `traffic-unaware`, `traffic-aware`, or `traffic-aware-optimal`.
- **[`traffic-polylines-disabled`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.trafficPolylinesDisabled)
  (`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`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.departureTime) (`departureTime`)** : Accepts an ISO 8601 timestamp string in HTML such as `"2027-03-15T16:00:00Z"`, or a `Date` object in JavaScript.
- **[`autofits-camera`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.autofitsCamera) (`autofitsCamera`)** : Frames the loaded route within the `<gmp-map-3d>` viewport.

## Handle route events and read route data

`Route3DElement` dispatches [`gmp-load`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.gmp-load) when a route finishes
rendering and [`gmp-error`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.gmp-error) if route computation fails or returns
zero routes. After `gmp-load` fires, you can read the computed
[`routes`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.routes), [`fallbackInfo`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.fallbackInfo), and
[`geocodingResults`](https://developers.google.com/maps/documentation/javascript/reference/routes-elements.md.txt#Route3DElement.geocodingResults) properties:

```javascript
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`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.computeRoutes)
and render the returned `Route` instance onto `<gmp-map-3d>` using its 3D helper
methods:

```html
<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 <var translate="no">YOUR_API_KEY</var> with your Google Maps Platform API key.

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

- **[`create3DPolylines`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.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`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#RoutePolyline3DOptions) to customize `polylineOptions` or set `trafficPolylinesDisabled`.
- **[`createWaypointMarkers`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.createWaypointMarkers)** : Request `'path'` in `fields`. Creates origin and destination markers (`Marker3DElement` by default, or `MarkerElement`, `MarkerInteractiveElement`, or `Marker3DInteractiveElement` when specified with `markerClass` in [`CreateWaypointMarkersOptions`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#CreateWaypointMarkersOptions)). Intermediate waypoints aren't generated by this method.
- **[`createPopover`](https://developers.google.com/maps/documentation/javascript/reference/route.md.txt#Route.createPopover)** : Request `'path'` and `'localizedValues'` (plus `'legs'` for transit routes) to anchor a summary `PopoverElement` halfway along the route path.

## Next steps

- [Automatically fit the camera to map elements](https://developers.google.com/maps/documentation/javascript/3d/autofit-camera.md.txt)
- [Route class overview](https://developers.google.com/maps/documentation/javascript/routes/route-class-overview.md.txt)
- [Popovers](https://developers.google.com/maps/documentation/javascript/3d/popovers.md.txt)