Menangani data perjalanan

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:

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_trip yang 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:
  • 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 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:
  • Pengemudi mencabut izin.
  • Pengemudi menggunakan platform yang tidak didukung, seperti Android Auto atau Apple CarPlay.
  • Aplikasi Anda menggunakan kembali token perjalanan di berbagai 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.