Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps Geocoding 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 Geocoding API
  3. Buat kunci yang sesuai
Lanjutkan

Panduan Developer

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 yang sama tetap berlaku bagaimana pun Anda menggunakan layanan. Permintaan per hari dihitung sebagai jumlah kueri sisi-klien dan sisi-server.

Apa yang dimaksud Geocoding?

Geocoding adalah proses konversi alamat (seperti "1600 Amphitheatre Parkway, Mountain View, CA") menjadi koordinat geografis (seperti garis lintang 37,423021 dan garis bujur -122,083739), yang bisa Anda gunakan untuk menempatkan marker pada peta, atau memosisikan peta.

Geocoding terbalik adalah proses mengonversi koordinat geografis menjadi alamat yang bisa dibaca orang. Layanan geocoding terbalik pada Google Maps Geocoding API juga memungkinkan Anda menemukan alamat untuk ID tempat yang diberikan.

Google Maps Geocoding API menyediakan cara langsung untuk mengakses layanan ini melalui permintaan HTTP. Contoh berikut menggunakan layanan Geocoding melalui Google Maps JavaScript API untuk memperagakan fungsionalitas dasar.

Tampilkan contoh pada layar penuh untuk melihat fungsionalitas tambahan Geocoding API, seperti opsi lain yang tersedia untuk menyesuaikan permintaan (pemfilteran komponen atau pencondongan tampilan yang terlihat) dan detail selengkapnya tentang setiap hasil.

Sebelum Anda Memulai

Dokumen ini menjelaskan layanan web Google Maps Geocoding API. Dokumen ini ditujukan untuk developer situs web dan seluler yang ingin menggunakan data geocoding dalam peta yang disediakan oleh salah satu Google Maps API.

Catatan: Layanan ini biasanya didesain untuk geocoding alamat statis (sudah diketahui sebelumnya) untuk penempatan materi aplikasi pada peta; layanan ini tidak didesain untuk merespons masukan pengguna secara real-time, misalnya. Untuk geocoding dinamis (misalnya, dalam elemen antarmuka pengguna), lihat dokumentasi untuk Google Maps JavaScript API client geocoder dan/atau Google Play Services Location API.

Geocoding adalah tugas yang menyita waktu dan sumber daya. Bila memungkinkan, lakukan pra-geocode atas alamat yang sudah diketahui (menggunakan Google Maps Geocoding API yang dijelaskan di sini atau layanan geocoding lainnya) dan simpan hasilnya di cache sementara pada desain Anda.

Untuk menggunakan Google Maps Geocoding API ini, Anda memerlukan kunci API. Sebelum Anda memulai development dengan Geocoding API, periksa persyaratan autentikasi dan batas penggunaan API.

Format Permintaan Google Maps Geocoding API

Permintaan Google Maps Geocoding API mengambil bentuk berikut:

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

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

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

Untuk mengakses Google Maps Geocoding API melalui HTTP, gunakan:

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

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.

Catatan: URL harus dienkodekan dengan benar agar valid dan dibatasi hingga 8192 karakter untuk semua layanan web. Perhatikan batas ini saat membuat URL Anda. Perhatikan, browser, proxy, dan server yang berbeda mungkin memiliki batas karakter URL yang berbeda pula.

Beberapa parameter diperlukan sementara sebagian lagi opsional. Sebagaimana standar dalam URL, parameter dipisah menggunakan karakter ampersand (&).

Bagian selebihnya dari laman ini menjelaskan geocoding dan geocoding terbalik secara terpisah, karena parameter yang berbeda tersedia untuk setiap tipe permintaan.

Geocoding (Pencarian Garis Lintang/Garis Bujur)

Parameter yang diperlukan dalam permintaan geocoding:

  • address — Alamat jalan yang ingin Anda geocode, dalam format yang digunakan oleh layanan pos nasional pada negara yang bersangkutan. Elemen alamat tambahan seperti nama bisnis dan unit, suite atau nomor lantai harus dihindari. Lihat FAQ untuk panduan tambahan.
         atau
    components - Filter komponen yang ingin Anda dapatkan geocode-nya. Lihat Pemfilteran Komponen untuk informasi selengkapnya. Filter komponen juga akan diterima sebagai parameter opsional jika address disediakan.
  • 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 Geocoding Anda. Dapatkan informasi selengkapnya tentang parameter autentikasi untuk pelanggan Premium Plan.

