Menentukan lokasi untuk rute

Untuk menghitung rute, Anda harus menentukan setidaknya lokasi asal dan tujuan rute. Anda menentukan lokasi ini sebagai titik jalan pada rute.

Selain asal dan tujuan, Anda dapat menentukan berbagai jenis titik jalan dan cara menangani titik jalan untuk sebuah rute. Untuk informasi dan contoh selengkapnya, lihat topik berikut:

Menentukan lokasi untuk rute

Anda merepresentasikan lokasi dengan membuat objek Waypoint (REST) atau Waypoint (gRPC). Dalam definisi titik jalan, Anda dapat menetapkan lokasi dengan salah satu cara berikut:

Anda bisa menetapkan lokasi untuk semua titik jalan dalam permintaan dengan cara yang sama, atau Anda dapat mencampurnya. Misalnya, Anda dapat menggunakan koordinat garis lintang/garis bujur untuk titik jalan asal dan menggunakan ID tempat untuk titik jalan tujuan.

Untuk efisiensi dan akurasi, gunakan ID tempat, bukan koordinat lintang/bujur atau string alamat. ID tempat bersifat unik dan memberikan manfaat geocoding untuk pemilihan rute seperti titik akses (AP) dan variabel traffic. Parameter ini membantu menghindari situasi berikut yang dapat disebabkan oleh cara lain untuk menentukan lokasi:

  • Menggunakan koordinat garis lintang/garis bujur dapat mengakibatkan lokasi dipetakan ke jalan yang paling dekat dengan koordinat tersebut - yang mungkin bukan titik akses ke properti, atau bahkan jalan yang cepat atau aman mengarah ke tujuan.
  • String alamat harus di-geocode terlebih dahulu oleh Routes API untuk mengonversinya menjadi koordinat garis lintang/bujur sebelum dapat menghitung rute. Konversi ini dapat memengaruhi performa.

Menentukan lokasi sebagai ID tempat

Anda bisa menggunakan ID tempat untuk menetapkan lokasi titik jalan. Karena koordinat lintang dan bujur diikat ke jalan, Anda mungkin menemukan ID tempat menawarkan hasil yang lebih baik dalam beberapa situasi.

Mengambil ID tempat dari Geocoding API dan Places API (termasuk Place Autocomplete). Untuk mengetahui informasi selengkapnya tentang ID tempat, lihat Ringkasan ID Tempat.

Contoh berikut menggunakan properti placeId guna meneruskan ID tempat untuk origin dan destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Menetapkan lokasi sebagai koordinat lintang dan bujur

Untuk menentukan lokasi di titik jalan, tentukan Location (REST) atau Location(gRPC) dengan menggunakan koordinat lintang/bujur.

Misalnya, tetapkan titik jalan untuk rute origin dan destination menggunakan koordinat latitude dan longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Menentukan lokasi sebagai string alamat

String alamat adalah alamat literal yang diwakili oleh string (seperti "1600 Amphitheatre Parkway, Mountain View, CA"). Geocoding adalah proses mengonversi string alamat menjadi koordinat lintang dan bujur (seperti lintang 37,423021 dan bujur -122,083739).

Jika Anda meneruskan string alamat sebagai lokasi titik jalan, Routes API akan melakukan geocoding terhadap string tersebut secara internal untuk mengonversinya menjadi koordinat lintang dan bujur.

Misalnya, untuk menghitung rute, Anda menetapkan titik jalan untuk rute origin dan destination menggunakan string alamat:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

Dalam contoh ini, Routes API akan melakukan geocoding terhadap kedua alamat untuk mengonversinya menjadi koordinat lintang dan bujur.

Jika nilai alamat ambigu, Routes API mungkin akan memanggil penelusuran untuk membedakan dari alamat serupa. Misalnya, "1st Street" dapat berupa nilai lengkap atau nilai parsial untuk "1st street NE" atau "1st St SE". Hasil ini mungkin berbeda dengan hasil yang ditampilkan oleh Geocoding API. Anda dapat menghindari kemungkinan salah penafsiran menggunakan ID tempat.

