Membuat rute & PWT kendaraan besar

Untuk siapa panduan ini: Baca panduan ini jika Anda adalah developer yang membangun layanan untuk perencanaan dan pelaksanaan perjalanan menggunakan truk atau kendaraan besar lainnya. Kasus penggunaan yang relevan mencakup penghitungan waktu dan jarak perjalanan, penghitungan perkiraan waktu tiba, atau pembuatan rute yang akan digunakan oleh aplikasi navigasi.

Cakupan panduan ini: Panduan ini membahas cara menggunakan Routes API dengan Large Vehicle Routing untuk meminta rute, jarak perjalanan, perkiraan waktu perjalanan, dan ETA yang memperhitungkan atribut spesifik kendaraan besar, seperti truk komersial atau bus penumpang.

Untuk mengetahui informasi tentang cara melakukan komputasi tingkat armada untuk kendaraan besar menggunakan Route Optimization API, lihat Dokumentasi Perutean Truk Route Optimization API.

Yang akan Anda pelajari

Anda akan mempelajari cara melakukan hal berikut:

  • Buat permintaan perutean yang valid.
  • Tentukan profil kendaraan untuk kendaraan di dunia nyata Anda, menggunakan dimensi, berat, dan karakteristik lainnya.
  • Menafsirkan respons, termasuk token rute dan tanda peringatan keselamatan perjalanan.

Prasyarat

  1. Project Google Cloud Anda harus dibuat dan Routes API harus diaktifkan.
  2. Project Anda harus disediakan untuk Perutean Kendaraan Besar. Hubungi perwakilan Google Anda untuk menyelesaikan langkah ini.

Batasan

Sebelum memulai, Anda harus mengetahui batasan dan persyaratan berikut.

  • Ketersediaan Geografis: Perutean kendaraan besar hanya tersedia di 48 negara bagian Amerika Serikat yang berdekatan.
  • Perutean kendaraan besar adalah penawaran tahap Pratinjau. Pengemudi tidak boleh hanya mengandalkan rute yang ditampilkan oleh API ini agar aman atau sesuai hukum. Rute tidak dijamin sesuai untuk kendaraan, dan mengikutinya dapat membuat pengemudi menghadapi bahaya seperti jembatan rendah atau jalan yang melarang kendaraan besar.
  • Rute upaya terbaik. Dalam beberapa kasus, API tidak dapat menemukan rute yang sepenuhnya mematuhi pembatasan perjalanan. Sebagai gantinya, rute "upaya terbaik" yang mungkin masih melintasi area terlarang akan ditampilkan. Respons Routes API dengan jelas menandai rute ini di kolom routeRestrictionsPartiallyIgnored. Rencanakan rute Anda dengan cermat dalam kasus ini, idealnya menggunakan data sumber lain. Jangan menggunakan rute yang ditandai sebagai satu-satunya sumber tepercaya untuk perencanaan atau navigasi.
  • Fitur yang Tidak Didukung: Meskipun kami berupaya menghadirkan lebih banyak fungsi ke penawaran ini, perutean kendaraan besar tidak mendukung hal berikut:
    • Harga tol truk
    • Batas kecepatan
    • Perutean untuk bahan berbahaya radioaktif
  • Batas Penggunaan: Semua permintaan tunduk pada batas kueri per detik (QPS) standar.

Membangun permintaan rute truk

Untuk mendapatkan rute truk, Anda mengirim permintaan HTTPS ke endpoint Routes API dengan parameter tertentu yang menjelaskan kendaraan Anda.

Endpoint

Anda dapat menggunakan dua endpoint untuk perutean truk:

  • computeRoutes: Menghitung satu rute antara satu titik awal dan satu tujuan.
  • computeRouteMatrix: Menghitung jarak dan durasi untuk matriks asal dan tujuan, tetapi tidak menampilkan polyline rute.

Parameter permintaan utama

Dalam isi permintaan, Anda harus menyertakan hal berikut:

  • travelMode: Tetapkan nilai ini ke TRUCK.
  • routingPreference: Tetapkan nilai ini ke TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: Objek ini berisi objek vehicleInfo tempat Anda menentukan atribut kendaraan. Objek vehicleInfo dijelaskan secara mendetail di bawah.

Menentukan profil kendaraan

