Bagikan melalui

Praktik terbaik untuk layanan Azure Maps Route

  • Artikel

Route Directions dan Route Matrix API di layanan Rute Azure Maps dapat digunakan untuk menghitung perkiraan waktu kedatangan (ETAs) untuk setiap rute yang diminta. API rute mempertimbangkan faktor-faktor seperti informasi lalu lintas real-time dan data lalu lintas historis, seperti kecepatan jalan umum pada tanggal dan waktu yang diminta. API memasukkan rute terpendek atau tercepat yang tersedia untuk beberapa tujuan secara berurutan atau dalam urutan yang dioptimalkan, berdasarkan waktu atau jarak. Pengguna juga dapat meminta rute dan detail khusus untuk pejalan kaki, pengendara sepeda, dan kendaraan komersial seperti truk. Artikel ini membahas praktik terbaik untuk memanggil layanan Rute Azure Maps, termasuk cara:

  • Pilih antara Route Directions API dan Matrix Routing API
  • Meminta waktu perjalanan historis dan terprediksi, berdasarkan data lalu lintas real-time dan historis
  • Meminta detail rute, seperti waktu dan jarak, untuk seluruh rute dan setiap kaki rute
  • Meminta rute untuk kendaraan komersial, seperti truk
  • Meminta informasi lalu lintas di sepanjang rute, seperti kemacetan dan informasi tol
  • Meminta rute yang terdiri dari satu atau beberapa pemberhentian (titik arah)
  • Optimalkan rute satu atau beberapa pemberhentian untuk mendapatkan urutan terbaik saat mengunjungi setiap perhentian (titik arah)
  • Optimalkan rute alternatif menggunakan titik pendukung. Misalnya, menawarkan rute alternatif yang melewati stasiun pengisian kendaraan listrik.
  • Menggunakan layanan Rute dengan Azure Maps Web SDK

Prasyarat

Untuk informasi selengkapnya tentang cakupan layanan Rute, lihat Cakupan Perutean.

Anda dapat menggunakan lingkungan pengembangan API apa pun seperti Postman atau bruno untuk menjalankan sampel permintaan HTTP yang ditunjukkan dalam artikel ini atau untuk membangun panggilan REST.

Pilih antara Route Directions dan Matrix Routing

Route Directions API mengembalikan instruksi termasuk waktu perjalanan dan koordinat untuk jalur rute. Route Matrix API memungkinkan Anda menghitung waktu dan jarak perjalanan untuk serangkaian rute yang ditentukan oleh lokasi asal dan tujuan. Untuk setiap asal yang diberikan, Matrix API menghitung biaya (waktu perjalanan dan jarak) perutean dari asal tersebut ke setiap tujuan yang diberikan. API ini memungkinkan Anda menentukan parameter seperti waktu keberangkatan yang diinginkan, waktu kedatangan, dan jenis kendaraan, seperti mobil atau truk. Mereka semua menggunakan data lalu lintas real-time atau prediktif yang sesuai untuk mengembalikan rute yang paling optimal.

Pertimbangkan untuk memanggil Route Directions API jika skenario Anda adalah:

  • Minta rute mengemudi terpendek atau tercepat antara dua lokasi atau lebih dikenal, untuk mendapatkan waktu kedatangan yang tepat untuk kendaraan pengiriman Anda.
  • Minta panduan rute terperinci, termasuk geometri rute, untuk memvisualisasikan rute di peta
  • Dengan daftar lokasi pelanggan, hitung rute yang paling singkat untuk mengunjungi lokasi setiap pelanggan dan kembali lagi ke tempat asal. Skenario ini umumnya dikenal sebagai masalah penjual keliling. Anda dapat melewati hingga 150 titik arah (berhenti) dalam satu permintaan.
  • Kirim batch kueri ke Route Directions Batch API hanya menggunakan satu panggilan API.

