Memberi geocode pada alamat

Developer Wilayah Ekonomi Eropa (EEA)

Geocoding menerjemahkan alamat menjadi lokasi di peta. Saat Anda melakukan geocoding alamat, respons akan berisi:

  • ID tempat của vị trí
  • Koordinat lintang dan bujur lokasi
  • Plus Code lokasi
  • Detail alamat yang diperluas

Permintaan geocode

Permintaan geocode adalah permintaan HTTP GET. Anda dapat menentukan alamat sebagai string tidak terstruktur:

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

Atau sebagai kumpulan komponen alamat terstruktur yang diwakili oleh parameter kueri:

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

Biasanya, Anda menggunakan format terstruktur saat memproses komponen alamat yang diambil dalam formulir HTML.

Teruskan semua parameter lainnya sebagai parameter URL atau, untuk parameter seperti kunci API dan mask kolom, di header sebagai bagian dari permintaan GET.

Meneruskan string alamat tidak terstruktur

Alamat tidak terstruktur adalah alamat yang diformat sebagai string atau Plus Code. Geocoding alamat tidak menyelesaikan koordinat lintang dan bujur, atau string tidak terstruktur lainnya yang tidak mewakili alamat atau Plus Code. Permintaan yang menggunakan string tersebut tidak didukung dan dapat menyebabkan respons error atau perilaku yang tidak ditentukan. Contoh kueri yang tidak didukung mencakup hal berikut:

Jenis kueri Contoh
Koordinat lintang dan bujur. Gunakan geocoding terbalik sebagai gantinya. "37.422131,-122.084801"
Terlalu banyak konsep atau batasan, seperti nama beberapa tempat, jalan, atau kota dalam satu kueri "Market Street San Francisco San Jose Airport"
Elemen alamat pos yang tidak ditampilkan di Google Maps "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
Nama bisnis, jaringan, atau kategori yang digabungkan dengan lokasi tempat entitas ini tidak tersedia "Tesco near Dallas, Texas"
Kueri ambigu dengan beberapa interpretasi "Charger drop-off"
Nama historis yang tidak lagi digunakan "Middlesex United Kingdom"
Elemen atau maksud non-geospasial "How many boats are in Ventura Harbor?"
Nama tidak resmi atau nama vanity "The Jenga"
"The Helter Skelter"

Misalnya, contoh berikut meneruskan string alamat yang dienkode URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Perhatikan bahwa karakter "+" di URL dikonversi menjadi spasi.

Anda juga dapat membuat permintaan menggunakan perintah curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Alamat dapat berisi banyak jenis karakter khusus. Misalnya, "/" seperti dalam "7/1 King St, Concord West". Enkode URL "/" sebagai %2F:

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Contoh umum lainnya adalah karakter "#", seperti dalam "9500 W Bryn Mawr Ave #650, Rosemont". Enkode URL "#" sebagai %2FE:

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Pada contoh berikutnya, Anda menentukan string alamat tidak terstruktur sebagai Plus Code 849VCWC8+R4. Pastikan Anda mengenkode URL karakter "+" sebagai %2B:

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

Meneruskan alamat terstruktur

Tentukan alamat terstruktur menggunakan parameter kueri address, dengan jenis PostalAddress. Objek PostalAddress memungkinkan Anda menentukan beberapa atau semua komponen alamat dalam permintaan sebagai parameter kueri individual.

Misalnya, untuk menentukan hanya kode pos alamat, Anda menggunakan PostalAddress.postalCode:

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

Untuk menentukan beberapa komponen alamat, seperti untuk komponen alamat yang diambil dalam formulir HTML, gunakan beberapa parameter kueri:

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

Menggunakan OAuth untuk membuat permintaan

Geocoding API v4 mendukung OAuth 2.0 untuk autentikasi. Untuk menggunakan OAuth dengan Geocoding API, token OAuth harus diberi cakupan yang benar. Geocoding API mendukung cakupan berikut untuk digunakan dengan geocoding maju:

  • https://www.googleapis.com/auth/maps-platform.geocode — Gunakan dengan semua metode Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.address — Hanya gunakan dengan GeocodeAddress untuk geocoding maju.

Selain itu, Anda dapat menggunakan cakupan https://www.googleapis.com/auth/cloud-platform umum untuk semua metode Geocoding API. Cakupan tersebut berguna selama pengembangan, tetapi tidak untuk produksi, karena cakupan tersebut adalah cakupan umum yang memungkinkan akses ke semua metode.

Untuk mengetahui informasi dan contoh selengkapnya, lihat Menggunakan OAuth.

Respons geocode

Geocoding menampilkan GeocodeAddressResponse objek yang berisi array results dari GeocodeResult objek. Setiap objek GeocodeResult mewakili satu tempat.

Respons Geocoding API menyertakan types array di dua tempat utama dalam GeocodeResult:

  1. GeocodeResult.types: Array ini menunjukkan jenis hasil secara keseluruhan. Nilai yang mungkin diambil dari Jenis tempat yang digunakan oleh Places API. Untuk mengetahui informasi selengkapnya, lihat Jenis tempat Tabel A dan B.
  2. GeocodeResult.addressComponents[].types: Setiap komponen alamat memiliki types array yang menunjukkan jenis bagian alamat tertentu. Nilai ini diambil dari tabel Jenis alamat dan jenis komponen alamat yang digunakan oleh Places API.