Untuk mengirim permintaan, Anda harus memberikan isi permintaan dengan objek vehicleInfo yang menjelaskan kendaraan Anda. Anggap informasi ini sebagai spesifikasi yang cocok dengan detail fisik kendaraan Anda di dunia nyata. Layanan ini memerlukan detail ini untuk menampilkan rute yang mempertimbangkan batasan jalan berdasarkan atribut kendaraan Anda.

Pengukuran kendaraan

Berikan berat kendaraan dalam kilogram dan dimensi kendaraan dalam milimeter, seperti yang ditunjukkan oleh nama kolom. Misalnya, tinggi total harus diberikan dalam milimeter (totalHeightMm). Karena dimensi truk sering kali dinyatakan dalam kaki atau meter, hal ini mungkin memerlukan konversi unit.

Konversi dari satuan imperial ke metrik

Saat mengonversi dari satuan imperial, selalu pertimbangkan dimensi kendaraan spesifik Anda bersama dengan batas ukuran jalan dan jalan layang standar. Hal ini bisa menjadi sangat penting dengan nilai pecahan. Bergantung pada ukuran kendaraan sebenarnya, pembulatan nilai pecahan ke atas dapat menyebabkan perutean yang terlalu ketat untuk kendaraan.

Contoh:

  • Lebar: Banyak trailer AS memiliki lebar 8' 6", yang dikonversi menjadi 2.590,8 mm. Pembulatan hingga 2.591 mm akan menunjukkan bahwa kendaraan lebih besar dari 8' 6", yang akan mengklasifikasikannya sebagai kendaraan berukuran besar di jalanan AS. Hal ini kemudian akan menghasilkan rute yang dihitung sesuai dengan batasan yang berbeda secara signifikan dari yang dimaksud.
  • Tinggi: Rute yang melewati bawah jembatan setinggi 11 kaki tidak akan cocok untuk truk gandeng biasa dengan tinggi 13,5 kaki. Namun, truk boks yang lebih kecil dengan panjang sekitar 10 kaki dapat melewati jalan bawah tanah. Oleh karena itu, Anda harus menentukan atribut kendaraan secara akurat.

Diagram yang menggambarkan dimensi truk terhadap dimensi jalan bawah tanah

Berikut adalah cuplikan kode yang menunjukkan contoh objek vehicleInfo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

Kolom objek vehicleInfo

Tabel berikut menunjukkan semua definisi kendaraan dan muatan yang dapat Anda kirim dengan permintaan.

Kolom Deskripsi Catatan / Nilai
totalHeightMm Tinggi maksimum kendaraan. Dalam milimeter, dibulatkan ke bawah. Lihat Konversi dari satuan imperial ke metrik untuk mengetahui detail selengkapnya tentang pembulatan.
totalWidthMm Lebar maksimum kendaraan. Dalam milimeter, dibulatkan ke bawah.
totalLengthMm Total panjang gabungan kendaraan dan trailer. Dalam milimeter, dibulatkan ke bawah.
totalWeightKg Bobot total kendaraan (termasuk trailer dan muatan). Dalam kilogram, dibulatkan ke bawah.
totalAxleCount Jumlah total gandar pada kendaraan dan trailer. Persis.
trailerInfo (Opsional) Array objek, satu untuk setiap cuplikan. Dihilangkan untuk kendaraan tanpa trailer, seperti truk boks.
hazardousGoodsTypes (Opsional) Array yang menentukan bahan berbahaya apa pun yang ada di dalam pesawat. BAHAN PELEDAK, GAS, MUDAH TERBAKAR, DAPAT TERBAKAR, ORGANIK, RACUN, KOROSIF, BAHAYA_ASPIRASI, BAHAYA_LINGKUNGAN, LAINNYA

Menggunakan mask kolom

Untuk hasil terbaik, sertakan header X-Goog-FieldMask dalam permintaan Anda untuk menentukan secara tepat kolom yang Anda inginkan dalam respons. Masker kolom mengurangi latensi dan memastikan Anda menerima kolom saran penting. Setidaknya, selalu sertakan routes.travelAdvisory.routeRestrictionsPartiallyIgnored dalam mask kolom, karena ini menunjukkan apakah rute memiliki satu atau beberapa batasan yang berlaku untuk kendaraan Anda.

Untuk mengetahui detail selengkapnya tentang FieldMask dengan Routes API, lihat artikel ini.

Jalan Tol

