Produk atau fitur ini bersifat Eksperimental (pra-GA). Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Penawaran Pra-GA tercakup dalam Persyaratan Khusus Layanan Google Maps Platform. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Menangani data perjalanan

Saat Anda mengambil data perjalanan, backend Anda akan menerima payload JSON yang menjelaskan progres perjalanan pengemudi. Urai payload ini untuk memantau perjalanan, memperbarui sistem pengiriman, dan menafsirkan status perjalanan saat ini untuk menentukan langkah berikutnya bagi pengemudi saat mereka melanjutkan perjalanan atau saat perjalanan berakhir.

Membaca payload data

Google Maps atau Waze mengirim payload data perjalanan ke server Navigation Connect saat pengemudi mulai menavigasi, secara berkala di sepanjang rute (setiap 60 detik secara default), dan saat pengemudi tiba di tujuan. Setiap pesan JSON berisi data perjalanan yang relevan, termasuk koordinat pengemudi yang disesuaikan dengan jalan, jarak yang ditempuh, dan perkiraan waktu tiba (ETA).

Contoh kode berikut menunjukkan payload data perjalanan saat pengemudi memulai navigasi untuk perjalanan dari King's Cross ke Central St. Giles.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

Memantau status perjalanan aktif

Untuk mengonfirmasi awal yang berhasil dan memantau progres, evaluasi kolom status di setiap payload.

Status	Deskripsi
`NEW`	Perjalanan dibuat, tetapi pengemudi belum mulai menavigasi.
`ENROUTE`	Pengemudi secara aktif menavigasi ke tujuan. Gunakan status ini untuk mengonfirmasi bahwa perjalanan diautentikasi dan dimulai dengan sukses.

Menangani perhentian yang ditambahkan

Pengemudi dapat menambahkan perhentian ke rute mereka selama navigasi. Jika mereka melakukannya, Navigation Connect akan menetapkan kolom execution.stopAddedInRoute ke true dalam payload data JSON. Navigation Connect API terus melacak pengemudi menuju tujuan awal. Metrik seperti perkiraan waktu tiba (ETA), jarak, dan durasi meningkat untuk menyertakan perhentian yang ditambahkan.

Perilaku untuk menambahkan perhentian bergantung pada aplikasi navigasi dan sesuai dengan fungsi standarnya:

Google Maps: Pengemudi dapat menambahkan beberapa perhentian ke rute mereka.
Waze: Pengemudi hanya dapat menambahkan satu perhentian. Jika pengemudi mencoba menambahkan perhentian lain, Waze akan meminta mereka untuk memulai sesi navigasi baru, bukan menambahkan perhentian ke rute saat ini.

Anda tidak perlu menyesuaikan input backend untuk mendukung fitur ini.

Memecahkan masalah autentikasi dan masalah awal

Jika Anda tidak menerima status ENROUTE, kemungkinan terjadi error autentikasi. Penyebab umumnya mencakup parameter API yang salah dieja atau token perjalanan yang telah habis masa berlakunya. Periksa waktu habis masa berlaku token dalam respons CreateTrip awal Anda.

Jika status tidak berubah dari NEW menjadi ENROUTE, perangkat pengemudi mungkin mencegah autentikasi. Navigation Connect tidak mengirim pesan error untuk kasus ini. Pastikan hal berikut:

Pengemudi telah menginstal Waze versi 5.15.5 atau yang lebih baru, atau Google Maps versi 26.14 atau yang lebih baru.
Pengemudi tidak menggunakan Android Auto atau Apple CarPlay.
Pengemudi memiliki koneksi internet aktif.

Menangani data rute yang tersisa (khusus Waze)

Jika Anda telah mengaktifkan pelaporan rute yang tersisa selama pembuatan perjalanan, backend Anda akan menerima polyline rute aktif dan kondisi lalu lintas real-time dari lokasi pengemudi saat ini ke tujuan akhir mereka.

Anda dapat menyerap dan memproses data ini untuk mendukung beberapa fitur di aplikasi Anda, termasuk contoh berikut:

Mendukung peta pelacakan langsung: Merender polyline rute yang tersisa di peta web atau seluler yang dapat dilihat pelanggan untuk memberikan visibilitas ke perjalanan pengemudi.
Meningkatkan akurasi ETA: Menggabungkan polyline yang disesuaikan dengan jalan dan kecepatan interval lalu lintas untuk meningkatkan prediksi kedatangan logistik atau pengiriman internal.
Menganalisis kepatuhan perutean: Membandingkan geometri rute yang tersisa dengan rute pengiriman yang diharapkan untuk menilai kepatuhan pengemudi.

