Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps Directions API

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Maps Directions API
  3. Buat kunci yang sesuai
Lanjutkan

Panduan Developer

Google Maps Directions API adalah layanan yang menghitung arah antar lokasi menggunakan permintaan HTTP.

Layanan ini juga tersedia sebagai bagian dari Google Maps JavaScript API sisi-klien, atau untuk penggunaan sisi-server dengan Java Client, Python Client, Go Client dan Node.js Client for Google Maps Services. Catatan: Batas penggunaan harian yang sama tetap berlaku bagaimana pun Anda menggunakan layanan. Permintaan per hari dihitung sebagai jumlah kueri sisi-klien dan sisi-server.

Dokumen ini ditujukan untuk developer situs web dan seluler yang ingin menghitung data arah dalam peta yang disediakan oleh salah satu Google Maps API. Dokumen ini menyediakan pengantar untuk menggunakan API dan materi referensi mengenai parameter yang tersedia.

Pengantar

Video ini mengilustrasikan penggunaan Google Maps Directions API untuk membantu orang menemukan jalan. Video ini berisi saran tentang mengatur proxy layanan web melalui server bila Anda menggunakan API dalam aplikasi seluler, untuk melindungi kunci API Anda.

Dengan Directions API, Anda bisa:

  • Menelusuri arah untuk beberapa moda transportasi, termasuk angkutan umum, mengemudi, berjalan atau bersepeda.
  • Mengembalikan arah multi-bagian dengan menggunakan serangkaian titik jalan.
  • Menetapkan tempat asal, tujuan dan titik jalan baik sebagai string teks (misalnya "Chicago, IL" atau "Darwin, NT, Australia") atau sebagai koordinat garis lintang/bujur, atau sebagai ID tempat.

Menghitung arah adalah tugas yang menyita waktu dan sumber daya. Bila memungkinkan, hitung alamat yang sudah diketahui sebelumnya (menggunakan layanan yang dijelaskan di sini) dan simpan hasilnya di cache sementara desain Anda.

Catatan: Layanan ini tidak dirancang untuk merespons masukan pengguna secara real-time. Untuk perhitungan arah dinamis (misalnya, dalam elemen antarmuka pengguna), lihat dokumentasi untuk Google Maps JavaScript API Layanan Directions.

Sebelum Anda memulai development dengan Directions API, periksa persyaratan autentikasi (Anda memerlukan kunci API) dan batas penggunaan API.

Permintaan Directions

Permintaan Google Maps Directions API mengambil bentuk berikut:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

dalam hal ini, outputFormat bisa berupa salah satu nilai berikut:

  • json (disarankan) menunjukkan keluaran dalam JavaScript Object Notation (JSON)
  • xml menunjukkan keluaran berupa XML

Catatan: URL harus dienkodekan dengan benar agar valid dan dibatasi hingga 8192 karakter untuk semua layanan web. Perhatikan batas ini saat membuat URL Anda.

HTTPS atau HTTP

Keamanan dianggap penting dan HTTPS disarankan kapan saja memungkinkan, khususnya untuk aplikasi yang berisi data pengguna sensitif, seperti lokasi pengguna, dalam permintaan. Dengan enkripsi HTTPS, aplikasi Anda menjadi lebih aman, dan lebih tahan terhadap aksi pengintaian atau perusakan.

Jika HTTPS tidak mungkin digunakan, untuk mengakses Google Maps Directions API melalui HTTP, gunakan:

http://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Parameter Permintaan

Beberapa parameter tertentu diperlukan sementara yang lainnya bersifat opsional. Sebagaimana standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&). Daftar parameter dan kemungkinan nilainya disebutkan di bawah ini.

Parameter yang diperlukan

  • origin — Alamat, nilai garis lintang/garis bujur tekstual, atau ID tempat asal yang ingin Anda hitung arahnya.
    • Jika Anda meneruskan sebuah alamat, layanan Directions akan melakukan geocode atas string itu dan mengubahnya menjadi koordinat garis lintang/bujur untuk menghitung arah. Koordinat ini mungkin berbeda dengan yang dikembalikan oleh Google Maps Geocoding API, misalnya pintu masuk bangunan dan bukan pusatnya.
      origin=24+Sussex+Drive+Ottawa+ON
    • Jika Anda meneruskan koordinat, koordinat akan digunakan tanpa diubah untuk menghitung arah. Pastikan tidak ada spasi di antara nilai garis lintang dan garis bujur.
      origin=41.43206,-81.38992
    • ID Tempat harus diawali dengan place_id:. Nilai ini hanya bisa ditetapkan jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Anda bisa mengambil ID tempat dari Google Maps Geocoding API dan Google Places API (termasuk Place Autocomplete). Untuk contoh menggunakan ID tempat dari Place Autocomplete, lihat Place Autocomplete dan Directions. Untuk informasi selengkapnya tentang ID tempat, lihat ringkasan ID tempat.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination — Alamat, nilai garis lintang/garis bujur tekstual, atau ID tempat tujuan yang ingin Anda hitung arahnya. Opsi untuk parameter destination sama dengan opsi untuk parameter origin yang dijelaskan di atas.
  • key — Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan manajemen kuota. Pelajari cara mendapatkan kunci.

    Catatan: Pelanggan Google Maps APIs Premium Plan bisa memilih menggunakan kunci API atau ID klien dan tanda tangan digital yang valid, di permintaan Directions Anda. Dapatkan informasi selengkapnya tentang parameter autentikasi untuk pelanggan Premium Plan.

