Layanan Posisi dan Trip

Halaman ini menjelaskan cara mengambil posisi kendaraan dan riwayat trip dengan Fleet API untuk audiens bisnis dan teknis.

Akronim dan Istilah

• API: Application Programming Interface.
• GPS: Global Positioning System.

Endpoint Mana yang Harus Digunakan?

Gunakan pemetaan ini saat pelanggan meminta data terkait lokasi:

• Semua posisi GPS / riwayat lengkap titik trip:
  • Get events for one vehicle
  • Get events for all vehicles
• Pelacakan berkelanjutan (tampilan armada near real-time):
  • Get vehicles status, location, fuel, odometer and more
• Lokasi awal dan akhir trip:
  • Get all trips
  • Get trips by registration

1) Semua Posisi GPS

Artinya

Mengambil event posisi historis dalam suatu periode untuk merekonstruksi di mana kendaraan pernah berada.

Endpoint Terbaik

• Satu kendaraan: Get events for one vehicle
• Semua kendaraan: Get events for all vehicles

Interpretasi Bisnis

• Gunakan untuk investigasi, trip replay, bukti keberadaan, dan audit operasional.
• Sumber terbaik saat pengguna meminta "semua titik" dalam jendela waktu tertentu.

Interpretasi untuk Developer

• Perlakukan event sebagai titik telemetri historis.
• Lakukan query berdasarkan jendela waktu dan pagination sesuai kebutuhan.
• Untuk periode panjang, lakukan fetch bertahap agar respons tidak terlalu besar.

2) Pelacakan Berkelanjutan (Near Real-Time)

Artinya

Menampilkan posisi kendaraan terbaru yang diketahui secara berkelanjutan, mirip peta armada live.

Endpoint Terbaik

• Get vehicles status, location, fuel, odometer and more

Interpretasi Bisnis

• Gunakan untuk operasi harian live dan pemantauan dispatcher.
• Pilihan terbaik untuk use case "kendaraan sekarang ada di mana?".

Interpretasi untuk Developer

• Implementasikan polling (misalnya setiap 10 sampai 30 detik) untuk memperbarui status terbaru.
• Ini adalah status polling near real-time, bukan websocket streaming feed.
• Kombinasikan dengan endpoint events saat dibutuhkan detail historis breadcrumb.

3) Riwayat Trip Lengkap

Artinya

Bergantung pada intent pelanggan, "riwayat trip" dapat berarti:

• Titik breadcrumb lengkap dari sebuah perjalanan, atau
• Ringkasan trip dengan lokasi awal dan akhir.

Pemilihan Endpoint

• Untuk titik breadcrumb trip lengkap: gunakan endpoint events.
• Untuk lokasi awal dan akhir level trip:
  • Get all trips
  • Get trips by registration

Interpretasi Bisnis

• Gunakan trips untuk pelaporan dan analisis KPI level trip.
• Gunakan events saat analis membutuhkan detail level jalur.

Interpretasi untuk Developer

• Trips adalah ringkasan data dan tidak boleh diperlakukan sebagai dataset titik rute yang lengkap.
• Bangun trip replay lengkap dari data events untuk interval waktu yang dipilih.

Pola Implementasi yang Direkomendasikan

Untuk sebagian besar aplikasi armada:

1. Poll endpoint status kendaraan untuk state peta saat ini.
2. Query endpoint events untuk route playback historis.
3. Query endpoint trips untuk pelaporan trip (awal/akhir dan konteks trip).