Pertimbangkan untuk memanggil Matrix Routing API jika skenario Anda adalah:

  • Hitung waktu atau jarak perjalanan antara sekumpulan asal dan tujuan. Misalnya, Anda memiliki 12 pengemudi dan Anda perlu menemukan pengemudi terdekat yang tersedia untuk mengambil pengiriman makanan dari restoran.
  • Urutkan rute potensial berdasarkan jarak atau waktu perjalanan mereka yang sebenarnya. Matrix API hanya mengembalikan waktu dan jarak perjalanan untuk setiap kombinasi asal dan tujuan.
  • Data klaster berdasarkan waktu atau jarak perjalanan. Misalnya, perusahaan Anda memiliki 50 karyawan, temukan semua karyawan yang tinggal dalam waktu 20 menit berkendara dari kantor Anda.

Berikut adalah perbandingan untuk menunjukkan beberapa kemampuan Route Directions dan Matrix API:

Azure Maps API Jumlah kueri maksimal dalam permintaan Hindari area Perutean truk dan kendaraan listrik Pengoptimalan Titik Arah (Waypoints) dan Penjual Keliling Titik pendukung
Dapatkan Arah Rute 1 ✔ ✔
Post Route Directions 1 ✔ ✔ ✔ ✔
Post Route Directions Batch 700 ✔ ✔
Matriks Rute Pos 700 ✔

Untuk mempelajari selengkapnya tentang kemampuan perutean kendaraan listrik, lihat tutorial kami tentang cara merutekan kendaraan listrik menggunakan Azure Notebooks dengan Python.

Meminta data historis dan real-time

Secara default, layanan Rute mengasumsikan mode perjalanan adalah mobil dan waktu keberangkatan sekarang. Ini mengembalikan rute berdasarkan kondisi lalu lintas real-time kecuali permintaan perhitungan rute menentukan sebaliknya. Faktor mesin perutean memperbaiki pembatasan lalu lintas tergantung waktu, seperti 'Belokan kiri tidak diizinkan antara pukul 16:00 hingga 18:00'. Penutupan jalan, seperti pengerjaan jalan, dipertimbangkan kecuali Anda secara khusus meminta rute yang mengabaikan lalu lintas langsung saat ini. Untuk mengabaikan lalu lintas saat ini, atur traffic ke false permintaan API Anda.

Nilai perhitungan rute travelTimeInSeconds mencakup keterlambatan karena lalu lintas. Ini dihasilkan dengan menggunakan data waktu perjalanan saat ini dan bersejarah, ketika waktu keberangkatan diatur ke sekarang. Jika waktu keberangkatan Anda ditetapkan di masa mendatang, API akan mengembalikan waktu perjalanan yang diprediksi berdasarkan data historis.

Jika Anda menyertakan parameter computeTravelTimeFor=all dalam permintaan Anda, maka elemen ringkasan dalam respons memiliki bidang berikut termasuk kondisi lalu lintas historis:

Elemen Deskripsi
noTrafficTravelTimeInSeconds Estimasi waktu tempuh dihitung seolah-olah tidak ada keterlambatan pada rute karena kondisi lalu lintas, misalnya, karena kemacetan
historicTrafficTravelTimeInSeconds Estimasi waktu perjalanan dihitung menggunakan data lalu lintas historis yang bergantung pada waktu
liveTrafficIncidentsTravelTimeInSeconds Estimasi waktu perjalanan dihitung menggunakan data kecepatan real-time

Bagian berikutnya menunjukkan cara melakukan panggilan ke Route API menggunakan parameter yang dibahas.

Kueri Sampel

Dalam contoh pertama di bawah waktu keberangkatan diatur ke masa depan, pada saat penulisan.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=51.368752,-0.118332:51.385426,-0.128929&travelMode=car&traffic=true&departAt=2025-03-29T08:00:20&computeTravelTimeFor=all

Respons berisi elemen ringkasan, seperti contoh berikut. Karena waktu keberangkatan diatur ke masa depan, trafficDelayInSeconds value adalah nol. Nilai travelTimeInSeconds dihitung menggunakan data lalu lintas historis yang bergantung pada waktu. Jadi, dalam hal ini, nilai travelTimeInSeconds sama dengan nilai historicTrafficTravelTimeInSeconds.