Parameter opsional

  • mode (default-nya adalah driving) — Menetapkan moda transportasi yang akan digunakan saat menghitung arah. Nilai yang valid dan detail permintaan lain ditetapkan dalam Mode Perjalanan.
  • waypoint — Menetapkan larik titik jalan. Titik jalan mengubah rute dengan mengarahkannya melalui lokasi yang ditetapkan. Titik jalan ditetapkan sebagai koordinat garis lintang/garis bujur, polyline yang dienkodekan, ID tempat, atau alamat yang akan di-geocode. Polyline yang dienkodekan harus diawali dengan enc: dan diikuti oleh titik dua (:). ID Tempat harus diawali dengan place_id:. Nilai ini hanya bisa ditetapkan jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Titik jalan hanya didukung untuk arah mengemudi, berjalan, dan bersepeda. Untuk informasi selengkapnya tentang titik jalan, lihat panduan untuk titik jalan di bawah ini.
  • alternative — Jika disetel ke true, menetapkan bahwa layanan Directions mungkin menyediakan lebih dari satu rute alternatif dalam respons. Perhatikan, memberikan alternatif rute bisa meningkatkan waktu respons dari server.
  • avoid — Menunjukkan rute yang dihitung harus menghindari fitur yang ditandai. Parameter ini mendukung argumen berikut:
    • tolls menunjukkan rute yang dihitung harus menghindari jalan/jembatan tol.
    • highways menunjukkan rute yang dihitung harus menghindari jalan raya.
    • ferries menunjukkan rute yang dihitung harus menghindari penyeberangan feri.
    • indoor menunjukkan rute yang dihitung harus menghindari tangga dalam ruangan untuk arah berjalan dan arah angkutan umum. Hanya permintaan yang menyertakan kunci API atau ID klien Google Maps APIs Premium Plan yang akan menerima tangga dalam ruangan secara default.
    Untuk informasi selengkapnya, lihat Pembatasan Rute di bawah ini.
  • language — Bahasa yang digunakan untuk mengembalikan hasil.
    • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung sehingga daftar ini mungkin tidak lengkap.
    • Jika language tidak diberikan, API akan berusaha menggunakan bahasa yang dipilih sebagaimana ditetapkan dalam header Accept-Language atau bahasa bawaan domain asal permintaan dikirim.
    • API akan melakukan yang terbaik untuk menyediakan alamat yang bisa dibaca oleh pengguna dan penduduk setempat. Untuk mencapai sasaran ini, API akan mengembalikan alamat dalam bahasa lokal, dan ditransliterasikan menjadi skrip yang bisa dibaca oleh pengguna jika perlu, dengan memperhatikan bahasa yang dipilih. Semua alamat lain dikembalikan dalam bahasa yang dipilih. Semua komponen alamat dikembalikan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa yang dipilih, API menggunakan bahasa terdekat yang sesuai.
    • Bahasa yang dipilih berpengaruh kecil terhadap serangkaian hasil yang dipilih API untuk dikembalikan, dan urutan pengembaliannya. Geocoder menerjemahkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk tipe jalan, atau sinonim yang mungkin valid dalam satu bahasa tetapi tidak valid dalam bahasa lainnya. Misalnya, utca dan tér adalah sinonim untuk jalan dalam bahasa Hungaria.
  • unit — Menetapkan sistem satuan yang akan digunakan saat menampilkan hasil. Nilai yang valid ditetapkan dalam Sistem Satuan di bawah ini.
  • region — Menetapkan kode region, ditetapkan sebagai nilai yang berisi dua karakter ccTLD ("top-level domain"). (Untuk informasi selengkapnya, lihat Mencondongkan Region di bawah ini.)
  • arrival_time — Menetapkan waktu kedatangan yang diinginkan untuk arah angkutan umum, dalam detik sejak tengah malam, 1 Januari 1970 UTC. Anda bisa menetapkan salah satu dari departure_time atau arrival_time, tetapi tidak keduanya sekaligus. Perhatikan, arrival_time harus ditetapkan berupa integer.
  • departure_time — Menetapkan waktu keberangkatan yang diinginkan. Anda bisa menetapkan waktu sebagai integer dalam detik sejak tengah malam, 1 Januari 1970 UTC. Atau, Anda bisa menetapkan nilai now, yang menyetel waktu keberangkatan ke waktu saat ini (dikoreksi ke detik terdekat). Waktu keberangkatan bisa ditetapkan dalam dua hal:
    • Untuk permintaan yang mode perjalanannya adalah angkutan umum: Anda juga bisa menetapkan salah satu dari departure_time atau arrival_time. Jika tidak ada waktu yang ditetapkan, default departure_time adalah sekarang (yaitu, waktu keberangkatan default adalah waktu saat ini).
    • Untuk permintaan yang mode perjalanannya adalah mengemudi: Anda bisa menetapkan departure_time untuk menerima durasi rute dan perjalanan (bidang respons: duration_in_traffic) yang mempertimbangkan kondisi lalu lintas. Opsi ini hanya tersedia jika permintaan berisi kunci API yang valid, atau tanda tangan dan ID klien Google Maps APIs Premium Plan yang valid. departure_time harus disetel ke waktu saat ini atau waktu mendatang. Tidak boleh waktu yang sudah lewat.
  • traffic_model (default-nya adalah best_guess) — Menetapkan asumsi yang akan digunakan saat menghitung waktu dalam lalu lintas. Setelan ini memengaruhi nilai yang dikembalikan di bidang duration_in_traffic dalam respons, yang berisi prediksi waktu dalam lalu lintas berdasarkan rata-rata historis. Parameter traffic_model hanya bisa ditetapkan untuk arah mengemudi yang permintaannya menyertakan departure_time, dan hanya jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Nilai yang tersedia untuk parameter ini adalah:
    • best_guess (default) menunjukkan duration_in_traffic yang dikembalikan harus berupa perkiraan waktu tempuh terbaik berdasarkan informasi riwayat kondisi lalu lintas dan lalu lintas saat ini. Lalu lintas saat ini menjadi kian penting bila departure_time semakin dekat ke waktu sekarang.
    • optimistic menunjukkan duration_in_traffic yang dikembalikan lebih lama dari waktu tempuh sesungguhnya di hari-hari biasa, meskipun hari-hari tertentu dengan kondisi lalu lintas yang buruk mungkin melebihi nilai ini.
    • optimistic menunjukkan duration_in_traffic yang dikembalikan harus lebih singkat dari waktu tempuh sesungguhnya di hari biasa, meskipun hari-hari tertentu dengan kondisi lalu lintas yang baik bisa lebih cepat dari nilai ini.
    Nilai default best_guess akan memberikan prediksi yang paling berguna untuk sebagian besar kasus penggunaan. Prediksi waktu tempuh best_guess mungkin lebih pendek dari optimistic, atau, lebih lama dari pessimistic karena cara model prediksi best_guess mengintegrasikan informasi lalu lintas langsung.
  • transit_mode — Menetapkan satu atau beberapa mode angkutan umum yang disukai. Parameter ini hanya bisa ditetapkan untuk arah angkutan umum, dan hanya jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Parameter ini mendukung argumen berikut:
    • bus menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan bus.
    • subway menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta bawah tanah.
    • train menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api.
    • tram menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan trem dan kereta ringan.
    • rail menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api, trem, kereta ringan, dan kereta bawah tanah. Ini sama dengan transit_mode=train|tram|subway.
  • transit_routing_preference — Menetapkan preferensi untuk rute angkutan umum. Dengan menggunakan parameter ini, Anda dapat membias opsi yang dikembalikan, daripada menerima rute default terbaik yang dipilih oleh API. Parameter ini hanya bisa ditetapkan untuk arah angkutan umum, dan hanya jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Parameter ini mendukung argumen berikut:
    • less_walking menunjukkan rute yang sudah dihitung akan mengutamakan jumlah berjalan kaki yang terbatas.
    • fewer_transfers menunjukkan rute yang sudah dihitung akan mengutamakan jumlah ganti angkutan yang terbatas.

