Menampilkan rute di peta 3D

Developer Wilayah Ekonomi Eropa (EEA)

Anda dapat menghitung dan merender rute pada elemen <gmp-map-3d> dengan dua cara:

  • Secara deklaratif dengan Route3DElement (<gmp-route-3d>): Tambahkan komponen web yang meminta rute dari Routes API dan merender polyline rute 3D, penanda asal dan tujuan, serta popover ringkasan rute.
  • Secara terprogram dengan metode bantuan Route: Panggil Route.computeRoutes dan teruskan rute ke create3DPolylines, createWaypointMarkers, dan createPopover saat Anda memerlukan titik jalan perantara, masker kolom kustom, atau gaya polyline kustom.

Kedua pendekatan ini tersedia di saluran v=beta Maps JavaScript API. Untuk mengetahui petunjuk tentang cara memuat saluran beta, lihat Pembuatan versi.

Prasyarat dan penagihan

Sebelum menampilkan rute 3D, siapkan project Google Cloud Anda dan aktifkan Maps JavaScript API dan Routes API untuk project tersebut. Muat library maps3d dan routes.

Rendering <gmp-map-3d> ditagih dalam Peta 3D Dinamis (Immersive Maps Pro). Setiap permintaan rute yang dibuat oleh <gmp-route-3d> atau Route.computeRoutes ditagih berdasarkan SKU Compute Routes Routes API berdasarkan fitur yang diminta:

Konfigurasi Tingkat SKU Rute
Permintaan rute default (mode perjalanan TRAFFIC_UNAWARE, atau WALKING, BICYCLING, dan TRANSIT tanpa polyline lalu lintas) Compute Routes Essentials
routing-preference ditetapkan ke traffic-aware atau traffic-aware-optimal dengan traffic-polylines-disabled diaktifkan Compute Routes Pro
routing-preference ditetapkan ke traffic-aware atau traffic-aware-optimal dengan polyline berwarna lalu lintas diaktifkan (default saat preferensi berbasis lalu lintas ditetapkan) Compute Routes Enterprise

Untuk mengetahui detail SKU, lihat Penggunaan dan Penagihan Maps JavaScript API.

Menambahkan rute 3D menggunakan HTML

Untuk menampilkan rute antara tempat asal dan tujuan dengan kode minimal, tempatkan <gmp-route-3d> di dalam <gmp-map-3d> dan tambahkan autofits-camera agar peta membingkai rute secara otomatis:

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

Ganti YOUR_API_KEY dengan kunci API Google Maps Platform Anda.

Route3DElement otomatis mencocokkan warna polyline dan popover ringkasannya dengan skema warna terang atau gelap dari <gmp-map-3d> induk, serta mendukung atribut dan properti berikut:

  • origin dan destination: Menerima string koordinat "lat,lng", nama resource tempat seperti "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", atau string alamat. Di JavaScript, properti ini juga menerima objek LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral, dan Place.
  • travel-mode (travelMode): Menerima driving (default), walking, bicycling, atau transit (merender segmen rute jalan kaki dan transportasi umum multimodal).
  • routing-preference (routingPreference): Menerima traffic-unaware, traffic-aware, atau traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): Menonaktifkan pewarnaan polyline kecepatan lalu lintas pada rute yang memperhitungkan lalu lintas sehingga permintaan ditagih berdasarkan Compute Routes Pro, bukan Compute Routes Enterprise.
  • departure-time (departureTime): Menerima string stempel waktu ISO 8601 dalam HTML seperti "2027-03-15T16:00:00Z", atau objek Date di JavaScript.
  • autofits-camera (autofitsCamera): Membingkai rute yang dimuat dalam area pandang <gmp-map-3d>.

Menangani peristiwa rute dan membaca data rute

Route3DElement mengirimkan gmp-load saat rute selesai dirender dan gmp-error jika komputasi rute gagal atau menampilkan nol rute. Setelah gmp-load diaktifkan, Anda dapat membaca properti routes, fallbackInfo, dan geocodingResults yang dihitung:

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

Kapan harus menggunakan metode bantuan Rute, bukan gmp-route-3d

<gmp-route-3d> merender rute utama antara satu origin dan destination dengan gaya penanda dan polyline default. Gunakan Route.computeRoutes dengan metode bantuan 3D saat Anda memerlukan titik jalan perantara, pemilihan rute alternatif, mask kolom respons kustom, atau gaya polyline dan penanda kustom.

Menyesuaikan rendering rute 3D dengan class Route

Untuk alur kerja rute 3D kustom, panggil Route.computeRoutes dan render instance Route yang ditampilkan ke <gmp-map-3d> menggunakan metode bantuan 3D-nya:

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

Ganti YOUR_API_KEY dengan kunci API Google Maps Platform Anda.

Sertakan kolom wajib diisi di ComputeRoutesRequest.fields untuk setiap metode helper yang Anda panggil:

  • create3DPolylines: Minta 'path' atau 'legs' untuk polyline standar, 'path' dan 'legs' jika travelMode adalah 'TRANSIT', atau 'speedPaths' dengan extraComputations: ['TRAFFIC_ON_POLYLINE'] untuk polyline berwarna lalu lintas. Teruskan RoutePolyline3DOptions untuk menyesuaikan polylineOptions atau menetapkan trafficPolylinesDisabled.
  • createWaypointMarkers: Minta 'path' di fields. Membuat penanda asal dan tujuan (Marker3DElement secara default, atau MarkerElement, MarkerInteractiveElement, atau Marker3DInteractiveElement jika ditentukan dengan markerClass di CreateWaypointMarkersOptions). Titik jalan perantara tidak dihasilkan oleh metode ini.
  • createPopover: Minta 'path' dan 'localizedValues' (ditambah 'legs' untuk rute transportasi umum) untuk menempatkan ringkasan PopoverElement di tengah jalur rute.

Langkah berikutnya