Membuat rute & PWT kendaraan besar

Target pembaca 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 Perutean Kendaraan Besar untuk meminta rute, jarak perjalanan, perkiraan waktu perjalanan, dan perkiraan waktu kedatangan (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 Pemilihan Rute Truk Route Optimization.

Yang akan Anda pelajari

Anda akan mempelajari cara melakukan hal berikut:

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

Prasyarat

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

Batasan

Sebelum memulai, Anda harus mengetahui batasan dan persyaratan berikut.

• Ketersediaan geografis: Pemilihan rute kendaraan besar tersedia di 48 negara bagian Amerika Serikat yang berdekatan (Ketersediaan 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 legal. Rute tidak dijamin sesuai untuk kendaraan, dan mengikutinya dapat mengekspos pengemudi pada 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" akan ditampilkan, yang mungkin masih melintasi area terlarang. 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 gunakan rute yang ditandai sebagai satu sumber tepercaya untuk perencanaan atau navigasi.
• Fitur yang tidak didukung: Pemilihan rute kendaraan besar tidak mendukung hal berikut:
  • Tarif tol truk
  • Batas kecepatan
  • Pemilihan rute untuk bahan berbahaya radioaktif
• Batas penggunaan: Semua permintaan tunduk pada batas kueri per detik (QPS) standar.

Membuat permintaan rute truk

Untuk mendapatkan rute truk, Anda mengirim permintaan HTTPS ke endpoint Routes API dengan parameter tertentu yang menjelaskan kendaraan Anda. Konsep di bagian ini berlaku untuk permintaan rute tunggal dan matriks rute.

Endpoint

Anda dapat menggunakan dua endpoint untuk pemilihan rute truk:

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

Parameter permintaan kunci

Dalam isi permintaan, Anda harus menyertakan parameter berikut untuk mengaktifkan pemilihan rute 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 mendeskripsikan kendaraan Anda. Anggap informasi ini sebagai spesifikasi yang sesuai dengan detail fisik kendaraan Anda di dunia nyata. Layanan ini memerlukan detail tersebut untuk menampilkan rute yang memperhitungkan pembatasan 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 dinyatakan dalam kaki atau meter, hal ini mungkin memerlukan konversi unit.

Konversi dari imperial ke metrik

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

Contoh:

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

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.

Menggunakan mask kolom

Untuk hasil terbaik, sertakan header X-Goog-FieldMask dalam permintaan Anda untuk menentukan dengan tepat kolom yang Anda inginkan dalam respons. Masker kolom mengurangi latensi dan memastikan Anda menerima kolom saran yang 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 tol dalam respons. Dalam beberapa kasus, penggunaan jalan tol diperlukan untuk melakukan perjalanan antara tempat asal dan tujuan. Jika Anda menyertakan routes.warnings dalam fieldmask permintaan API Routes, rute yang berisi jalan tol akan dianotasi sebagaimana mestinya dalam kolom ini.

Perilaku pemilihan rute lainnya

Jika Anda menetapkan travelMode ke TRUCK, API akan otomatis mengoptimalkan rute untuk kemampuan manuver kendaraan besar. Rute yang dihasilkan menghindari putar balik dan sangat memilih jalan antarnegara bagian 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 tempat 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

Berikut 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. Ini dapat digunakan untuk merender rute di peta.
• Estimasi durasi perjalanan: routes.duration (dalam detik). Durasi perjalanan pemilihan rute kendaraan besar menggunakan model baru yang dilatih berdasarkan kecepatan perjalanan yang diamati dari truk sebenarnya di jaringan jalan. Metode ini juga dapat digunakan untuk menghitung perkiraan waktu kedatangan (ETA) dengan menambahkan estimasi durasi perjalanan ke waktu keberangkatan yang diharapkan.
• Total jarak rute: routes.distanceMeters (dalam meter).
• Token rute: routes.routeToken. Ini adalah token non-transparan yang mewakili rute yang dihitung secara tepat. Anda meneruskan token ini ke Navigation SDK untuk memastikan pengemudi melihat rute khusus truk yang sama. Untuk mengetahui detailnya, lihat panduan Navigation SDK untuk Android atau iOS.

Memeriksa tanda keamanan rute

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

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

• false(atau dihilangkan dari 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 mematuhi aturan 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 dan jarak perjalanan secara efisien antara banyak tempat asal dan tujuan. Misalnya, Anda dapat menggunakannya untuk menemukan truk terdekat ke 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, tentukan 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

Responsnya 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

• Menyediakan navigasi belokan demi belokan: Pelajari cara menggunakan routeToken di Navigation SDK untuk Android atau iOS.
• Melakukan pengoptimalan tingkat armada: Gunakan Route Optimization API dengan Pemilihan Rute Kendaraan Besar.
• Referensi API: Untuk mengetahui daftar lengkap semua kemungkinan kolom dan nilai, lihat Referensi Routes API.