Saat Anda mengambil data perjalanan, backend Anda akan menerima payload JSON yang menjelaskan progres perjalanan pengemudi. Uraikan payload ini untuk memantau perjalanan, memperbarui sistem pengiriman, dan menafsirkan status perjalanan saat ini guna menentukan langkah berikutnya bagi pengemudi saat mereka melanjutkan atau saat perjalanan berakhir.
Membaca payload data
Google Maps atau Waze mengirimkan 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 yang disesuaikan dengan jalan, jarak yang ditempuh, dan perkiraan waktu tiba (ETA) pengemudi. Karena pembaruan ini mencerminkan rute aktif dan real-time pengemudi, rute tersebut mungkin berbeda dari rute yang telah dihitung sebelumnya oleh backend Anda (lihat FAQ).
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 keberhasilan memulai dan memantau progres, evaluasi kolom state di setiap payload.
| Status | Deskripsi |
|---|---|
NEW |
Perjalanan telah dibuat, tetapi pengemudi belum memulai navigasi. |
ENROUTE |
Pengemudi sedang aktif menavigasi ke tujuan. Gunakan status ini untuk mengonfirmasi bahwa perjalanan telah diautentikasi dan dimulai dengan berhasil. |
Menangani perhentian yang ditambahkan
Pengemudi dapat menambahkan perhentian ke rute mereka selama navigasi. Jika ya,
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 akan 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 memulai
Jika Anda tidak menerima status ENROUTE, kemungkinan terjadi error autentikasi. Penyebab umumnya mencakup parameter API yang salah eja atau token perjalanan yang sudah tidak berlaku. 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. Verifikasi hal berikut:
- Pengemudi telah menginstal Waze versi 5.15.5 atau yang lebih tinggi, atau Google Maps versi 26.14 atau yang lebih tinggi.
- Pengemudi tidak menggunakan Android Auto atau Apple CarPlay.
- Pengemudi memiliki koneksi internet yang aktif.
Menangani data rute yang tersisa
Jika Anda telah mengaktifkan pelaporan rute yang tersisa selama pembuatan perjalanan, backend Anda akan menerima polyline rute yang tersisa dan kondisi lalu lintas real-time dari lokasi pengemudi saat ini ke tujuan akhirnya. Pengemudi memerlukan Waze versi 5.20.0.2 atau yang lebih baru di Android, 5.20.0.1 atau yang lebih baru di iOS, atau Google Maps untuk Android versi 26.27 atau yang lebih baru.
Anda dapat menyerap dan memproses data ini untuk mendukung beberapa fitur dalam aplikasi Anda, termasuk contoh berikut:
- Mendukung peta pelacakan langsung: Render polyline rute yang tersisa di peta web atau seluler yang ditampilkan kepada pelanggan untuk memberikan visibilitas ke perjalanan pengemudi.
- Meningkatkan akurasi PWT: Gabungkan polyline yang dipaskan ke jalan dan kecepatan interval lalu lintas untuk meningkatkan prediksi kedatangan pengiriman atau logistik internal.
- Menganalisis kepatuhan pemilihan rute: Bandingkan geometri rute yang tersisa dengan rute pengiriman yang diharapkan untuk menilai kepatuhan pengemudi (lihat FAQ untuk mengetahui detail tentang alasan rute real-time dan yang telah dihitung sebelumnya mungkin berbeda).
Navigation Connect menampilkan detail rute yang tersisa di kolom
execution.remainingRoute,
baik Anda mengirim permintaan GetTrip maupun menerima update 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 traffic sebagai daftar objek
SpeedReadingInterval
terpisah di kolom
execution.remainingRoute.trafficInformation. Objek ini memetakan kategori traffic ke indeks polyline menggunakan nilai berikut:
startPolylinePointIndex: Indeks awal interval lalu lintas pada polyline.endPolylinePointIndex: Indeks akhir interval traffic.speed: Kategori traffic untuk segmen ini:NORMAL,SLOW, atauTRAFFIC_JAM.
Update Google Cloud Pub/Sub
Saat Anda mengambil data perjalanan dengan Pub/Sub,
update akan selalu menampilkan data rute yang tersisa dalam FeatureCollection GeoJSON terpadu di kolom
execution.remainingRoute.
Format ini menggabungkan geometri polyline dengan kecepatan lalu lintas secara langsung, sehingga tidak perlu memetakan indeks secara manual.
Lihat 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 update frekuensi tinggi, volume ini dapat meningkatkan beban pemrosesan backend dan biaya penggunaan.
Untuk mengoptimalkan streaming, gunakan parameter
pubsubFieldMask
di objek TripConfig
selama pembuatan perjalanan untuk mengecualikan kolom yang berat. Untuk mengetahui detailnya, lihat Konfigurasi opsional.
Menangani deviasi rute (khusus Waze)
Pengemudi memerlukan Waze versi 5.22 atau yang lebih baru.
Jika Anda telah mengaktifkan pelaporan deviasi rute selama pembuatan perjalanan, saat pengemudi keluar dari rute, API akan menampilkan metadata deviasi rute. Anda dapat mengakses data ini dengan cara berikut:
- On-demand: Panggil metode
GetTrip. Server mempertahankan status deviasi terakhir yang diketahui. - Real-time: Berlangganan ke Google Cloud Pub/Sub. Layanan ini memublikasikan
update deviasi menggunakan peristiwa
updated_tripyang ada dalam waktu 5 detik setelah deteksi.
Membaca payload deviasi
Objek last_route_deviation menyediakan metadata berikut untuk membantu Anda menganalisis peristiwa.
| Kolom | Jenis | Deskripsi |
|---|---|---|
location |
LatLng |
Koordinat lintang dan bujur tempat perangkat klien mencatat deviasi. |
source |
TriggerSource |
Alasan penyimpangan. Gunakan ini untuk menentukan apakah pengemudi melakukan
tindakan yang tidak terduga atau mengikuti panduan sistem:
|
client_timestamp |
Timestamp |
Waktu saat perangkat klien mendeteksi penyimpangan. |
server_timestamp |
Timestamp |
Waktu saat server memproses pembaruan deviasi. |
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 telah mencapai tujuan. | Centang remainingDistanceMeters. Jika pengemudi parkir
di sekitar, tetapi tidak pada koordinat yang tepat, pertimbangkan untuk memberikan rute
jalan kaki di aplikasi Anda. |
SUSPENDED |
Pengemudi keluar secara manual dari navigasi belokan demi belokan 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. |
Untuk membantu pengemudi menyelesaikan perjalanan mereka, bandingkan
execution.location dengan tujuan. Jika masih ada jarak yang harus ditempuh, sediakan 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 info terbaru. | Kembali ke pelacakan status manual di aplikasi Anda. |
CLIENT_ERROR |
Status ini muncul karena salah satu alasan berikut:
|
Kembali ke pelacakan status manual di aplikasi Anda. |