"summary": {
    "lengthInMeters": 2131,
    "travelTimeInSeconds": 248,
    "trafficDelayInSeconds": 0,
    "departureTime": "2025-03-29T08:00:20Z",
    "arrivalTime": "2025-03-29T08:04:28Z",
    "noTrafficTravelTimeInSeconds": 225,
    "historicTrafficTravelTimeInSeconds": 248,
    "liveTrafficIncidentsTravelTimeInSeconds": 248
},

Kueri Sampel

Dalam contoh berikutnya, kami memiliki permintaan perutean real-time, di mana waktu keberangkatan sekarang. Ini tidak secara eksplisit ditentukan dalam URL karena itu adalah nilai default.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=47.6422356,-122.1389797:47.6641142,-122.3011268&travelMode=car&traffic=true&computeTravelTimeFor=all

Respons berisi ringkasan seperti yang ditunjukkan dalam contoh berikut. Karena kemacetan , nilai trafficDelaysInSeconds lebih besar dari nol. Ini juga lebih besar dari historicTrafficTravelTimeInSeconds.

"summary": {
    "lengthInMeters": 16637, 
    "travelTimeInSeconds": 2905, 
    "trafficDelayInSeconds": 1604, 
    "departureTime": "2020-02-28T01:00:20+00:00",
    "arrivalTime": "2020-02-28T01:48:45+00:00", 
    "noTrafficTravelTimeInSeconds": 872, 
    "historicTrafficTravelTimeInSeconds": 1976, 
    "liveTrafficIncidentsTravelTimeInSeconds": 2905 
},

Meminta detail rute dan kaki

Secara default, layanan Rute mengembalikan array koordinat. Respons berisi koordinat yang membentuk jalur dalam daftar bernama points. Respon rute juga mencakup jarak dari awal rute dan perkiraan waktu yang berlalu. Nilai-nilai ini dapat digunakan untuk menghitung kecepatan rata-rata untuk seluruh rute.

Gambar berikut menunjukkan points elemen.

Elemen titik

Perluas point elemen untuk melihat daftar koordinat untuk jalur:

Elemen titik yang diperluas

Route Directions API mendukung berbagai format instruksi yang dapat digunakan dengan menentukan parameter instructionsType. Untuk memformat instruksi agar pemrosesan komputer lebih mudah, gunakan instruksiType=coded. Gunakan instruksiType=tagged untuk menampilkan instruksi sebagai teks untuk pengguna. Selain itu, instruksi dapat diformat sebagai teks di mana beberapa elemen instruksi ditandai, dan instruksi disajikan dengan pemformatan khusus. Untuk informasi selengkapnya, lihat daftar tipe instruksi yang didukung.

Saat instruksi diminta, respons akan mengembalikan elemen baru bernama guidance. Elemen guidance ini menyimpan dua bagian informasi: petunjuk belokan demi belokan dan instruksi yang dirangkum.

Tipe instruksi

instructions Elemen ini menyimpan petunjuk belokan demi belokan untuk perjalanan, dan instructionGroups instruksi yang telah dirangkum. Setiap ringkasan instruksi mencakup segmen perjalanan yang dapat mencakup beberapa jalan. API dapat mengembalikan detail untuk bagian rute. seperti, rentang koordinat kemacetan atau kecepatan lalu lintas saat ini.

Instruksi belokan demi belokan

Instruksi yang dirangkum

Meminta rute untuk kendaraan komersial

Azure Maps Routing API mendukung perutean kendaraan komersial, yang mencakup perutean truk komersial. API mempertimbangkan batas yang ditentukan. Seperti, tinggi dan berat kendaraan, dan jika kendaraan membawa kargo berbahaya. Misalnya, jika kendaraan yang membawa mudah terbakar, mesin perutean menghindari terowongan tertentu yang berada di dekat daerah perumahan.

Kueri Sampel

Contoh permintaan di bawah ini meminta rute untuk truk komersial. Truk ini membawa bahan limbah berbahaya kelas 1.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass1&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