Contoh Permintaan Arah

Permintaan berikut mengembalikan arah mengemudi dari Toronto, Ontario ke Montreal, Quebec.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

Dengan mengubah parameter mode dan avoid, permintaan awal bisa dimodifikasi guna mengembalikan arah untuk perjalanan bersepeda melewati pemandangan indah yang menghindari jalan raya utama.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

Permintaan berikut akan menelusuri arah angkutan umum dari Brooklyn, New York ke Queens, New York. Permintaan ini tidak menetapkan departure_time, sehingga waktu keberangkatan default adalah waktu saat ini:

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

Permintaan berikut berisi waktu keberangkatan spesifik.

Catatan: Dalam contoh ini, waktu keberangkatan ditetapkan 30 Juli 2012 pukul 09:45 pagi. Untuk menghindari kesalahan, Anda harus mengubah parameter ke waktu mendatang sebelum mengirimkan permintaan.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

Permintaan berikut mengembalikan arah mengemudi dari Glasgow, UK ke Perth, UK menggunakan ID tempat.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

Mode Perjalanan

Saat menghitung arah, Anda bisa menetapkan mode transportasi yang akan digunakan. Secara default, arah dihitung sebagai arah driving. Mode perjalanan berikut ini telah didukung:

  • driving (default) menunjukkan arah mengemudi standar yang menggunakan jaringan jalan raya.
  • walking meminta arah berjalan melalui jalur pejalan kaki & trotoar (bila tersedia).
  • bicycling meminta arah bersepeda melalui jalur sepeda & jalan yang disukai (bila tersedia).
  • transit meminta arah melalui rute angkutan umum (bila tersedia). Jika menyetel mode ke transit, Anda juga bisa menetapkan departure_time atau arrival_time. Jika tidak ada waktu yang ditetapkan, default departure_time adalah sekarang (yaitu, waktu keberangkatan default adalah waktu saat ini). Anda juga bisa menyertakan transit_mode dan/atau transit_routing_preference.

Catatan: Kadang-kadang arah berjalan dan bersepeda tidak menyertakan jalur pejalan kaki atau jalur bersepeda yang jelas, sehingga arah akan menampilkan warnings dalam hasil yang dikembalikan yang harus Anda tampilkan kepada pengguna.

Titik jalan

Saat menghitung rute menggunakan Google Maps Directions API, Anda juga bisa menetapkan titik jalan untuk arah mengemudi, berjalan atau bersepeda. Titik jalan tidak tersedia untuk arah angkutan umum. Anda bisa menggunakan titik jalan untuk menghitung rute melalui lokasi tambahan, di mana rute yang dikembalikan menyertakan persinggahan di setiap titik jalan yang diberikan.

Menetapkan titik jalan dalam parameter waypoints.

  • Anda bisa memberikan satu atau beberapa lokasi yang dipisahkan dengan karakter pipa (|), dalam bentuk alamat, koordinat garis lintang/bujur, atau ID tempat:
    • Jika Anda meneruskan sebuah alamat, layanan Directions akan melakukan geocode atas string itu dan mengubahnya menjadi koordinat garis lintang/bujur untuk menghitung arah. Koordinat ini mungkin berbeda dengan yang dikembalikan oleh Google Maps Geocoding API, misalnya pintu masuk bangunan dan bukan pusatnya.
    • Jika Anda meneruskan koordinat garis lintang/bujur, koordinat ini akan digunakan tanpa diubah untuk menghitung arah. Pastikan tidak ada spasi di antara nilai garis lintang dan garis bujur.
    • Jika Anda memberikan ID tempat, Anda harus mengawalinya dengan place_id. Anda hanya bisa menetapkan ID tempat jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan. Anda bisa mengambil ID tempat dari Google Maps Geocoding API dan Google Places API (termasuk Place Autocomplete). Untuk contoh menggunakan ID tempat dari Place Autocomplete, lihat Place Autocomplete dan Directions. Untuk informasi selengkapnya tentang ID tempat, lihat ringkasan ID tempat.
  • Atau, Anda bisa memberikan serangkaian koordinat yang dienkodekan menggunakan Algoritme Polyline yang Dienkodekan. Ini sangat berguna jika Anda memiliki titik jalan dalam jumlah besar, karena URL sangat pendek saat menggunakan polyline yang dienkodekan.
    • Polyline yang dienkodekan harus diawali dengan enc: dan diikuti oleh titik dua (:). Misalnya: waypoints=enc:gfo}EtohhU:
    • Anda juga bisa menyertakan beberapa polyline yang dienkodekan, yang dipisahkan dengan karakter pipa (|). Misalnya: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

URL berikut membuat permintaan Directions untuk rute antara Boston, MA dan Concord, MA dengan persinggahan di Charlestown dan Lexington, dalam urutan itu:

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&key=YOUR_API_KEY

Untuk setiap titik jalan dalam permintaan, respons arah menyertakan entri tambahan dalam larik legs guna memberikan detail yang sesuai untuk segmen perjalanan itu.

Jika ingin memengaruhi rute menggunakan titik jalan tanpa menambahkan persinggahan, tambahkan awalan via: pada titik jalan tersebut. Titik jalan yang diberi awalan via: tidak akan menambahkan entri ke larik legs, namun akan mengarahkan perjalanan melalui titik jalan yang diberikan.

URL berikut memodifikasi permintaan sebelumnya yang perjalanannya diarahkan melewati Lexington tanpa berhenti:

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|via:Lexington,MA&key=YOUR_API_KEY

Awalan via: sangat efektif saat membuat rute sebagai respons terhadap pengguna yang menyeret titik jalan pada peta. Hal itu memungkinkan pengguna melihat bagaimana tampilan rute akhir secara real-time dan membantu memastikan titik-titik jalan tersebut ditempatkan di lokasi yang bisa diakses oleh Google Maps Directions API.

URL berikut meminta titik jalan menggunakan koordinat garis lintang/bujur:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Berikut adalah permintaan yang sama, menggunakan polyline yang dienkodekan:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

Optimalkan titik jalan Anda

