Muestra rutas en un mapa en 3D

Desarrolladores del Espacio Económico Europeo (EEE)

Puedes calcular y renderizar rutas en un elemento <gmp-map-3d> de dos maneras:

  • De forma declarativa con Route3DElement (<gmp-route-3d>): Agrega un componente web que solicite instrucciones sobre cómo llegar desde la API de Routes y renderice polilíneas de rutas en 3D, marcadores de origen y destino, y un cuadro emergente con un resumen de la ruta.
  • De manera programática con los métodos auxiliares de Route: Llama a Route.computeRoutes y pasa la ruta a create3DPolylines, createWaypointMarkers y createPopover cuando necesites puntos de referencia intermedios, máscaras de campo personalizadas o estilos de polilínea personalizados.

Ambos enfoques están disponibles en el canal v=beta de la API de Maps JavaScript. Para obtener instrucciones sobre cómo cargar el canal Beta, consulta Control de versiones.

Requisitos previos y facturación

Antes de mostrar rutas en 3D, configura tu proyecto de Google Cloud y habilita la API de Maps JavaScript y la API de Routes para ese proyecto. Carga las bibliotecas maps3d y routes.

La renderización de <gmp-map-3d> se factura en Dynamic 3D Maps (Immersive Maps Pro). Cada solicitud de ruta que realiza <gmp-route-3d> o Route.computeRoutes se factura con un SKU de Compute Routes de la API de Routes según las funciones solicitadas:

Configuración Nivel de SKU de Routes
Solicitudes de rutas predeterminadas (TRAFFIC_UNAWARE o los medios de transporte WALKING, BICYCLING y TRANSIT sin polilíneas de tráfico) Compute Routes Essentials
routing-preference establecido en traffic-aware o traffic-aware-optimal con traffic-polylines-disabled habilitado Compute Routes Pro
routing-preference establecido en traffic-aware o traffic-aware-optimal con polilíneas de colores según el tráfico habilitadas (opción predeterminada cuando se establece una preferencia de reconocimiento del tráfico) Compute Routes Enterprise

Para obtener detalles sobre los SKU, consulta Uso y facturación de la API de Maps JavaScript.

Cómo agregar una ruta en 3D con HTML

Para mostrar una ruta entre un origen y un destino con un código mínimo, anida <gmp-route-3d> dentro de <gmp-map-3d> y agrega autofits-camera para que el mapa enmarque la ruta automáticamente:

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

Reemplaza YOUR_API_KEY por tu clave de API de Google Maps Platform.

Route3DElement hace coincidir automáticamente los colores de su polilínea y de la ventana emergente de resumen con el esquema de colores claro u oscuro del <gmp-map-3d> superior, y admite los siguientes atributos y propiedades:

  • origin y destination: Aceptan una cadena de coordenadas "lat,lng", un nombre de recurso de lugar, como "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", o una cadena de dirección. En JavaScript, estas propiedades también aceptan objetos LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral y Place.
  • travel-mode (travelMode): Acepta driving (predeterminado), walking, bicycling o transit (renderiza segmentos de líneas de transporte público y caminata multimodales).
  • routing-preference (routingPreference): Acepta traffic-unaware, traffic-aware o traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): Inhabilita el color de la polilínea de velocidad del tráfico en las rutas que tienen en cuenta el tráfico para que la solicitud se facture con Compute Routes Pro en lugar de Compute Routes Enterprise.
  • departure-time (departureTime): Acepta una cadena de marca de tiempo ISO 8601 en HTML, como "2027-03-15T16:00:00Z", o un objeto Date en JavaScript.
  • autofits-camera (autofitsCamera): Enmarca la ruta cargada dentro del viewport de <gmp-map-3d>.

Cómo controlar eventos de ruta y leer datos de ruta

Route3DElement envía gmp-load cuando una ruta termina de renderizarse y gmp-error si el cálculo de la ruta falla o devuelve cero rutas. Después de que se active gmp-load, puedes leer las propiedades calculadas routes, fallbackInfo y 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.');
});

Cuándo usar los métodos auxiliares de Route en lugar de gmp-route-3d

<gmp-route-3d> renderiza la ruta principal entre un solo origin y un solo destination con el estilo predeterminado de marcador y polilínea. Usa Route.computeRoutes con los métodos auxiliares de 3D cuando necesites puntos de referencia intermedios, selección de rutas alternativas, máscaras de campo de respuesta personalizadas o estilos personalizados de polilíneas y marcadores.

Personaliza la renderización de rutas en 3D con la clase Route

Para los flujos de trabajo de rutas en 3D personalizadas, llama a Route.computeRoutes y renderiza la instancia de Route que se muestra en <gmp-map-3d> con sus métodos auxiliares en 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>

Reemplaza YOUR_API_KEY por tu clave de API de Google Maps Platform.

Incluye los campos obligatorios en ComputeRoutesRequest.fields para cada método auxiliar al que llames:

  • create3DPolylines: Solicita 'path' o 'legs' para polilíneas estándar, 'path' y 'legs' cuando travelMode es 'TRANSIT', o 'speedPaths' con extraComputations: ['TRAFFIC_ON_POLYLINE'] para polilíneas con colores de tráfico. Pasa RoutePolyline3DOptions para personalizar polylineOptions o establecer trafficPolylinesDisabled.
  • createWaypointMarkers: Solicita 'path' en fields. Crea marcadores de origen y destino (Marker3DElement de forma predeterminada, o MarkerElement, MarkerInteractiveElement o Marker3DInteractiveElement cuando se especifica con markerClass en CreateWaypointMarkersOptions). Este método no genera puntos de referencia intermedios.
  • createPopover: Solicita 'path' y 'localizedValues' (además de 'legs' para las rutas de transporte público) para fijar un resumen PopoverElement a mitad de camino de la ruta.

Próximos pasos