Menetapkan region untuk alamat

Jika Anda meneruskan string alamat yang tidak lengkap sebagai lokasi titik jalan, API mungkin akan menggunakan koordinat geocode/garis bujur yang salah dibuat. Misalnya, Anda membuat permintaan yang menentukan "Toledo" sebagai tempat asal dan "Madrid" sebagai tujuan untuk rute mengemudi:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

Dalam contoh ini, "Toledo" ditafsirkan sebagai kota di negara bagian Ohio di Amerika Serikat, bukan di Spanyol. Oleh karena itu, permintaan tersebut menampilkan array kosong, yang berarti tidak ada rute:

{
  []
}

Anda dapat mengonfigurasi API untuk menampilkan hasil yang dibiaskan ke wilayah tertentu dengan menyertakan parameter regionCode. Parameter ini menentukan kode wilayah sebagai nilai dua karakter ccTLD ("domain level teratas"). Sebagian besar kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian penting. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Inggris Raya dan Irlandia Utara").

Permintaan rute untuk "Toledo" ke "Madrid" yang menyertakan parameter regionCode akan menampilkan hasil yang sesuai karena "Toledo" ditafsirkan sebagai kota di Spanyol:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

Responsnya sekarang berisi rute yang dihitung dari Toledo, Spanyol ke Madrid, Spanyol:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Menetapkan lokasi sebagai Plus Codes

Banyak orang tidak memiliki alamat persis, yang dapat menyulitkan mereka untuk menerima pengiriman. Atau, orang dengan alamat mungkin lebih memilih untuk menerima pengiriman di lokasi yang lebih spesifik, seperti pintu masuk belakang atau dok pemuatan.

Plus Codes seperti alamat untuk orang atau tempat yang tidak memiliki alamat sebenarnya. Alih-alih alamat dengan nama jalan dan nomor, Plus Codes didasarkan pada koordinat lintang/bujur, serta ditampilkan sebagai angka dan huruf.

Google mengembangkan Plus Codes untuk memberikan manfaat alamat bagi semua orang. Plus Codes adalah referensi lokasi yang dienkode, berasal dari koordinat lintang/bujur, yang mewakili area: 1/8000 derajat dengan 1/8000 derajat (sekitar 14 m x 14 m pada khatulistiwa) atau lebih kecil. Anda dapat menggunakan Plus Codes sebagai pengganti alamat di tempat tanpa alamat jelas atau jika bangunan tidak diberi nomor atau jalan tidak diberi nama.

Plus Codes harus diformat sebagai kode global atau kode gabungan:

  • Kode global terdiri dari kode area 4 karakter dan kode lokal 6 karakter atau yang lebih panjang.

    Misalnya, untuk alamat "1600 Amphitheatre Parkway, Mountain View, CA", kode globalnya adalah "849V" dan kode lokalnya adalah "CWC8+R9". Selanjutnya, Anda menggunakan Plus Codes berisi 10 karakter secara keseluruhan untuk menentukan nilai lokasi sebagai "849VCWC8+R9".

  • Kode gabungan terdiri dari kode lokal sepanjang 6 karakter atau lebih yang dikombinasikan dengan lokasi yang eksplisit.

    Misalnya, alamat "450 Serra Mall, Stanford, CA 94305, USA" memiliki kode lokal "CRHJ+C3". Untuk alamat gabungan, gabungkan kode lokal dengan bagian kota, negara bagian, kode pos, dan negara dari alamat dalam bentuk "CRHJ+C3 Stanford, CA 94305, USA".

    Misalnya, hitung rute dengan menentukan titik jalan untuk rute origin dan destination menggunakan Plus Codes:

    {
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Plus Codes didukung dalam API Google Maps Platform, termasuk Place Autocomplete, Place Details, Directions API, dan Geocoding API. Misalnya, Anda dapat menggunakan Geocoding API untuk membalikkan geocoding pada lokasi yang ditentukan oleh koordinat garis lintang/bujur untuk menentukan Plus Codes lokasi.