Menangani data perjalanan

Saat Anda mengambil data perjalanan Anda, backend Anda akan menerima payload JSON yang menjelaskan progres perjalanan pengemudi. Parse muatan 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 mengirimkan payload data perjalanan ke server Navigation Connect saat pengemudi mulai menggunakan navigasi, 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 pengemudi, jarak yang ditempuh, dan perkiraan waktu tiba (ETA). Karena pembaruan ini mencerminkan rute aktif pengemudi secara real-time, pembaruan ini mungkin berbeda dengan 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 dibuat, tetapi pengemudi belum mulai bernavigasi.
ENROUTE Pengemudi secara aktif melakukan navigasi ke tujuan. Gunakan status ini untuk mengonfirmasi bahwa perjalanan berhasil diautentikasi dan dimulai.

Menangani perhentian yang ditambahkan

Pengemudi dapat menambahkan perhentian ke rute mereka selama navigasi. Jika ya, Navigation Connect 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 bertambah untuk menyertakan perhentian tambahan.

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 memulai

Jika Anda tidak menerima status ENROUTE, kemungkinan terjadi error autentikasi. Penyebab umumnya mencakup parameter API yang salah eja atau token perjalanan yang 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. Verifikasi 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 yang tersisa 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 live: Merender 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 disesuaikan dengan jalan dan kecepatan interval lalu lintas untuk meningkatkan prediksi kedatangan pengiriman atau logistik internal.
  • Menganalisis kepatuhan perutean: 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 rute 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 format dan struktur payload 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:

Update Google Cloud Pub/Sub

Saat Anda mengambil data perjalanan dengan Pub/Sub, pembaruan selalu menampilkan data rute yang tersisa dalam GeoJSON FeatureCollection terpadu 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 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 berat. Untuk mengetahui detailnya, lihat Konfigurasi opsional.

Menangani penyimpangan rute (Khusus Waze)

Jika Anda telah mengaktifkan pelaporan penyimpangan rute selama pembuatan perjalanan, saat pengemudi keluar dari rute, API akan menampilkan metadata penyimpangan rute. Anda dapat mengakses data ini dengan cara berikut:

  • Sesuai permintaan: Panggil metode GetTrip. Server mempertahankan status penyimpangan terakhir yang diketahui.
  • Real-time: Berlangganan ke Google Cloud Pub/Sub. Layanan memublikasikan pembaruan penyimpangan menggunakan peristiwa updated_trip yang ada dalam waktu 5 detik setelah deteksi.

Membaca payload penyimpangan

Objek last_route_deviation memberikan metadata berikut untuk membantu Anda menganalisis peristiwa.

Kolom Jenis Deskripsi
location LatLng Koordinat lintang dan bujur tempat perangkat klien merekam penyimpangan.
source TriggerSource Alasan penyimpangan. Gunakan ini untuk menentukan apakah pengemudi melakukan tindakan yang tidak terduga atau mengikuti panduan sistem:
  • DRIVER_INITIATED_REROUTE: Pengemudi membuat pilihan aktif (misalnya, salah belok atau memilih jalur baru secara manual).
  • SYSTEM_INITIATED_REROUTE: Aplikasi navigasi menghitung rute baru (misalnya, karena perubahan kondisi lalu lintas atau penutupan jalan).
client_timestamp Timestamp Waktu saat perangkat klien mendeteksi penyimpangan.
server_timestamp Timestamp Waktu server memproses pembaruan penyimpangan.

Menangani status akhir perjalanan

Saat pengemudi mencapai tujuan atau berhenti bernavigasi, 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. Periksa remainingDistanceMeters. Jika pengemudi parkir di dekat 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. 		Untuk membantu pengemudi menyelesaikan perjalanan, bandingkan execution.location dengan tujuan. Jika jarak tetap ada, berikan tombol atau link untuk melanjutkan perjalanan atau beralih ke mode jalan kaki.
FAILED Terjadi error teknis yang mengganggu koneksi. Hal ini terjadi jika aplikasi tidak dapat menghitung rute atau peringatan keselamatan muncul. Pengemudi mungkin masih menggunakan navigasi, 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:
  • Pengemudi mencabut izin.
  • Pengemudi menggunakan platform yang tidak didukung, seperti Android Auto atau Apple CarPlay.
  • Aplikasi Anda menggunakan kembali token perjalanan di beberapa perjalanan terpisah. Misalnya, Navigation Connect menolak permintaan yang mengubah tujuan perjalanan atau memperbarui perjalanan yang telah selesai.
  • 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.