Route API mengembalikan arah yang mengakomodasi dimensi truk dan limbah berbahaya. Anda dapat membaca instruksi rute dengan memperluas guidance elemen.

Truk dengan limbah berbahaya kelas 1

Kueri Sampel

Mengubah Kelas Hazmat AS, dari kueri di atas, menghasilkan rute yang berbeda untuk mengakomodasi perubahan ini.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass9&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

Respons berikut adalah untuk truk yang membawa bahan berbahaya kelas 9, yang kurang berbahaya daripada bahan berbahaya kelas 1. Saat Anda memperluas guidance elemen untuk membaca petunjuk arah, perhatikan bahwa petunjuk arahnya tidak sama. Ada lebih banyak instruksi rute untuk truk yang membawa bahan berbahaya kelas 1.

Truk dengan kelas 9 hazwaste

Meminta informasi lalu lintas di sepanjang rute

Dengan Azure Maps Route Direction API, pengembang dapat meminta detail untuk setiap jenis bagian dengan menyertakan sectionType parameter dalam permintaan. Misalnya, Anda dapat meminta informasi kecepatan untuk setiap segmen kemacetan lalu lintas. Lihat daftar nilai untuk kunci sectionType untuk mempelajari tentang berbagai detail yang dapat Anda minta.

Kueri Sampel

Kueri berikut ini mengatur sectionType ke traffic. Ini meminta bagian yang berisi informasi lalu lintas dari Seattle ke San Diego.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&sectionType=traffic&query=47.6062,-122.3321:32.7157,-117.1611

Responsnya berisi bagian-bagian yang cocok untuk lalu lintas di sepanjang koordinat yang diberikan.

Bagian lalu lintas

Opsi ini dapat digunakan untuk mewarnai bagian saat merender peta, seperti pada Gambar berikut:

Cuplikan layar memperlihatkan bagian berwarna yang dirender di peta.

Menghitung dan mengoptimalkan rute multihenti

Azure Maps saat ini menyediakan dua bentuk pengoptimalan rute:

  • Pengoptimalan berdasarkan jenis rute yang diminta, tanpa mengubah urutan titik arah. Untuk informasi selengkapnya, lihat RouteType.

  • Optimasi penjual keliling, yang mengubah urutan titik arah untuk mendapatkan pesanan terbaik untuk mengunjungi setiap pemberhentian

Untuk perutean multi-stop, hingga 150 titik arah dapat ditentukan dalam satu permintaan rute. Lokasi koordinat awal dan akhir bisa sama, seperti halnya dengan pulang pergi. Tetapi Anda perlu menyediakan setidaknya satu titik arah lagi untuk membuat perhitungan rute. Titik arah dapat ditambahkan ke kueri di antara koordinat asal dan tujuan.

Jika Anda ingin mengoptimalkan urutan terbaik untuk mengunjungi titik arah yang diberikan, maka Anda perlu menentukan computeBestOrder=true. Skenario ini juga dikenal sebagai masalah optimalisasi penjual keliling.

Kueri Sampel

Kueri berikut ini meminta jalur untuk enam titik arah, dengan computeBestOrder parameter diatur ke false. Ini juga merupakan nilai default untuk computeBestOrder parameter.

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=false&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

Responnya menjelaskan panjang jalur menjadi 140.851 meter, dan bahwa dibutuhkan 9.991 detik untuk menempuh jalur itu.

Respons yang tidak dioptimalkan

Gambar berikut mengilustrasikan jalur yang dihasilkan dari kueri ini. Jalur ini adalah salah satu rute yang mungkin. Ini bukan jalur optimal berdasarkan waktu atau jarak.

Cuplikan layar memperlihatkan peta dengan rute Yang tidak dioptimalkan.

Urutan titik arah rute ini adalah: 0, 1, 2, 3, 4, 5, dan 6.

Kueri Sampel

Kueri berikut ini meminta jalur untuk enam titik arah yang sama, seperti pada sampel di atas. Kali ini, computeBestOrder parameter diatur ke true (pengoptimalan penjual keliling).

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=true&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