Navigation Connect menampilkan detail rute yang tersisa di kolom execution.remainingRoute, baik Anda mengirim permintaan GetTrip atau menerima pembaruan berbasis peristiwa menggunakan Google Cloud Pub/Sub. Namun, cara payload memformat dan menyusun data ini bergantung pada metode pengambilan yang Anda gunakan.

Metode `GetTrip`

Saat Anda memanggil metode GetTrip, format respons untuk polyline bergantung pada parameter routePolylineFormat yang Anda tentukan dalam permintaan. Untuk mengetahui informasi selengkapnya, lihat Menyesuaikan format polyline.

Untuk semua format polyline, Navigation Connect menampilkan lalu lintas sebagai daftar terpisah objek SpeedReadingInterval di kolom execution.remainingRoute.trafficInformation. Objek ini memetakan kategori lalu lintas ke indeks polyline menggunakan nilai berikut:

startPolylinePointIndex: Indeks awal interval lalu lintas pada polyline.
endPolylinePointIndex: Indeks akhir interval lalu lintas.
speed: Kategori lalu lintas untuk segmen ini: NORMAL, SLOW, atau TRAFFIC_JAM.

Pembaruan Google Cloud Pub/Sub

Saat Anda mengambil data perjalanan dengan Pub/Sub, pembaruan akan selalu menampilkan data rute yang tersisa dalam GeoJSON terpadu FeatureCollection di kolom execution.remainingRoute.

Format ini menggabungkan geometri polyline dengan kecepatan lalu lintas secara langsung, sehingga Anda tidak perlu memetakan indeks secara manual.

Melihat contoh payload Pub/Sub

Contoh kode berikut menunjukkan struktur GeoJSON yang ditampilkan di kolom execution.remainingRoute dalam objek updatedTrip dari pesan Pub/Sub:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

Mengoptimalkan ukuran payload

Karena array koordinat berukuran besar, menyertakan data rute yang tersisa dalam pesan Pub/Sub dapat meningkatkan ukuran payload secara signifikan (hingga 13–14 KB per pesan). Jika Anda menerima pembaruan frekuensi tinggi, volume ini dapat meningkatkan beban pemrosesan backend dan biaya penggunaan.

Untuk mengoptimalkan streaming, gunakan parameter pubsubFieldMask dalam objek TripConfig selama pembuatan perjalanan untuk mengecualikan kolom yang besar. Untuk mengetahui detailnya, lihat Konfigurasi opsional.

Menangani status akhir perjalanan

Saat pengemudi mencapai tujuan atau berhenti menavigasi, payload akan menampilkan salah satu status akhir berikut. Gunakan status ini untuk memicu langkah berikutnya yang sesuai di aplikasi Anda.

Status	Deskripsi	Tindakan yang disarankan
`ARRIVED`	Pengemudi mencapai tujuan.	Periksa `remainingDistanceMeters`. Jika pengemudi parkir di dekat tujuan, tetapi tidak di koordinat yang tepat, pertimbangkan untuk memberikan petunjuk arah jalan kaki di aplikasi Anda.
`SUSPENDED`	Pengemudi keluar dari navigasi belokan demi belokan secara manual sebelum tiba di tujuan. Karena Google Maps atau Waze tidak otomatis mengembalikan pengemudi ke aplikasi Anda saat mereka keluar dari sesi lebih awal, pengemudi harus mengetuk tombol kembali secara manual. Catatan: Jika pengemudi menggunakan tombol kembali untuk beralih kembali ke aplikasi Anda tanpa keluar dari sesi navigasi aktif, status perjalanan akan tetap `ENROUTE`. Untuk mengetahui informasi selengkapnya, lihat Menangani peralihan aplikasi di tengah perjalanan.	Untuk membantu pengemudi menyelesaikan perjalanan, bandingkan `execution.location` dengan tujuan. Jika jarak masih ada, berikan tombol atau link untuk melanjutkan perjalanan atau beralih ke mode jalan kaki.
`FAILED`	Error teknis mengganggu koneksi. Hal ini terjadi jika aplikasi tidak dapat menghitung rute atau peringatan keselamatan muncul. Pengemudi mungkin masih menavigasi, tetapi Anda tidak akan menerima pembaruan.	Kembali ke pelacakan status manual di aplikasi Anda.
`CLIENT_ERROR`	Status ini muncul karena salah satu alasan berikut: Pengemudi mencabut izin. Pengemudi menggunakan platform yang tidak didukung, seperti Android Auto atau Apple CarPlay. Aplikasi Anda menggunakan kembali token perjalanan untuk perjalanan dengan tujuan yang berbeda. Pengemudi berada di Amerika Serikat kapan saja selama perjalanan, tetapi aplikasi Anda tidak mengaktifkan berbagi data di Amerika Serikat saat Anda memverifikasi aplikasi selama penyiapan.	Kembali ke pelacakan status manual di aplikasi Anda.