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 khusus 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 informasi kendaraan untuk kendaraan dunia nyata Anda, menggunakan dimensi, berat, dan karakteristik lainnya.
  • Menafsirkan respons, termasuk token rute dan tanda keamanan perjalanan.

Prasyarat

  1. Project Google Cloud Anda harus dibuat dan Routes API harus diaktifkan.
  2. Project Anda harus disediakan untuk Perutean Kendaraan Besar. Perutean kendaraan besar tersedia untuk sejumlah kecil pelanggan, hubungi kami untuk meminta akses

Batasan

Sebelum memulai, Anda harus mengetahui batasan dan persyaratan berikut.

  • Ketersediaan geografis: Perutean kendaraan besar tersedia di 48 negara bagian Amerika Serikat yang berdekatan (Tersedia Secara Umum) dan Jepang (Eksperimental). Fitur ini tidak tersedia di Alaska, Hawaii, atau wilayah AS.
  • Saran dan keselamatan pengemudi. 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 sumber tepercaya untuk perencanaan atau navigasi.
  • Fitur yang tidak didukung: Perutean kendaraan besar tidak mendukung hal berikut:
    • Harga tol truk
    • Batas kecepatan
    • Rute 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. Konsep dalam bagian ini berlaku untuk permintaan rute tunggal dan matriks rute.

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 parameter berikut untuk mengaktifkan perutean truk:

  • 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 atribut 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 tersebut 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.
  • Ketinggian: Rute yang melewati bawah jembatan setinggi 3,35 m tidak akan cocok untuk truk gandeng biasa dengan tinggi 4,11 m. 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

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. Tepat.
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 API Routes, rute yang berisi jalan tol akan diberi anotasi yang sesuai dalam kolom ini.

Perilaku pemilihan rute lainnya

Jika Anda menyetel travelMode ke TRUCK, API akan otomatis mengoptimalkan rute untuk kemampuan manuver kendaraan besar. Rute yang dibuat menghindari putar balik dan sangat lebih memilih jalan bebas hambatan dan jalan raya daripada jalan yang lebih kecil. Anda tidak perlu menetapkan parameter atau pengubah tambahan untuk mengaktifkan perilaku ini.

Menghitung satu rute dengan computeRoutes

Gunakan endpoint computeRoutes untuk menghitung rute khusus truk antara satu asal dan satu tujuan.

Contoh permintaan computeRoutes

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
      }]
    }
  }
}'

Contoh respons computeRoutes

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

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

Menafsirkan respons computeRoutes

Permintaan yang berhasil ke endpoint computeRoutes 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.
  • Estimasi 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 detailnya, lihat panduan Navigation SDK untuk Android atau iOS.
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 ada 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.

Menghitung matriks rute (computeRouteMatrix)

Gunakan endpoint computeRouteMatrix untuk membandingkan waktu perjalanan dan jarak 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 origin, bukan di root permintaan.

Contoh permintaan computeRouteMatrix

{
  "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 computeRouteMatrix

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