Secara default, layanan Directions menghitung rute melalui titik jalan yang diberikan dalam urutan tertentu. Atau, Anda bisa meneruskan optimize:true sebagai argumen pertama dalam parameter waypoints untuk memungkinkan layanan Directions mengoptimalkan rute yang disediakan dengan menata ulang titik jalan dalam urutan yang lebih efisien. (Optimalisasi ini merupakan aplikasi dari masalah salesman yang sedang bepergian.) Waktu tempuh adalah faktor utama yang dioptimalkan, namun faktor lain seperti jarak, jumlah belokan, dan sebagainya mungkin akan diperhitungkan saat memutuskan rute yang paling efisien. Semua titik jalan harus merupakan persinggahan untuk layanan Directions guna mengoptimalkan rutenya.

Jika Anda memerintahkan layanan Directions untuk mengoptimalkan urutan titik jalan, maka urutannya akan dikembalikan dalam bidang waypoint_order di dalam objek routes. Bidang waypoint_order mengembalikan nilai yang berbasis nol.

Contoh berikut menghitung rute perjalanan darat dari Adelaide, Australia Selatan ke setiap region penghasil wine utama Australia Selatan dengan menggunakan optimalisasi rute.

https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&key=YOUR_API_KEY

Pemeriksaan rute yang dihitung akan menunjukkan rute tersebut dihitung menggunakan urutan titik jalan berikut:

"waypoint_order": [ 1, 0, 2, 3 ]

Pembatasan

Arah bisa dihitung dengan mengikuti pembatasan tertentu. Pembatasan ditunjukkan melalui penggunaan parameter avoid, dan sebuah argumen ke parameter itu yang menunjukkan pembatasan untuk avoid. Pembatasan berikut ini telah didukung:

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

Bisa saja meminta rute yang menghindari kombinasi tol, jalan raya dan feri dengan meneruskan kedua pembatasan itu ke parameter avoid. Misalnya: avoid=tolls|highways|ferries.

Catatan: penambahan pembatasan tidak menghalangi rute berisi fitur yang dibatasi; cuma mencondongkan hasil ke rute yang lebih disukai.

Sistem Satuan

Hasil Directions berisi text dalam bidang distance yang bisa ditampilkan kepada pengguna untuk menunjukkan jarak "langkah" tertentu pada rute tersebut. Secara default, teks ini menggunakan sistem satuan pada negara atau region asal.

Misalnya, rute dari "Chicago, IL" ke "Toronto, ONT" akan menampilkan hasil dalam mil, sedangkan rute terbalik akan menampilkan hasil dalam kilometer. Anda bisa mengesampingkan sistem satuan ini dengan menetapkannya secara eksplisit dalam parameter units permintaan, dengan meneruskan salah satu dari nilai berikut:

  • metric menetapkan penggunaan sistem metrik. Jarak tekstual dikembalikan menggunakan kilometer dan meter.
  • imperial menetapkan penggunaan sistem Imperial (Inggris). Jarak tekstual dikembalikan menggunakan mil dan kaki.

Catatan: setelan sistem satuan ini hanya memengaruhi text yang ditampilkan dalam bidang distance. Bidang distance juga berisi values yang selalu dinyatakan dalam meter.

Mencondongkan Region

Anda juga bisa menyetel layanan Directions untuk mengembalikan hasil yang dicondongkan ke region tertentu dengan menggunakan parameter region. Parameter ini mengambil argumen ccTLD (top-level domain kode negara) yang menetapkan kecondongan region. Umumnya kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Kerajaan Inggris adalah "uk" (.co.uk) sementara kode ISO 3166-1 untuknya adalah "gb" (secara teknis untuk entitas "Kerajaan Bersatu Britania Raya dan Irlandia Utara").

Anda bisa memanfaatkan domain apa saja tempat aplikasi Google Maps utama menjalankan arah mengemudi.

Misalnya, permintaan arah dari "Toledo" ke "Madrid" akan mengembalikan hasil bila region disetel ke es karena "Toledo" ditafsirkan sebagai kota Spanyol:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Arah untuk "Toledo" ke "Madrid" yang dikirim tanpa parameter region tidak akan mengembalikan hasil, karena "Toledo" ditafsirkan sebagai kota di Ohio:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Respons Directions

Respons Directions dikembalikan dalam format yang ditunjukkan oleh flag output dalam jalur permintaan URL.

Respons Contoh

Contoh permintaan HTTP ditampilkan di bawah ini, yang menghitung rute dari Chicago, IL ke Los Angeles, CA melewati dua titik jalan di Joplin, MO dan Oklahoma City, OK.

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

Contoh di atas meminta keluaran JSON. Bisa juga meminta keluaran XML. Klik tab di bawah ini untuk melihat contoh respons JSON dan XML.

Karena hasil arah bisa sangat detail, maka elemen berulang dalam respons telah dihilangkan agar lebih jelas.

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

Biasanya, hanya dihasilkan satu entri dalam larik routes untuk pencarian arah, meskipun layanan Directions bisa mengembalikan beberapa rute jika Anda meneruskan alternatives=true.

Perhatikan, hasil ini biasanya harus di-parse jika Anda ingin mengekstrak nilai-nilai dari hasil ini. Mem-parse JSON relatif mudah. Lihat Mem-parse JSON untuk mengetahui beberapa pola desain yang disarankan.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Perhatikan, respons XML terdiri dari satu <DirectionsResponse> dan elemen tingkat atas berikut:

  • <status> berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • Satu <geocoded_waypoint> per titik jalan, plus asal dan tujuan, dengan detail tentang hasil geocoding ini. Mungkin ada elemen <geocoded_waypoint/> yang kosong. Lihat Titik Jalan Hasil Geocoding di bawah ini.
  • Nol atau beberapa elemen <route>, masing-masing berisi satu set informasi rute antara tempat asal dan tujuan.

Kami menyarankan Anda menggunakan json sebagai flag output yang dipilih kecuali jika layanan Anda memerlukan xml karena suatu alasan. Pemrosesan struktur hierarki XML memerlukan kehati-hatian, jadi Anda perlu mereferensikan simpul dan elemen yang tepat. Lihat Mem-parse XML dengan XPath untuk mengetahui beberapa pola desain yang disarankan bagi pemrosesan keluaran.

Bagian selebihnya dari dokumentasi ini akan menggunakan sintaks JSON. Umumnya, format keluaran tidak menjadi masalah untuk keperluan mengilustrasikan konsep atau nama bidang dalam dokumentasi. Akan tetapi, perhatikan perbedaan kecil berikut ini:

  • Hasil XML dibungkus dalam elemen <DirectionsResponse> akar.
  • JSON menandai entri dengan beberapa elemen menurut larik plural (misalnya steps dan legs), sedangkan XML menandakan ini menggunakan beberapa elemen tunggal (misalnya <step> dan <leg>).
  • JSON menandai urutan titik jalan melalui bidang waypoint_order, sedangkan XML menandai ini menggunakan elemen <waypoint_index> individual.
  • Elemen kosong ditunjukkan melalui larik kosong dalam JSON, namun tidak ada elemen tersebut di XML. Respons tanpa hasil akan mengembalikan larik routes kosong dalam JSON, namun tidak ada elemen <route> dalam XML, misalnya.