Objek JSON lengkap dalam bentuk:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Parameter yang diperlukan

  • address — Alamat jalan atau Plus Code yang ingin Anda geocode. Catatan: Geocoding alamat tidak menyelesaikan koordinat lintang dan bujur, atau string tidak terstruktur lainnya yang tidak mewakili alamat atau Plus Code. Lihat Meneruskan string alamat tidak terstruktur untuk mengetahui detail dan contoh kueri yang tidak didukung. Tetapkan alamat sesuai dengan format yang digunakan oleh layanan pos nasional di negara terkait. Elemen alamat tambahan seperti nama bisnis dan nomor unit, suite, atau lantai harus dihindari. Elemen alamat jalan harus dibatasi oleh spasi yang dienkode URL ke %20. Misalnya, teruskan alamat "24 Sussex Drive Ottawa ON" sebagai: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Format Plus Codes seperti yang ditunjukkan di bawah. Tanda plus dienkode URL ke %2B dan spasi dienkode URL ke %20:
    • A kode global adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih. Misalnya, enkode "849VCWC8+R9" sebagai 849VCWC8%2BR9.
    • A kode majemuk adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit. Misalnya, enkode "CWC8+R9 Mountain View, CA, USA" sebagai CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parameter opsional

  • locationBias

    Menentukan area yang akan ditelusuri sebagai Viewport. Lokasi ini berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di dekat tetapi di luar area.

    Tentukan wilayah sebagai Viewport persegi panjang. Persegi panjang adalah area pandang lintang-bujur, yang direpresentasikan sebagai dua titik rendah dan tinggi yang berlawanan secara diagonal. Titik rendah menandai sudut barat daya persegi panjang, dan titik tinggi mewakili sudut timur laut persegi panjang.

    Area pandang dianggap sebagai wilayah tertutup, yang berarti area pandang tersebut mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:

    • Jika low = high, area pandang terdiri dari satu titik tersebut.
    • Jika low.longitude > high.longitude, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat).
    • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang akan mencakup semua bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur akan kosong.
    • Jika low.latitude > high.latitude, rentang lintang akan kosong.

    Nilai rendah dan tinggi harus diisi, dan kotak yang direpresentasikan tidak boleh kosong. Area pandang kosong akan menghasilkan error.

    Misalnya, string kueri ini menentukan area pandang yang sepenuhnya mencakup New York City:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    Bahasa yang digunakan untuk menampilkan hasil.

    • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
    • Jika languageCode tidak diberikan, API akan menggunakan en sebagai default. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
    • API akan berupaya sebaik mungkin untuk memberikan alamat jalan yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API akan menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika diperlukan, dengan memperhatikan bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Semua komponen alamat ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.
    • Bahasa pilihan memiliki pengaruh kecil pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan hasil tersebut ditampilkan. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa, tetapi tidak dalam bahasa lain.

  • regionCode

    Kode wilayah sebagai nilai kode CLDR dua karakter. Tidak ada nilai default. Sebagian besar kode CLDR identik dengan kode ISO 3166-1.

    Saat melakukan geocoding alamat, geocoding maju, parameter ini dapat memengaruhi, tetapi tidak sepenuhnya membatasi, hasil dari layanan ke wilayah yang ditentukan. Saat melakukan geocoding lokasi atau tempat, geocoding terbalik atau geocoding tempat, parameter ini dapat digunakan untuk memformat alamat. Dalam semua kasus, parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  • FieldMask

    Buat mask kolom respons untuk menentukan kolom yang akan ditampilkan dalam respons. Teruskan mask kolom respons ke metode menggunakan parameter URL $fields atau fields, atau menggunakan header HTTP X-Goog-FieldMask. Misalnya, permintaan di bawah ini hanya akan menampilkan kolom placeID dari respons.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    Responsnya adalah: 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    Lihat Memilih kolom yang akan ditampilkan untuk mengetahui detail selengkapnya.

Membiaskan lokasi

Gunakan parameter locationBias untuk menginstruksikan layanan Geocoding agar lebih memilih hasil dalam area pandang tertentu (dinyatakan dalam bentuk kotak pembatas). Parameter locationBias menentukan koordinat lintang/bujur sudut barat daya dan timur laut kotak pembatas ini.

Misalnya, permintaan geocode untuk alamat "Washington" dapat menampilkan hasil untuk Washington, D.C. dan untuk negara bagian Washington di AS:

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

Responsnya dalam bentuk:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Namun, menambahkan parameter locationBias yang menentukan kotak pembatas di sekitar bagian timur laut AS akan menghasilkan geocode ini yang hanya menampilkan kota Washington, D.C.:

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Membiaskan wilayah

Dalam permintaan geocoding, Anda dapat menginstruksikan layanan Geocoding untuk menampilkan hasil yang dibiaskan ke wilayah tertentu menggunakan parameter regionCode. Parameter ini menggunakan nilai kode CLDR dua karakter yang menentukan bias wilayah. Sebagian besar kode CLDR identik dengan kode ISO 3166-1.

Tidak ada nilai default untuk regionCode. Misalnya, geocode untuk "Toledo" menampilkan hasil untuk AS dan Spanyol:

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

Respons:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Permintaan geocoding untuk "Toledo" dengan regionCode=es (Spanyol) hanya menampilkan hasil dari Spanyol:

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY