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
Routehelper methods: CallRoute.computeRoutesand pass the route tocreate3DPolylines,createWaypointMarkers, andcreatePopoverwhen 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:
originanddestination: Accept a"lat,lng"coordinate string, a place resource name such as"places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", or an address string. In JavaScript, these properties also acceptLatLng,LatLngLiteral,LatLngAltitude,LatLngAltitudeLiteral, andPlaceobjects.travel-mode(travelMode): Acceptsdriving(default),walking,bicycling, ortransit(renders multimodal walking and transit line segments).routing-preference(routingPreference): Acceptstraffic-unaware,traffic-aware, ortraffic-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 aDateobject 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'whentravelModeis'TRANSIT', or'speedPaths'withextraComputations: ['TRAFFIC_ON_POLYLINE']for traffic-colored polylines. PassRoutePolyline3DOptionsto customizepolylineOptionsor settrafficPolylinesDisabled.createWaypointMarkers: Request'path'infields. Creates origin and destination markers (Marker3DElementby default, orMarkerElement,MarkerInteractiveElement, orMarker3DInteractiveElementwhen specified withmarkerClassinCreateWaypointMarkersOptions). Intermediate waypoints aren't generated by this method.createPopover: Request'path'and'localizedValues'(plus'legs'for transit routes) to anchor a summaryPopoverElementhalfway along the route path.