Mostrar trajetos em um mapa 3D

Desenvolvedores do Espaço Econômico Europeu (EEE)

É possível calcular e renderizar rotas em um elemento <gmp-map-3d> de duas maneiras:

  • De forma declarativa com Route3DElement (<gmp-route-3d>): adicione um componente da Web que solicita rotas da API Routes e renderiza polilinhas de rota em 3D, marcadores de origem e destino e um popover de resumo da rota.
  • De forma programática com os métodos auxiliares Route: chame Route.computeRoutes e transmita o trajeto para create3DPolylines, createWaypointMarkers e createPopover quando precisar de waypoints intermediários, máscaras de campo personalizadas ou estilos de polilinhas personalizados.

As duas abordagens estão disponíveis no canal v=beta da API Maps JavaScript. Para instruções sobre como carregar o canal Beta, consulte Controle de versões.

Pré-requisitos e faturamento

Antes de mostrar rotas em 3D, configure seu projeto do Google Cloud e ative as APIs Maps JavaScript e Routes nele. Carregue as bibliotecas maps3d e routes.

A renderização de <gmp-map-3d> é faturada em Dynamic 3D Maps (Immersive Maps Pro). Cada solicitação de trajeto feita por <gmp-route-3d> ou Route.computeRoutes é faturada em uma SKU Compute Routes da API Routes com base nos recursos solicitados:

Configuração Nível de SKU do Routes
Solicitações de rota padrão (TRAFFIC_UNAWARE ou modos de viagem WALKING, BICYCLING e TRANSIT sem polilinhas de trânsito) Compute Routes Essentials
routing-preference definido como traffic-aware ou traffic-aware-optimal com traffic-polylines-disabled ativado Compute Routes Pro
routing-preference definido como traffic-aware ou traffic-aware-optimal com polilinhas coloridas de trânsito ativadas (padrão quando uma preferência de trânsito é definida) Compute Routes Enterprise

Para detalhes sobre as SKUs, consulte Uso e faturamento da API Maps JavaScript.

Adicionar um trajeto em 3D usando HTML

Para mostrar um trajeto entre uma origem e um destino com o mínimo de código, aninhe <gmp-route-3d> em <gmp-map-3d> e adicione autofits-camera para que o mapa enquadre o trajeto automaticamente:

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

Substitua YOUR_API_KEY pela sua chave de API da Plataforma Google Maps.

O Route3DElement ajusta automaticamente as cores da polilinha e do popover de resumo ao esquema de cores claro ou escuro do <gmp-map-3d> pai e é compatível com os seguintes atributos e propriedades:

  • origin e destination: aceitam uma string de coordenadas "lat,lng", um nome de recurso de lugar, como "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", ou uma string de endereço. No JavaScript, essas propriedades também aceitam objetos LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral e Place.
  • travel-mode (travelMode): aceita driving (padrão), walking, bicycling ou transit (renderiza segmentos de linha de transporte público e caminhada multimodal).
  • routing-preference (routingPreference): aceita traffic-unaware, traffic-aware ou traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): desativa a coloração de polilinhas de velocidade do trânsito em rotas que consideram o trânsito para que a solicitação seja faturada no Compute Routes Pro, em vez do Compute Routes Enterprise.
  • departure-time (departureTime): aceita uma string de carimbo de data/hora ISO 8601 em HTML, como "2027-03-15T16:00:00Z", ou um objeto Date em JavaScript.
  • autofits-camera (autofitsCamera): enquadra o trajeto carregado na janela de visualização do <gmp-map-3d>.

Processar eventos de trajeto e ler dados de trajeto

O Route3DElement envia gmp-load quando uma rota termina de ser renderizada e gmp-error se o cálculo da rota falha ou retorna zero rotas. Depois que gmp-load é acionado, é possível ler as propriedades computadas routes, fallbackInfo e 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.');
});

Quando usar os métodos auxiliares de rota em vez de gmp-route-3d

<gmp-route-3d> renderiza o trajeto principal entre uma única origin e destination com o estilo padrão de marcador e polilinha. Use Route.computeRoutes com os métodos auxiliares 3D quando precisar de waypoints intermediários, seleção de rotas alternativas, máscaras de campo de resposta personalizadas ou estilos personalizados de polilinhas e marcadores.

Personalizar a renderização de trajetos em 3D com a classe Route

Para fluxos de trabalho de trajeto 3D personalizados, chame Route.computeRoutes e renderize a instância Route retornada em <gmp-map-3d> usando os métodos auxiliares 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>

Substitua YOUR_API_KEY pela sua chave de API da Plataforma Google Maps.

Inclua os campos obrigatórios em ComputeRoutesRequest.fields para cada método auxiliar chamado:

  • create3DPolylines: solicite 'path' ou 'legs' para polilinhas padrão, 'path' e 'legs' quando travelMode for 'TRANSIT' ou 'speedPaths' com extraComputations: ['TRAFFIC_ON_POLYLINE'] para polilinhas coloridas de acordo com o trânsito. Transmita RoutePolyline3DOptions para personalizar polylineOptions ou definir trafficPolylinesDisabled.
  • createWaypointMarkers: solicite 'path' em fields. Cria marcadores de origem e destino (Marker3DElement por padrão ou MarkerElement, MarkerInteractiveElement ou Marker3DInteractiveElement quando especificado com markerClass em CreateWaypointMarkersOptions). Os waypoints intermediários não são gerados por esse método.
  • createPopover: solicite 'path' e 'localizedValues' (além de 'legs' para trajetos de transporte público) para fixar um resumo PopoverElement no meio do caminho do trajeto.

Próximas etapas