Permintaan dan respons geocoding terbalik (pencarian alamat)

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Istilah geocoding umumnya mengacu pada penerjemahan alamat yang dapat dibaca manusia ke lokasi pada peta. Proses melakukan kebalikannya, yaitu menerjemahkan lokasi pada peta menjadi alamat yang dapat dibaca manusia, dikenal sebagai geocoding terbalik.

Permintaan geocoding terbalik

Parameter wajib

  • latlng — Nilai lintang dan bujur yang menentukan lokasi tempat Anda ingin mendapatkan alamat terdekat yang dapat dibaca manusia.
  • key — Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk tujuan pengelolaan kuota. Pelajari cara mendapatkan kunci.

Parameter opsional

Ini adalah parameter opsional yang dapat Anda sertakan dalam permintaan geocoding terbalik:

  • language — Bahasa yang digunakan untuk menampilkan hasil.
    • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
    • Jika language tidak disediakan, geocoder akan mencoba menggunakan bahasa pilihan seperti yang ditentukan dalam header Accept-Language, atau bahasa asli domain tempat permintaan dikirim.
    • Geocoder akan menyediakan cara terbaik untuk menyediakan alamat yang dapat dibaca oleh pengguna dan lokal. Untuk mencapai sasaran tersebut, API akan menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi menjadi skrip yang dapat dibaca oleh pengguna jika perlu, dengan mengamati bahasa yang dipilih. Semua alamat lainnya ditampilkan dalam bahasa yang diinginkan. Semua komponen alamat ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa pilihan, geocoder akan menggunakan yang paling cocok.
  • result_type — Filter dari satu atau beberapa jenis alamat, yang dipisahkan tanda pipa (|). Jika parameter berisi beberapa jenis alamat, API akan menampilkan semua alamat yang cocok dengan salah satu jenis alamat. Catatan tentang pemrosesan: Parameter result_type tidak membatasi penelusuran ke jenis alamat yang ditentukan. Sebaliknya, result_type berfungsi sebagai filter pasca-penelusuran: API mengambil semua hasil untuk latlng yang ditentukan, lalu menghapus hasil tersebut yang tidak cocok dengan jenis alamat yang ditentukan. Nilai-nilai berikut ini didukung:
    • street_address menunjukkan alamat yang akurat.
    • route menunjukkan rute yang telah diberi nama (seperti "US 101").
    • intersection menunjukkan persimpangan utama, biasanya persimpangan dua jalan utama.
    • political menunjukkan entitas politik. Biasanya, jenis ini menunjukkan poligon dari pemerintahan sipil tertentu.
    • country menunjukkan entitas politik nasional, dan biasanya merupakan jenis 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 didasarkan 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. Jenis 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. Jenis 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. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • administrative_area_level_6 menunjukkan entitas sipil urutan keenam di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • administrative_area_level_7 menunjukkan entitas sipil urutan ketujuh di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    • colloquial_area menunjukkan nama alternatif yang biasa digunakan untuk entitas.
    • locality menunjukkan gabungan entitas politik kota besar atau kota kecil.
    • sublocality menunjukkan entitas sipil urutan pertama di bawah lokalitas. Beberapa lokasi dapat menerima salah satu dari jenis tambahan: sublocality_level_1 hingga sublocality_level_5. Setiap tingkat sublokalitas 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
    • plus_code menunjukkan referensi lokasi yang dienkode, yang berasal dari lintang dan bujur. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika bangunan tidak diberi nomor atau jalan tidak diberi nama). Lihat https://plus.codes untuk mengetahui detailnya.
    • postal_code menunjukkan kode pos seperti yang biasa digunakan untuk penulisan alamat pos dalam negara tersebut.
    • natural_feature menunjukkan fitur alam terkemuka.
    • airport menunjukkan bandara.
    • park menunjukkan taman yang telah diberi nama.
    • point_of_interest menunjukkan lokasi menarik yang telah diberi nama. Biasanya, "POI" ini adalah entitas lokal terkenal yang tidak mudah dimasukkan dalam kategori lain, seperti "Empire State Building" atau "Eiffel Tower".
  • location_type — Filter dari satu atau beberapa jenis lokasi, yang dipisahkan dengan pipa (|). Jika parameter berisi beberapa jenis lokasi, API akan menampilkan semua alamat yang cocok dengan salah satu jenis. Catatan tentang pemrosesan: Parameter location_type tidak membatasi penelusuran ke jenis lokasi yang ditentukan. Sebaliknya, location_type bertindak sebagai filter pasca-penelusuran: API mengambil semua hasil untuk latlng yang ditentukan, lalu menghapus hasil tersebut yang tidak cocok dengan jenis lokasi yang ditentukan. Nilai-nilai berikut ini didukung:
    • "ROOFTOP" hanya menampilkan alamat dengan informasi lokasi yang akurat bagi Google untuk presisi alamat.
    • "RANGE_INTERPOLATED" hanya menampilkan alamat yang mencerminkan perkiraan (biasanya di jalan) yang diinterpolasi antara dua titik akurat (seperti persimpangan). Rentang interpolasi umumnya menunjukkan bahwa geocode rooftop tidak tersedia untuk alamat jalan.
    • "GEOMETRIC_CENTER" hanya menampilkan pusat geometris lokasi seperti polyline (misalnya, jalan) atau poligon (region).
    • "APPROXIMATE" hanya menampilkan alamat yang digolongkan sebagai perkiraan.