Elemen Respons Directions

Respons Directions berisi elemen akar berikut ini:

  • status berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • geocoded_waypoints berisi larik dengan detail tentang geocoding asal, tujuan dan titik jalan. Lihat Titik Jalan Hasil Geocoding di bawah ini.
  • routes berisi larik rute dari asal ke tujuan. Lihat Routes di bawah ini. Routes terdiri dari Legs dan Steps tersarang.
  • available_travel_modes berisi larik mode perjalanan yang tersedia. Bidang ini dikembalikan jika sebuah permintaan menetapkan mode perjalanan dan tidak mendapatkan hasil. Larik berisi mode perjalanan yang tersedia di negara-negara dari serangkaian titik jalan yang diberikan. Bidang ini tidak dikembalikan jika satu atau beberapa titik jalan adalah via: titik jalan. Lihat detailnya di bawah ini.

Kode Status

Bidang status dalam objek respons Directions berisi status permintaan, dan bisa berisi informasi debug untuk membantu Anda melacak penyebab kegagalan layanan Directions. Bidang status bisa berisi nilai-nilai berikut:

  • OK menunjukkan respons berisi result yang valid.
  • NOT_FOUND menunjukkan setidaknya salah satu lokasi yang ditetapkan dalam asal, tujuan, atau titik jalan suatu permintaan tidak bisa dibuat kode geografisnya.
  • ZERO_RESULTS menunjukkan tidak ada rute yang bisa ditemukan antara tempat asal dan tujuan.
  • MAX_WAYPOINTS_EXCEEDED menunjukkan terlalu banyak waypoints yang diberikan dalam permintaan. Untuk aplikasi yang menggunakan Google Maps Directions API sebagai layanan web, atau layanan Directions dalam Google Maps JavaScript API, jumlah waypoints maksimum yang diperbolehkan adalah 23 ditambah lokasi asal dan tujuan. Pelanggan Google Maps APIs Premium Plan dapat mengirimkan permintaan dengan maksimum 23 titik jalan, ditambah lokasi asal dan tujuan.
  • INVALID_REQUEST menunjukkan permintaan yang diberikan tidak valid. Penyebab umum dari status ini adalah parameter atau nilai parameter yang tidak valid.
  • OVER_QUERY_LIMIT menunjukkan layanan menerima terlalu banyak permintaan dari aplikasi Anda dalam jangka waktu yang diperbolehkan.
  • REQUEST_DENIED menunjukkan layanan menolak penggunaan layanan Directions oleh aplikasi Anda.
  • "UNKNOWN_ERROR" menunjukkan permintaan arah tidak bisa diproses karena kesalahan server. Permintaan mungkin berhasil jika Anda mencoba lagi.

Pesan Kesalahan

Jika kode statusnya bukan OK, mungkin ada bidang error_message tambahan dalam objek respons Directions. Bidang ini berisi informasi lebih detail tentang alasan di balik kode status yang diberikan.

Catatan: Bidang ini tidak dijamin akan selalu ada, dan materinya bisa berubah.

Titik Jalan Hasil Geocoding

Detail geocoding setiap titik jalan, serta tempat asal dan tujuan, bisa ditemukan dalam larik geocoded_waypoints (JSON). Ini bisa digunakan untuk menduga sebab layanan mengembalikan rute yang tidak diharapkan atau tanpa rute.

Elemen-elemen dalam larik geocoded_waypoints sesuai dengan, menurut posisi berbasis nol, tempat asal, titik jalan dalam urutan penetapannya, dan tujuan. Setiap elemen menyertakan detail tentang operasi geocoding untuk titik jalan yang sesuai:

  • geocoder_status menunjukkan kode status yang dihasilkan dari operasi geocoding. Bidang ini bisa berisi nilai berikut:
    • "OK" menunjukkan tidak terjadi kesalahan; alamat berhasil di-parse dan setidaknya satu geocode dikembalikan.
    • ZERO_RESULTS menunjukkan geocode berhasil namun tidak mengembalikan hasil. Ini bisa terjadi jika geocoder meneruskan address yang tidak ada.
  • partial_match menunjukkan geocoder tidak mengembalikan hasil yang benar-benar cocok dengan permintaan asal, meskipun geocoder bisa mencocokkan sebagian dari alamat yang diminta. Anda mungkin ingin memeriksa permintaan asal untuk mengetahui adanya salah eja dan/atau alamat yang tidak lengkap.

    Kecocokan parsial paling sering terjadi untuk alamat jalan yang tidak ditemukan di lokasi yang Anda teruskan dalam permintaan. Kecocokan parsial juga mungkin dikembalikan bila sebuah permintaan memiliki kecocokan terhadap dua atau beberapa lokasi di daerah yang sama. Misalnya, "21 Henr St, Bristol, UK" akan mengembalikan kecocokan parsial untuk Henry Street dan Henrietta Street. Perhatikan, jika permintaan menyertakan komponen alamat yang salah eja, layanan geocoding mungkin akan menyarankan alamat alternatif. Saran yang terpicu melalui cara ini juga akan dinilai sebagai kecocokan parsial.

  • place_id adalah sebuah identifier unik yang bisa digunakan bersama Google API lainnya. Misalnya, Anda bisa menggunakan place_id dari respons Google Place Autocomplete untuk menghitung arah ke sebuah bisnis setempat. Lihat ringkasan ID tempat.
  • types menunjukkan tipe alamat dari hasil geocoding yang digunakan untuk menghitung arah. Berikut ini adalah tipe yang dikembalikan: 
    • street_address menunjukkan alamat jalan secara tepat.
    • route menunjukkan rute yang telah diberi nama (misalnya "US 101").
    • intersection menunjukkan persimpangan utama, biasanya persimpangan dua jalan besar.
    • political menunjukkan entitas politik. Biasanya, tipe ini menunjukkan poligon dari beberapa pemerintahan sipil.
    • country menunjukkan entitas politik nasional, dan biasanya merupakan tipe urutan tertinggi yang dikembalikan oleh Geocoder.
    • administrative_area_level_1 menunjukkan entitas sipil urutan pertama di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah negara bagian. Tidak semua negara memiliki tingkat administratif ini. Di hampir semua kasus, nama-nama singkat administrative_area_level_1 akan hampir cocok dengan subdivisi ISO 3166-2 dan daftar lainnya yang beredar luas; akan tetapi hal ini bukan jaminan karena hasil geocoding kami berdasarkan pada aneka macam sinyal dan data lokasi.
    • administrative_area_level_2 menunjukkan entitas sipil urutan kedua di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah county. Tidak semua negara memiliki tingkat administratif ini.
    • administrative_area_level_3 menunjukkan entitas sipil urutan ketiga di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • administrative_area_level_4 menunjukkan entitas sipil urutan keempat di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • administrative_area_level_5 menunjukkan entitas sipil urutan kelima di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • colloquial_area menunjukkan nama alternatif yang umum digunakan untuk entitas.
    • locality menunjukkan gabungan entitas politik kota besar atau kota kecil.
    • ward menunjukkan suatu tipe daerah khusus di Jepang, untuk memfasilitasi perbedaan antara beberapa komponen daerah dalam alamat di Jepang.
    • sublocality menunjukkan entitas sipil urutan pertama di bawah daerah. Beberapa lokasi mungkin akan menerima salah satu tipe tambahan: sublocality_level_1 hingga sublocality_level_5. Setiap tingkat subdaerah adalah entitas sipil. Angka yang lebih besar menunjukkan area geografis yang lebih kecil.
    • neighborhood menunjukkan daerah sekitar yang telah diberi nama
    • premise menunjukkan lokasi yang telah diberi nama, biasanya bangunan atau sekumpulan bangunan dengan nama umum
    • subpremise menunjukkan entitas urutan pertama di bawah lokasi yang telah diberi nama, biasanya sebuah bangunan dalam sekumpulan bangunan dengan nama umum
    • postal_code menunjukkan kode pos seperti yang biasa digunakan untuk penulisan alamat pos dalam negara tersebut.
    • natural_feature menunjukkan fitur alami yang menonjol.
    • airport menunjukkan sebuah bandara.
    • park menunjukkan taman yang telah diberi nama.
    • point_of_interest menunjukkan tempat menarik yang telah diberi nama. Biasanya, "POI" ini adalah entitas lokal terkenal yang tidak mudah dimasukkan dalam kategori lain, seperti "Empire State Building" atau "Patung Liberty".

    Daftar kosong dari tipe menunjukkan tidak ada tipe yang diketahui untuk komponen alamat tertentu, misalnya Lieu-dit di Prancis.