Untuk memilih rute bebas tol, tentukan avoidTolls di properti routeModifiers permintaan. Untuk mengetahui informasi selengkapnya tentang pengubah rute, lihat Menentukan fitur rute yang harus dihindari.

Menentukan avoidTolls tidak menjamin rute bebas pulsa dalam respons. Dalam beberapa kasus, jalan tol diperlukan untuk melakukan perjalanan antara asal dan tujuan. Jika Anda menyertakan routes.warnings dalam fieldmask permintaan Routes API, rute yang berisi jalan tol akan diberi anotasi yang sesuai dalam kolom ini.

Contoh permintaan curl lengkap

Berikut adalah permintaan curl lengkap untuk truk semi-trailer biasa. Contoh ini mencakup endpoint, header, dan isi permintaan.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Menafsirkan respons computeRoutes

Permintaan yang berhasil ke Routes API akan menampilkan objek respons JSON yang berisi satu atau beberapa kemungkinan rute.

Kolom respons utama

  • Geometri rute yang dienkode: routes.polyline. Hal ini dapat digunakan untuk merender rute di peta.
  • Perkiraan durasi perjalanan: routes.duration (dalam detik). Durasi perjalanan perutean kendaraan besar menggunakan model baru yang dilatih berdasarkan kecepatan perjalanan yang diamati dari truk sebenarnya di jaringan jalan. Waktu ini juga dapat digunakan untuk menghitung perkiraan waktu tiba dengan menambahkan perkiraan durasi perjalanan ke perkiraan waktu keberangkatan.
  • Total jarak rute: routes.distanceMeters (dalam meter).
  • Token rute: routes.routeToken. Ini adalah token non-transparan yang merepresentasikan rute yang dihitung secara tepat. Anda meneruskan token ini ke Navigation SDK untuk memastikan pengemudi ditampilkan rute khusus truk yang sama. Untuk mengetahui detail selengkapnya tentang cara melakukannya, tinjau panduan Menyediakan navigasi belokan demi belokan.

Memeriksa tanda keamanan rute

Saat Anda mendapatkan respons, hal pertama yang harus Anda lakukan adalah memeriksa tanda keamanan rute. Jika rute yang diberikan berisi satu atau beberapa batasan yang membuatnya tidak sesuai untuk kendaraan, Anda akan menemukan kolom travelAdvisory.routeRestrictionsPartiallyIgnored disetel ke true.

Kolom ini berfungsi sebagai tanda untuk menjawab pertanyaan, "Apakah rute ini ditandai karena berpotensi menimbulkan masalah?"

  • false(atau tidak disertakan dalam respons): Rute tidak ditandai. Sistem menemukan rute yang diyakini sepenuhnya mematuhi parameter yang Anda berikan dalam permintaan.
  • true: Rute ditandai. Sistem tidak dapat menemukan rute yang sepenuhnya sesuai dan telah menampilkan rute "upaya terbaik" yang mungkin tidak aman atau legal. Rute ini harus digunakan dengan sangat hati-hati.

Contoh: Respons computeRoutes

Ini adalah contoh respons untuk permintaan yang ditunjukkan di atas. Perhatikan bahwa dalam objek travelAdvisory, tanda routeRestrictionsPartiallyIgnored tidak disertakan. Hal ini menunjukkan bahwa rute tidak ditandai dan diyakini sepenuhnya mematuhi profil kendaraan.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Mendapatkan matriks rute truk

Untuk menghitung waktu perjalanan untuk banyak potensi perjalanan sekaligus, gunakan endpoint computeRouteMatrix untuk perencanaan tingkat tinggi guna membandingkan waktu dan jarak perjalanan antara banyak tempat asal dan tujuan secara efisien. Misalnya, Anda dapat menggunakannya untuk menemukan truk terdekat dengan lokasi pengambilan baru. Setelah mengidentifikasi asal kendaraan yang ingin Anda gunakan untuk tujuan Anda, Anda dapat mengeluarkan permintaan computeRoutes untuk mendapatkan detail rute dan token rute untuk kendaraan yang diusulkan.

Untuk menggunakan computeRouteMatrix, Anda menentukan vehicleInfo dalam setiap objek asal.

Contoh permintaan

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Contoh respons

Respons adalah array yang setiap objeknya berisi durasi dan distanceMeters untuk satu pasangan asal-tujuan.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Langkah berikutnya