Parameter opsional dalam permintaan geocoding:

  • bounds — Kotak pembatas viewport yang akan digunakan untuk mencondongkan hasil geocode secara lebih jelas. Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. (Untuk informasi selengkapnya lihat Mencondongkan Viewport 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, geocoder akan berusaha menggunakan bahasa yang dipilih sebagaimana ditetapkan dalam header Accept-Language atau bahasa bawaan domain asal permintaan dikirim.
    • Geocoder 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, geocoder 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.
  • region — Kode region, ditetapkan sebagai nilai yang berisi dua karakter ccTLD ("top-level domain"). Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. (Untuk informasi selengkapnya, lihat Mencondongkan Region di bawah ini.)
  • components — Filter komponen, dipisah dengan karakter pipa (|). Setiap filter komponen terdiri dari sepasang component:value dan secara penuh membatasi hasil geocoder. Untuk informasi selengkapnya, lihat Pemfilteran Komponen di bawah ini.

Respons Geocoding

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

Dalam contoh ini, Google Maps Geocoding API meminta respons json untuk kueri terhadap "1600 Amphitheatre Parkway, Mountain View, CA".

Permintaan ini memperagakan penggunaan flag output JSON:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Permintaan ini memperagakan penggunaan flag output XML:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Klik tab di bawah ini untuk melihat contoh respons JSON dan XML.

JSON
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Pkwy",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Perhatikan, respons JSON berisi dua elemen akar:

  • "status" berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • "results" berisi larik informasi alamat dan informasi geometri yang telah di-geocode.

Biasanya, hanya satu entri dalam larik "results" yang dikembalikan untuk pencarian alamat , meskipun geocoder mungkin mengembalikan beberapa hasil bila kueri alamat tidak jelas.

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
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Pkwy</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
    <lat>37.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

Perhatikan, respons XML terdiri dari satu <GeocodeResponse> dan dua elemen tingkat atas:

  • <status> berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • Nol atau beberapa elemen <result>, masing-masing berisi satu set informasi alamat dan informasi geometri yang telah di-geocode.

Perhatikan, respons ini jauh lebih lama dari respons JSON. Karena itu, kami menyarankan Anda menggunakan json sebagai flag output yang dipilih kecuali jika layanan Anda memerlukan xml karena suatu alasan. Selain itu, 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 <GeocodeResponse> akar.
  • JSON menunjukkan entri yang memiliki beberapa elemen dengan larik plural (types), sementara XML menunjukkan hal ini dengan menggunakan beberapa elemen singular (<type>).
  • Elemen kosong ditunjukkan dengan larik kosong dalam JSON, namun dalam XML ditunjukkan dengan tidak adanya elemen seperti itu. Respons tanpa hasil akan mengembalikan larik results kosong dalam JSON, namun tidak ada elemen <result> dalam XML, misalnya.

Kode Status

Bidang "status" dalam objek respons Geocoding berisi status permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak penyebab geocoding tidak bekerja. Bidang "status" 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.
  • OVER_QUERY_LIMIT menunjukkan Anda telah melebihi kuota.
  • REQUEST_DENIED menunjukkan permintaan Anda ditolak.
  • INVALID_REQUEST biasanya menunjukkan kueri (address, components atau latlng) tidak ada.
  • "UNKNOWN_ERROR" menunjukkan permintaan tidak bisa diproses karena kesalahan server. Permintaan mungkin berhasil jika Anda mencoba lagi.

Pesan Kesalahan

Bila geocoder mengembalikan kode status selain OK, mungkin ada bidang error_message tambahan dalam objek respons Geocoding. 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.

Hasil

Bila geocoder mengembalikan hasilnya, maka akan ditempatkan dalam larik results (JSON). Sekalipun geocoder tidak mengembalikan hasil (misalnya jika alamat tidak ada) ia tetap mengembalikan larik results kosong. Respons XML terdiri dari nol atau beberapa elemen <result>.

Hasil pada umumnya terdiri dari bidang-bidang berikut:

  • Larik types[] menunjukkan tipe hasil yang dikembalikan. Larik ini berisi nol atau beberapa tag yang mengidentifikasi tipe fitur yang dikembalikan dalam hasil. Misalnya, geocode "Chicago" akan mengembalikan "locality" yang menunjukkan "Chicago" adalah kota, juga mengembalikan "political" yang menunjukkan Chicago adalah entitas politik.

  • formatted_address adalah string berisi alamat yang bisa dibaca orang untuk lokasi ini. Sering kali alamat ini sama dengan "alamat pos", yang terkadang berbeda antara satu negara dengan negara lainnya. (Perhatikan, beberapa negara, seperti Kerajaan Inggris, tidak memperbolehkan distribusi alamat pos sebenarnya karena adanya pembatasan pemberian lisensi.) Alamat ini biasanya terdiri dari satu atau beberapa komponen alamat. Misalnya, alamat "111 8th Avenue, New York, NY" berisi komponen alamat terpisah untuk "111" (nomor rumah), "8th Avenue" (rute), "New York" (kota) dan "NY" (negara bagian AS). Komponen alamat tersebut berisi informasi tambahan seperti yang disebutkan di bawah ini.

  • address_components[] adalah larik berisi komponen alamat terpisah, seperti dijelaskan di atas. Setiap address_component biasanya berisi:

    • types[] adalah larik yang menunjukkan tipe komponen alamat.
    • long_name adalah keterangan teks lengkap atau nama komponen alamat sebagaimana dikembalikan oleh Geocoder.
    • short_name adalah nama tekstual yang disingkat untuk komponen alamat, jika tersedia. Misalnya, komponen alamat untuk negara bagian Alaska dapat memiliki long_name "Alaska" dan short_name "AK" dengan menggunakan 2 huruf singkatan istilah pos.

    Perhatikan, address_components[] mungkin berisi komponen alamat lebih banyak daripada yang disebutkan dalam formatted_address.

  • postcode_localities[] adalah larik yang menunjukkan semua lokalitas yang dimuat dalam kode pos. Ini hanya ada bila hasilnya adalah kode pos yang berisi beberapa lokalitas.
  • geometry berisi informasi berikut:

    • location berisi nilai geocode garis lintang dan garis bujur. Untuk pencarian alamat normal, bidang ini biasanya yang paling penting.
    • location_type menyimpan data tambahan tentang lokasi yang ditetapkan. Nilai-nilai berikut saat ini didukung:

      • "ROOFTOP" menunjukkan hasil yang dikembalikan adalah geocode presisi yang informasi lokasinya kita miliki secara akurat dengan presisi hingga ke alamat jalan.
      • "RANGE_INTERPOLATED" menunjukkan hasil yang dikembalikan mencerminkan perkiraan (biasanya di jalan) interpolasi antara dua titik tepat (seperti persimpangan). Hasil interpolasi umumnya dikembalikan bila rooftop-geocode tidak tersedia untuk alamat jalan.
      • "GEOMETRIC_CENTER" menunjukkan hasil yang dikembalikan adalah pusat geometris dari hasil seperti polyline (misalnya, jalan) atau poligon (region).
      • "APPROXIMATE" menunjukkan hasil yang dikembalikan adalah perkiraan.
    • viewport berisi viewport yang disarankan untuk menampilkan hasil yang dikembalikan, ditetapkan sebagai dua nilai garis lintang/garis bujur yang mendefinisikan sudut southwest dan northeast dari kotak pembatas viewport. Biasanya viewport digunakan untuk membingkai hasil saat menampilkannya kepada pengguna.
    • bounds (dikembalikan secara opsional) menyimpan kotak pembatas yang sepenuhnya bisa berisi hasil yang dikembalikan. Perhatikan, batas-batas ini mungkin tidak cocok dengan viewport yang disarankan. (Misalnya, San Francisco menyertakan Farallon Islands, yang secara teknis merupakan bagian dari kota, namun mungkin tidak dikembalikan dalam viewport.)
  • 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 dalam permintaan Google Places API untuk mendapatkan detail bisnis setempat, seperti nomor telepon, jam buka, ulasan pengguna, dan lainnya. Lihat ringkasan ID tempat.

Karena tidak menjamin adanya format pasti dari respons individual terhadap permintaan Google Maps Geocoding API, maka Anda tidak boleh beranggapan bahwa elemen berada dalam posisi absolut. (Khususnya, jumlah address_components dalam respons Geocoding API bervariasi berdasarkan alamat yang diminta dan bisa berubah dari waktu ke waktu.) Sebagai gantinya, Anda harus mem-parse respons dan memilih nilai yang sesuai melalui ekspresi. Lihat Mem-parse Respons Web Service untuk informasi selengkapnya.

Tipe Alamat dan Tipe Komponen Alamat

Larik types[] dalam hasil menunjukkan tipe alamat. Contoh tipe alamat meliputi alamat jalan, negara, atau entitas politik. Ada juga larik types[] dalam address_components[], yang menunjukkan tipe setiap bagian alamat. Contohnya antara lain nomor rumah atau negara. (Di bawah ini adalah daftar lengkap tipe tersebut.) Alamat mungkin memiliki beberapa tipe. Tipe ini bisa dianggap sebagai "tag". Misalnya, banyak kota diberi tag dengan tipe political dan locality.

Tipe berikut ini didukung dan dikembalikan oleh geocoder dalam larik tipe alamat dan tipe komponen alamat:


  • 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.

Selain yang disebutkan di atas, komponen alamat mungkin menyertakan tipe-tipe di bawah ini.

Catatan: Daftar ini tidak lengkap dan bisa berubah.


  • floor menunjukkan lantai pada alamat bangunan.
  • establishment biasanya menunjukkan tempat yang belum dikategorikan.
  • point_of_interest menunjukkan tempat menarik yang telah diberi nama.
  • parking menunjukkan tempat parkir atau gedung parkir.
  • post_box menunjukkan kotak pos tertentu.
  • postal_town menunjukkan pengelompokan area geografis, seperti locality dan sublocality, yang digunakan untuk alamat pos di beberapa negara.
  • room menunjukkan kamar pada alamat bangunan.
  • street_number menunjukkan nomor rumah secara akurat.
  • bus_station, train_station dan transit_station menunjukkan lokasi perhentian bus, kereta api atau halte angkutan umum.

Mencondongkan Viewport

Dalam permintaan geocoding, Anda juga bisa menginstruksikan layanan Geocoding agar lebih memilih hasil dalam viewport yang diberikan (dinyatakan berupa kotak pembatas). Anda melakukannya dalam URL permintaan dengan menyetel parameter bounds. Perhatikan, pencondongan hanya mengutamakan hasil dalam batas-batas ini; jika hasil yang lebih relevan berada di luar batas-batas ini, mungkin akan disertakan.

Parameter bounds mendefinisikan koordinat garis lintang/garis bujur sudut barat daya dan timur laut kotak pembatas ini dengan menggunakan karakter pipa (|) untuk memisahkan koordinat.

Misalnya, geocode untuk "Winnetka" biasanya akan mengembalikan daerah pinggiran kota Chicago:

Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Akan tetapi, menambahkan argumen bounds yang mendefinisikan kotak pembatas untuk hasil San Fernando Valley, Los Angeles dalam geocode ini akan mengembalikan daerah sekitar bernama "Winnetka" di lokasi itu:

Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Mencondongkan Region

Dalam respons geocoding, Google Maps Geocoding API mengembalikan hasil alamat yang dipengaruhi oleh region (biasanya negara) yang menjadi asal pengiriman permintaan. Misalnya, penelusuran untuk "San Francisco" mungkin mengembalikan hasil yang berbeda jika dikirim dari domain di Amerika Serikat dibandingkan hasil yang dikirim dari Spanyol.

Anda bisa menyetel Google Maps Geocoding API agar mengembalikan hasil yang dicondongkan ke region tertentu 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").

Permintaan geocoding bisa dicondongkan untuk setiap domain tempat aplikasi utama Google Maps secara resmi diluncurkan. Perhatikan, pencondongan hanya mengutamakan hasil untuk domain tertentu; jika hasil yang lebih relevan ada di luar batas-batas ini, mungkin akan disertakan.

Misalnya, geocode untuk "Toledo" akan mengembalikan hasil ini, karena domain default untuk Google Maps Geocoding API disetel ke Amerika Serikat. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Permintaan geocoding untuk "Toledo" dengan region=es (Spanyol) akan mengembalikan kota di Spanyol. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Pemfilteran Komponen

Dalam respons geocoding, Google Maps Geocoding API bisa mengembalikan hasil alamat yang dibatasi pada area tertentu. Batasan ditetapkan menggunakan filter components. Filter terdiri dari daftar pasangan component:value yang dipisah dengan karakter pipa (|). Hanya hasil yang cocok dengan semua filter yang akan dikembalikan. Nilai-nilai filter mendukung metode yang sama untuk koreksi ejaan dan kecocokan parsial seperti permintaan geocoding lainnya. Jika hasil geocoding memiliki kecocokan parsial dengan filter komponen maka respons akan berisi bidang partial_match.

components yang bisa difilter meliputi:

  • route mencocokkan dengan nama panjang rute atau nama pendeknya.
  • locality mencocokkan dengan tipe locality maupun sublocality.
  • administrative_area mencocokkan dengan semua tingkat administrative_area.
  • postal_code mencocokkan dengan postal_code dan postal_code_prefix.
  • country mencocokkan dengan nama negara atau kode negara ISO 3166-1 dua huruf.

    Catatan:Kami mengikuti standar ISO untuk mendefinisikan negara, sehingga pemfilteran bekerja maksimal jika menggunakan kode ISO negara yang sesuai.

Catatan: Setiap komponen alamat hanya bisa ditetapkan dalam parameter alamat atau sebagai filter komponen, namun tidak boleh keduanya. Hal itu bisa mengakibatkan ZERO_RESULTS.

Geocode untuk "Santa Cruz" dengan components=country:ES akan mengembalikan Santa Cruz de Tenerife di Canary Islands, Spanyol. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Query yang berisi filter komponen hanya akan mengembalikan hasil geocoding yang cocok dengan filternya. Jika tidak ditemukan kecocokan, geocoder akan mengembalikan hasil yang cocok dengan filter itu sendiri. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Pemfilteran komponen akan mengembalikan respons ZERO_RESULTS hanya jika Anda memberikan filter yang saling mengecualikan. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Respons:

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

Filter components bisa digunakan untuk membuat kueri tanpa parameter alamat, namun Anda tidak bisa menetapkan komponen tanpa nilai. Permintaan:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Respons:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Geocoding Terbalik (Pencarian Alamat)

Istilah geocoding umumnya mengacu pada penerjemahan alamat yang bisa dibaca orang menjadi sebuah lokasi pada peta. Proses melakukan kebalikannya, yaitu menerjemahkan lokasi pada peta menjadi alamat yang bisa dibaca orang, dikenal sebagai geocoding terbalik.

Parameter yang diperlukan dalam permintaan geocoding terbalik:

  • latlng — Nilai garis lintang dan bujur yang menetapkan lokasi tempat Anda ingin mendapatkan alamat terdekat yang bisa dibaca manusia.
         atau
    place_id — ID tempat untuk lokasi yang ingin Anda peroleh alamatnya yang bisa dibaca manusia. ID tempat adalah sebuah identifier unik yang bisa digunakan bersama Google API lainnya. Misalnya, Anda bisa menggunakan placeId yang dikembalikan oleh Google Maps Roads API untuk mendapatkan alamat titik yang telah diikat. Untuk informasi selengkapnya tentang ID tempat, lihat ringkasan ID tempat. Nilai ini hanya bisa ditetapkan jika permintaan menyertakan kunci API atau ID klien Google Maps APIs Premium Plan.
  • 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 Geocoding terbalik Anda. Dapatkan informasi selengkapnya tentang parameter autentikasi untuk pelanggan Premium Plan.

Parameter opsional dalam permintaan geocoding terbalik:

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

  • 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, geocoder akan berusaha menggunakan bahasa yang dipilih sebagaimana ditetapkan dalam header Accept-Language atau bahasa bawaan domain asal permintaan dikirim.
    • Geocoder 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, geocoder menggunakan bahasa terdekat yang sesuai.
  • result_type — Satu atau beberapa tipe alamat, dipisah dengan karakter pipa (|). Contoh tipe alamat: country, street_address, postal_code. Untuk mengetahui daftar lengkap nilai yang diperbolehkan, lihat tipe alamat pada laman ini. Menetapkan tipe yang akan membatasi hasil untuk tipe ini. Jika ada beberapa tipe yang ditetapkan, API akan mengembalikan semua alamat yang cocok dengan tipe itu. Catatan: Parameter ini hanya tersedia untuk permintaan yang menyertakan kunci API atau ID klien.
  • location_type — Satu atau beberapa tipe lokasi, dipisah dengan karakter pipa (|). Menetapkan tipe yang akan membatasi hasil untuk tipe ini. Jika ada beberapa tipe yang ditetapkan, API akan mengembalikan semua alamat yang cocok dengan tipe itu. Catatan: Parameter ini hanya tersedia untuk permintaan yang menyertakan kunci API atau ID klien. Nilai-nilai berikut ini didukung:
    • "ROOFTOP" membatasi hasil pada alamat yang informasi lokasinya kita miliki secara akurat dengan presisi hingga ke alamat jalan.
    • "RANGE_INTERPOLATED" membatasi hasil pada sesuatu yang mencerminkan perkiraan (biasanya di jalan) interpolasi antara dua titik presisi (misalnya persimpangan). Kisaran interpolasi biasanya menunjukkan geocode atas-atap tidak tersedia untuk alamat jalan.
    • "GEOMETRIC_CENTER" membatasi hasil pada pusat geometris dari lokasi seperti polyline (misalnya, jalan) atau poligon (region).
    • "APPROXIMATE" membatasi hasil pada sesuatu yang digolongkan sebagai perkiraan.

Jika pembatasan result_type maupun location_type ada, maka API hanya akan mengembalikan hasil yang cocok dengan pembatasan result_type dan location_type.

Geocoding Terbalik untuk Garis Lintang/Garis Bujur

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

Catatan: Pastikan tidak ada spasi di antara nilai garis lintang dan bujur saat diteruskan di parameter latlng.

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 results[] ...

Perhatikan, geocoder terbalik akan mengembalikan lebih dari satu hasil. Hasil "formatted_address" tidak cuma berisi alamat pos, melainkan cara apa saja untuk menamai suatu lokasi secara geografis. Misalnya, saat geocoding titik di kota Chicago, titik yang diberi geocode bisa ditandai sebagai alamat jalan, sebagai kota (Chicago), sebagai negara bagian (Illinois) atau sebagai negara (Amerika Serikat). Semua adalah "alamat" untuk geocoder tersebut. Geocoder terbalik akan mengembalikan setiap tipe 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 dikembalikan oleh kueri sebelumnya akan ditampilkan di bawah ini.

"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 dikembalikan dari yang paling spesifik sampai ke yang paling tidak spesifik; alamat yang lebih tepat akan menjadi hasil yang paling menonjol, seperti dalam kasus ini. Perhatikan, kita mengembalikan berbagai tipe alamat, dari alamat jalan yang paling spesifik hingga entitas politik yang kurang spesifik seperti lingkungan, kota, county, negara bagian, dll. Jika Anda ingin mencocokkan tipe alamat tertentu, lihat bagian di bawah ini tentang membatasi hasil dengan tipe.

Catatan: Geocoding terbalik merupakan sebuah perkiraan. Geocoder akan mencoba untuk menemukan lokasi alamat yang paling dekat dalam toleransi tertentu. Jika tidak ditemukan kecocokkan, geocoder akan mengembalikan hasil nol.

Geocoding Terbalik untuk ID Tempat

Kueri berikut berisi ID tempat untuk lokasi di Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&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 Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "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 Ave, 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
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Geocoding Terbalik Dibatasi oleh Tipe

Contoh berikut membatasi alamat yang dikembalikan untuk alamat yang memiliki tipe lokasi ROOFTOP dan tipe 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: Pembatasan ini hanya berlaku 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

Bidang "status" dalam objek respons Geocoding berisi status permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak penyebab geocoding terbalik tidak bekerja. Bidang "status" bisa berisi nilai berikut:

  • OK menunjukkan tidak terjadi kesalahan dan setidaknya satu alamat dikembalikan.
  • ZERO_RESULTS menunjukkan geocoding terbalik berhasil namun tidak mengembalikan hasil. Ini bisa terjadi jika pada geocoder itu diteruskan latlng di lokasi terpencil.
  • OVER_QUERY_LIMIT menunjukkan Anda telah melebihi kuota.
  • REQUEST_DENIED menunjukkan permintaan Anda ditolak. Mungkin karena permintaan menyertakan parameter result_type atau location_type namun tidak menyertakan kunci API atau ID klien.
  • "INVALID_REQUEST" biasanya menunjukkan salah satu hal berikut:
    • Kueri (address, components atau latlng) tidak ada.
    • Diberikan result_type atau location_type yang tidak valid.
  • "UNKNOWN_ERROR" menunjukkan permintaan tidak bisa diproses karena kesalahan server. Permintaan mungkin berhasil jika Anda mencoba lagi.

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 Geocoding API
Google Maps Geocoding API
Butuh bantuan? Kunjungi halaman dukungan kami.