Detail ini tidak akan disajikan untuk titik jalan yang ditetapkan berupa nilai garis lintang/garis bujur tekstual jika layanan tidak mengembalikan hasil. Hal ini karena titik jalan tersebut hanya membalik geocode untuk memperoleh alamat representatif setelah rute ditemukan. Sebuah objek JSON kosong akan menempati tempat yang sesuai dalam larik geocoded_waypoints.

Routes

Bila Google Maps Directions API mengembalikan hasil, ia akan menempatkannya dalam larik routes (JSON). Sekalipun layanan tidak mengembalikan hasil (misalnya jika tempat asal dan/atau tujuan tidak ada) ia tetap mengembalikan larik routes kosong. (Respons XML terdiri dari nol atau beberapa elemen <route>.)

Setiap elemen larik routes berisi satu hasil dari tempat asal dan tujuan yang ditetapkan. Rute ini bisa terdiri dari satu atau beberapa legs bergantung pada apakah ada titik jalan yang ditetapkan. Serta, rute tersebut juga berisi informasi hak cipta dan peringatan yang harus ditampilkan kepada pengguna di samping informasi rute.

Setiap rute di bidang routes bisa berisi bidang-bidang berikut:

  • summary berisi keterangan tekstual singkat untuk rute, cocok untuk menamakan dan membedakan rute dari alternatif.
  • legs[] berisi sebuah larik yang berisi informasi tentang segmen rute, di antara dua lokasi dalam rute yang diberikan. Segmen terpisah akan ditampilkan untuk setiap titik jalan atau tujuan yang ditetapkan. (Rute tanpa titik jalan akan berisi persis satu segmen dalam larik legs.) Setiap segmen terdiri dari serangkaian steps. (Lihat Segmen Arah di bawah ini.)
  • waypoint_order (atau <waypoint_index> dalam XML) berisi sebuah larik yang menunjukkan urutan setiap titik jalan dalam rute yang dihitung. Titik-titik jalan ini bisa diurutkan ulang jika pada permintaan diteruskan optimize:true dalam parameter waypoints-nya.
  • overview_polyline berisi objek points tunggal yang memegang representasi rute polyline yang dienkode. Polyline adalah perkiraan jalur (dihaluskan) arah yang dihasilkan.
  • bounds berisi kotak pembatas viewport overview_polyline.
  • copyrights berisi teks hak cipta yang akan ditampilkan untuk rute ini. Anda harus mengelola dan menampilkan sendiri informasi ini.
  • warnings[] berisi sebuah larik peringatan yang akan ditampilkan saat menampilkan arah ini. Anda harus menangani dan menampilkan sendiri peringatan ini.
  • fare: Jika ada, berisi total tarif (yaitu, total biaya tiket) pada rute ini. Properti ini hanya dikembalikan untuk permintaan angkutan umum dan hanya untuk rute yang informasi tarifnya tersedia untuk semua segmen angkutan umum. Informasi ini menyertakan:
    • currency: Sebuah kode mata uang ISO 4217 menunjukkan mata uang yang digunakan dalam menyatakan jumlahnya.
    • value: Jumlah total tarif, dalam mata uang yang ditetapkan di atas.
    • text: Jumlah total tarif, diformat dalam bahasa yang diminta.

Di bawah ini adalah contoh informasi tarif dalam sebuah rute:

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

Leg

Setiap elemen dalam larik legs menetapkan satu segmen perjalanan dari tempat asal ke tujuan dalam rute yang dihitung. Untuk rute yang tidak berisi titik jalan, rute akan terdiri dari satu "segmen", namun untuk rute yang mendefinisikan satu atau beberapa titik jalan, rute akan terdiri dari satu atau beberapa segmen, sesuai dengan segmen tertentu pada perjalanan tersebut.