Jika filter result_type dan location_type ada, API hanya akan menampilkan hasil yang cocok dengan nilai result_type dan location_type. Jika tidak ada satu pun nilai filter yang dapat diterima, API akan menampilkan ZERO_RESULTS.

Contoh geocoding terbalik

Kueri berikut berisi nilai garis lintang/garis bujur untuk lokasi di Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Kueri di atas mengembalikan hasil berikut:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Perhatikan, geocoder terbalik akan mengembalikan lebih dari satu hasil. Hasil "formatted_address" bukan hanya alamat pos, tetapi cara apa pun untuk menamai lokasi secara geografis. Misalnya, saat geocoding titik di kota Chicago, titik yang di-geocoding dapat dinyatakan sebagai alamat jalan, sebagai kota (Chicago), sebagai negara bagian (Illinois) atau sebagai negara (Amerika Serikat). Semua adalah "alamat" ke geocoder tersebut. Geocoder terbalik akan menampilkan salah satu jenis ini sebagai hasil yang valid.

Geocoder terbalik akan mencocokkan entitas politik (negara, provinsi, kota dan lingkungan), alamat jalan, dan kode pos.

Daftar lengkap nilai formatted_address yang ditampilkan oleh kueri sebelumnya akan ditampilkan di bawah.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

Biasanya, alamat ditampilkan dari yang paling spesifik hingga yang paling tidak spesifik; alamat yang lebih tepat adalah hasil yang paling menonjol, seperti dalam kasus ini. Perhatikan bahwa kami menampilkan berbagai jenis alamat, dari alamat yang paling spesifik hingga entitas politik yang kurang spesifik seperti kawasan, kota, wilayah, negara bagian, dll. Jika Anda ingin mencocokkan jenis alamat tertentu, lihat bagian di bawah tentang membatasi hasil menurut jenis.

Geocoding terbalik difilter menurut jenis

Contoh berikut memfilter alamat yang ditampilkan untuk hanya menyertakan alamat yang memiliki jenis lokasi ROOFTOP dan jenis alamat street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Catatan: Filter ini hanya valid untuk geocoding terbalik.

Respons geocoding terbalik

Format respons geocoding terbalik sama dengan respons Geocoding. Lihat respons Geocoding. Di bawah ini adalah kode status yang mungkin dalam respons geocoding terbalik.

Kode status geocoding terbalik

Kolom "status" dalam objek respons Geocoding berisi status permintaan, dan mungkin berisi informasi proses debug untuk membantu Anda melacak penyebab geocoding terbalik tidak berfungsi. Kolom "status" dapat berisi nilai-nilai berikut:

  • "OK" menunjukkan bahwa tidak ada error yang terjadi dan setidaknya satu alamat ditampilkan.
  • "ZERO_RESULTS" menunjukkan bahwa geocoding terbalik berhasil, tetapi tidak menampilkan hasil. Hal ini dapat terjadi jika geocoder diteruskan latlng di lokasi jarak jauh.
  • "OVER_QUERY_LIMIT" menunjukkan bahwa Anda melebihi kuota.
  • "REQUEST_DENIED" menunjukkan bahwa permintaan ditolak. Mungkin karena permintaan menyertakan parameter result_type atau location_type, tetapi tidak menyertakan kunci API.
  • "INVALID_REQUEST" umumnya menunjukkan salah satu dari hal berikut:
    • Kueri (address, components, atau latlng) tidak ada.
    • result_type atau location_type yang tidak valid diberikan.
  • "UNKNOWN_ERROR" menunjukkan permintaan tidak bisa diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.

Geocoding terbalik plus kode

Kolom plus_code dalam objek respons Geocoding berisi kode plus yang paling mendekati lintang dan bujur yang dikueri. Selain itu, array hasil JSON dalam sebagian besar kasus akan berisi hasil Geocoding lengkap dengan jenis plus_code dan alamat yang berisi kode plus. Jarak antara kode plus yang didekode dan titik permintaan dijamin kurang dari 10 meter.