Responnya menggambarkan panjang jalur menjadi 91.814 meter, dan dibutuhkan 7.797 detik untuk menempuh jalur itu. Jarak tempuh dan waktu tempuh keduanya lebih rendah di sini karena API mengembalikan rute yang dioptimalkan.

Respons yang dioptimalkan

Gambar berikut mengilustrasikan jalur yang dihasilkan dari kueri ini.

Cuplikan layar memperlihatkan peta dengan rute yang dioptimalkan.

Rute optimal memiliki urutan titik arah berikut: 0, 5, 1, 2, 4, 3, dan 6.

Tip

Informasi pesanan titik arah yang dioptimalkan dari layanan Routing menyediakan serangkaian indeks. Ini mengecualikan asal dan indeks tujuan. Anda perlu meningkatkan nilai-nilai ini dengan 1 untuk memperhitungkan asalnya. Kemudian, tambahkan tujuan Anda ke akhir untuk mendapatkan daftar titik arah lengkap yang dipesan.

Menghitung dan bias rute alternatif menggunakan titik pendukung

Anda mungkin memiliki situasi di mana Anda ingin merekonstruksi rute untuk menghitung nol atau lebih rute alternatif untuk rute referensi. Misalnya, Anda dapat menampilkan rute alternatif pelanggan yang melewati toko ritel Anda. Dalam hal ini, Anda perlu bias lokasi menggunakan titik pendukung. Berikut adalah langkah-langkah untuk bias lokasi:

  1. Hitung rute apa adanya dan dapatkan jalur dari respons rute
  2. Gunakan jalur rute untuk menemukan lokasi yang diinginkan di sepanjang atau dekat jalur rute. Misalnya, Anda bisa menggunakan permintaan Point of Interest atau mengkueri data Anda sendiri di database Anda.
  3. Pesan lokasi berdasarkan jarak dari awal rute
  4. Tambahkan lokasi ini sebagai titik pendukung dalam permintaan rute baru ke Arah Rute Pos. Untuk mempelajari selengkapnya tentang titik pendukung, lihat dokumentasi Post Route Directions API.

Saat memanggil Arah Rute Pos, Anda dapat mengatur waktu penyimpangan minimum atau batasan jarak, bersama dengan titik pendukung. Gunakan parameter ini jika Anda ingin menawarkan rute alternatif, tetapi Anda juga ingin membatasi waktu perjalanan. Ketika batasan ini digunakan, rute alternatif mengikuti rute referensi dari titik asal untuk waktu atau jarak tertentu. Dengan kata lain, rute lain menyimpang dari rute referensi per kendala yang diberikan.

Gambar berikut adalah contoh penyajian rute alternatif dengan batas penyimpangan yang ditentukan untuk waktu dan jarak.

Cuplikan layar memperlihatkan peta dengan rute alternatif.

Menggunakan layanan Perutean di aplikasi web

Azure Maps Web SDK menyediakan modul Layanan. Modul ini adalah pustaka pembantu yang memudahkan penggunaan Azure Maps REST API di aplikasi web atau Node.js, menggunakan JavaScript atau TypeScript. Modul Layanan dapat digunakan untuk merender rute yang dikembalikan di peta. Modul secara otomatis menentukan API mana yang akan digunakan dengan permintaan GET dan POST.

Catatan

Penghentian Modul Layanan Azure Maps Web SDK

Modul Layanan Azure Maps Web SDK sekarang tidak digunakan lagi dan akan dihentikan pada 30/9/26. Untuk menghindari gangguan layanan, sebaiknya migrasi ke Azure Maps JavaScript REST SDK sebesar 30/9/26. Untuk informasi selengkapnya, lihat Panduan Pengembang JavaScript/TypeScript REST SDK (pratinjau).

Langkah berikutnya

Untuk mempelajari lebih lanjut, silakan lihat:

Layanan Azure Maps Route

Cara menggunakan modul Layanan

Tampilkan rute di peta

Paket npm Azure Maps