Setiap segmen dalam bidang legs bisa berisi bidang-bidang berikut:

  • steps[] berisi larik langkah yang menunjukkan informasi tentang setiap langkah terpisah dari segmen perjalanan. (Lihat Langkah Arah di bawah ini.)
  • distance menunjukkan total jarak yang ditempuh oleh segmen ini, sebagai sebuah bidang dengan elemen-elemen berikut:

    • value menunjukkan jarak dalam meter
    • text berisi representasi jarak yang bisa dibaca orang, ditampilkan dalam satuan yang digunakan di tempat asal (atau sebagaimana digantikan dalam parameter units pada permintaan). (Misalnya, mil dan kaki akan digunakan untuk tempat asal yang berada di Amerika Serikat.) Perhatikan, sistem satuan apa pun yang Anda tampilkan sebagai teks, bidang distance.value selalu berisi nilai yang dinyatakan dalam meter.

    Bidang ini mungkin tidak ada jika jaraknya tidak diketahui.

  • distance menunjukkan total durasi segmen ini, sebagai sebuah bidang dengan elemen-elemen berikut:

    • value menunjukkan durasi dalam detik.
    • text berisi representasi durasi yang bisa dibaca orang.

    Bidang ini mungkin tidak ada jika durasinya tidak diketahui.

  • duration_in_traffic menunjukkan total durasi segmen ini. Nilai ini merupakan perkiraan waktu dalam lalu lintas berdasarkan kondisi lalu lintas saat ini dan lalu lintas historis. Lihat parameter permintaan traffic_model untuk opsi yang bisa Anda gunakan untuk meminta agar nilai yang dikembalikan optimistik, pesimistik, atau perkiraan terbaik. Durasi dalam lalu lintas hanya dikembalikan jika berlaku semua hal berikut ini:

    • Permintaan menyertakan kunci API yang valid, atau tanda tangan dan ID klien Google Maps APIs Premium Plan yang valid.
    • Permintaan tidak berisi titik jalan persinggahan. Jika permintaan menyertakan titik jalan, permintaan harus diawali dengan via: untuk menghindari persinggahan.
    • Permintaan ini khusus untuk arah mengemudi— parameter mode disetel ke driving.
    • Permintaan berisi parameter departure_time.
    • Kondisi lalu lintas tersedia untuk rute yang diminta.

    duration_in_traffic berisi bidang-bidang berikut:

    • value menunjukkan durasi dalam detik.
    • text berisi representasi durasi yang bisa dibaca orang.
  • arrival_time berisi perkiraan waktu kedatangan untuk segmen ini. Properti ini hanya dikembalikan untuk arah angkutan umum. Hasilnya dikembalikan sebagai objek Time dengan tiga properti:
    • value waktu yang ditetapkan sebagai objek JavaScript Date.
    • text waktu yang ditetapkan sebagai string. Waktu ditampilkan dalam zona waktu halte angkutan umum.
    • time_zone berisi zona waktu stasiun ini. Nilainya adalah nama zona waktu sebagaimana didefinisikan dalam Database Zona Waktu IANA, misalnya "America/New_York".
  • departure_time berisi perkiraan waktu keberangkatan untuk segmen ini, yang ditetapkan sebagai objek Time. departure_time hanya tersedia untuk arah angkutan umum.
  • start_location berisi koordinat garis lintang/garis bujur dari tempat asal segmen ini. Karena Directions API menghitung arah antar lokasi dengan menggunakan opsi transportasi terdekat (biasanya sebuah jalan) pada titik awal dan titik akhir, start_location mungkin berbeda dari tempat asal yang diberikan segmen ini jika, misalnya, jalan tidak dekat dengan tempat asal.
  • end_location berisi koordinat garis lintang/garis bujur untuk tempat tujuan segmen ini. Karena Google Maps Directions API menghitung arah antar lokasi dengan menggunakan opsi transportasi terdekat (biasanya sebuah jalan) pada titik awal dan titik akhir, end_location mungkin berbeda dari tempat tujuan yang diberikan segmen ini jika, misalnya, jalan tidak dekat dengan tempat tujuan.
  • start_address berisi alamat yang bisa dibaca orang (biasanya alamat jalan) yang dihasilkan dari geocoding terbalik atas start_location segmen ini.
  • end_address berisi alamat yang bisa dibaca orang (biasanya alamat jalan) dengan geocoding terbalik atas end_location segmen ini.

Steps

Setiap elemen dalam larik steps mendefinisikan satu langkah dari arah yang dihitung. Langkah adalah satuan terkecil dari rute arah, berisi satu langkah yang menjelaskan satu petunjuk spesifik mengenai perjalanan. Mis. "Belok kiri di W. 4th St." Langkah ini tidak hanya menjelaskan petunjuk namun juga berisi informasi jarak dan durasi yang berkaitan dengan bagaimana hubungan langkah ini dengan langkah berikut. Misalnya, langkah yang dinyatakan dengan "Gabung ke I-80 Barat" dapat berisi durasi "37 mil" dan "40 menit", yang menunjukkan langkah berikutnya adalah 37 mil/40 menit dari langkah ini.

Saat menggunakan Google Maps Directions API untuk menelusuri arah angkutan umum, larik langkah akan menyertakan transit details tambahan dalam bentuk larik transit_details. Jika arah menyertakan beberapa moda transportasi, arah detail akan diberikan untuk langkah-langkah berjalan atau mengemudi dalam larik steps bagian dalam. Misalnya, langkah berjalan kaki akan menyertakan arah dari lokasi awal sampai akhir: "Berjalan ke Innes Ave & Fitch St". Langkah tersebut akan menyertakan detail arah berjalan untuk rute itu dalam larik steps bagian dalam, misalnya: "Menuju ke barat laut", "Belok kiri ke Arelious Walker", dan "Belok kiri ke Innes Ave".

Setiap langkah dalam bidang steps bisa berisi bidang-bidang berikut:

  • html_instructions berisi petunjuk terformat untuk langkah ini, disajikan berupa string teks HTML.
  • distance berisi jarak yang ditempuh oleh langkah ini hingga langkah berikutnya. (Lihat diskusi tentang bidang ini dalam Segmen Arah di atas.) Bidang ini mungkin tidak didefinisikan jika jarak tidak diketahui.
  • duration berisi waktu yang biasanya diperlukan untuk melakukan langkah tersebut, hingga langkah berikutnya. (Lihat keterangan dalam Segmen Arah di atas.) Bidang ini mungkin tidak didefinisikan jika durasi tidak diketahui.
  • start_location berisi lokasi titik awal langkah ini, berupa satu set bidang lat dan lng.
  • end_location berisi lokasi titik terakhir langkah ini, berupa satu set bidang lat dan lng.
  • polyline berisi objek points tunggal yang menyimpan representasi langkah polyline yang dienkode. Polyline ini adalah perkiraan jalur (dihaluskan) langkah tersebut.
  • steps berisi arah detail untuk langkah berjalan kaki atau mengemudi dalam arah angkutan umum. Substep hanya tersedia bila travel_mode disetel ke "transit". Larik steps bagian dalam sama tipenya dengan steps.
  • transit_details berisi informasi spesifik angkutan umum. Bidang ini hanya dikembalikan bersama travel_mode yang disetel ke "transit". Lihat Detail Angkutan Umum di bawah ini.

Detail Angkutan Umum

Arah angkutan umum mengembalikan informasi tambahan yang tidak relevan untuk moda transportasi lain. Properti tambahan ini diekspos melalui objek transit_details, yang dikembalikan berupa bidang elemen dalam larik steps[]. Dari objek TransitDetails Anda bisa mengakses informasi tambahan tentang halte angkutan umum, jalur angkutan umum dan agen angkutan umum.

Objek transit_details bisa berisi bidang-bidang berikut:

  • arrival_stop dan departure_stop berisi informasi tentang halte/stasiun untuk bagian dari perjalanan ini. Detail halte bisa berisi:
    • name nama stasiun/halte angkutan umum, misalnya "Union Square".
    • location lokasi stasiun/halte angkutan umum, dinyatakan berupa bidang lat dan lng.
  • arrival_time dan departure_time berisi waktu kedatangan dan waktu keberangkatan untuk segmen perjalanan ini, ditetapkan berupa tiga properti berikut ini:
    • text waktu yang ditetapkan sebagai string. Waktu ditampilkan dalam zona waktu halte angkutan umum.
    • value waktu ditetapkan sebagai waktu Unix, atau detik sejak tengah malam 1 Januari 1970 UTC.
    • time_zone berisi zona waktu stasiun ini. Nilainya adalah nama zona waktu sebagaimana didefinisikan dalam Database Zona Waktu IANA, misalnya "America/New_York".
  • headsign menetapkan arah melakukan perjalanan pada jalur ini, sebagaimana ditandai pada kendaraan atau pada halte keberangkatan. Ini sering kali akan berupa stasiun terakhir.
  • headway menetapkan perkiraan jumlah detik antar keberangkatan dari halte yang sama pada saat ini. Misalnya, dengan nilai headway 600, berarti Anda memperkirakan menunggu selama sepuluh menit jika ketinggalan bus.
  • num_stops berisi jumlah halte di langkah ini, termasuk halte kedatangan, namun bukan halte keberangkatan. Misalnya, jika arah Anda melibatkan berangkat dari Halte A, melewati halte B dan C, dan tiba di halte D, num_stops akan mengembalikan 3.
  • line berisi informasi tentang jalur angkutan umum yang digunakan dalam langkah ini, dan bisa berisi properti berikut:
    • name berisi nama lengkap jalur angkutan umum ini, misalnya "7 Avenue Express".
    • short_name berisi nama singkat jalur angkutan umum ini. Biasanya ini adalah nomor jalur, seperti "M7" atau "355".
    • color berisi warna yang biasa digunakan dalam papan informasi untuk jalur angkutan umum ini. Warna akan ditetapkan sebagai string heksadesimal seperti: #FF0033.
    • agencies berisi larik objek TransitAgency yang masing-masing menyediakan informasi tentang operator jalur ini, termasuk properti berikut:
      • name berisi nama agen angkutan umum.
      • url berisi alamat URL agen angkutan umum.
      • phone berisi nomor telepon agen angkutan umum.

      Anda harus menampilkan nama dan URL agen angkutan umum yang melayani hasil perjalanan tersebut.

    • url berisi URL untuk jalur angkutan umum ini seperti yang diberikan oleh agen angkutan umum.
    • icon berisi URL untuk ikon yang dikaitkan dengan jalur ini.
    • text_color berisi warna teks yang umum digunakan untuk papan informasi pada jalur ini. Warna akan ditetapkan sebagai string heksadesimal.
    • vehicle berisi tipe kendaraan yang digunakan pada jalur ini. Ini mungkin menyertakan properti berikut:
      • name berisi nama kendaraan pada jalur ini, misalnya "Kereta bawah tanah".
      • type berisi tipe kendaraan yang dijalankan pada jalur ini. Lihat dokumentasi Tipe Kendaraan untuk daftar lengkap nilai yang didukung.
      • icon berisi URL untuk ikon yang dikaitkan dengan tipe kendaraan ini.
      • local_icon berisi URL untuk ikon yang dikaitkan dengan tipe kendaraan ini, berdasarkan rambu-rambu lalu lintas setempat.

Tipe Kendaraan

Properti vehicle.type bisa mengembalikan salah satu dari nilai berikut:

Nilai Definisi
RAIL Kereta api.
METRO_RAIL Angkutan umum kereta ringan.
SUBWAY Kereta ringan bawah tanah.
TRAM Kereta ringan permukaan.
MONORAIL Monorel.
HEAVY_RAIL Kereta berat.
COMMUTER_TRAIN Kereta pelaju.
HIGH_SPEED_TRAIN Kereta kecepatan tinggi.
BUS Bus.
INTERCITY_BUS Bus antarkota.
TROLLEYBUS Trolleybus.
SHARE_TAXI Share-taxi adalah sejenis bis dengan kemampuan untuk menurunkan dan mengambil penumpang di mana saja pada rutenya.
FERRY Kapal feri.
CABLE_CAR Kendaraan yang beroperasi pada kabel, biasanya di atas tanah. Kereta gantu bisa berupa tipe GONDOLA_LIFT.
GONDOLA_LIFT Kereta gantung.
FUNICULAR Kereta yang ditarik menaiki lereng curam dengan kabel. Funicular biasanya terdiri dari dua kereta, setiap kereta bertindak sebagai pengimbang untuk kereta yang lain.
OTHER Semua kendaraan lain akan mengembalikan tipe ini.

Mode Perjalanan yang Tersedia

Bidang respons available_travel_modes berisi larik mode perjalanan yang tersedia. Bidang ini dikembalikan jika sebuah permintaan menetapkan mode perjalanan dan tidak mendapatkan hasil. Larik berisi mode perjalanan yang tersedia di negara-negara dari serangkaian titik jalan yang diberikan yang memiliki hasil. Bidang tidak dikembalikan jika ada titik jalan yang merupakan titik jalan via:.

Misalnya, coba permintaan ini:

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

Ini menghasilkan respons berikut:

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

Parameter sensor

Google Maps API sebelumnya mengharuskan Anda menyertakan parameter sensor untuk menunjukkan apakah aplikasi Anda menggunakan sensor untuk menentukan lokasi pengguna. Parameter ini tidak lagi diperlukan.

Kirim masukan tentang...

Google Maps Directions API
Google Maps Directions API
Butuh bantuan? Kunjungi halaman dukungan kami.