Permintaan
Permintaan Geocoding API menggunakan format berikut:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
dengan outputFormat
dapat berupa salah satu nilai berikut:
json
(direkomendasikan) menunjukkan output dalam JavaScript Object Notation (JSON); atauxml
menunjukkan output dalam XML
HTTPS diperlukan.
Beberapa parameter diperlukan sementara sebagian lagi opsional. Sebagaimana standar dalam URL,
parameter dipisahkan menggunakan karakter ampersand (&
).
Bagian selebihnya dari halaman ini menjelaskan geocoding dan geocoding terbalik secara terpisah, karena parameter yang berbeda tersedia untuk setiap jenis permintaan.
Parameter geocoding (pencarian lintang/bujur)
Parameter yang diperlukan dalam permintaan geocoding:
address
— Alamat atau plus code yang ingin Anda geocode. Tentukan alamat sesuai dengan format digunakan oleh layanan pos nasional untuk negara yang bersangkutan. Tambahan elemen alamat seperti nama dan unit bisnis, nomor suite atau lantai harus dihindari. Elemen alamat harus dipisahkan dengan spasi (ditampilkan di sini sebagai URL yang di-escape ke%20
): Format plus code seperti yang ditampilkan di sini (tanda plus di-escape URL keaddress=24%20Sussex%20Drive%20Ottawa%20ON
%2B
dan spasi dikonversi ke%20
):- kode global adalah kode area 4 karakter dan 6 karakter atau lebih
kode lokal (849VCWC8+R9 adalah
849VCWC8%2BR9
). - kode majemuk adalah kode lokal berisi 6 karakter atau lebih dengan
lokasi eksplisit (CWC8+R9 Mountain View, CA, USA adalah
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--ATAU--
components
— Filter komponen dengan elemen yang dipisahkan oleh pipa (|
). Filter komponen juga diterima sebagai parameter opsional jikaaddress
disediakan. Setiap elemen dalam filter komponen terdiri dari pasangancomponent:value
, dan sepenuhnya membatasi hasil dari geocoder. Lihat informasi selengkapnya tentang pemfilteran komponen di bawah.- kode global adalah kode area 4 karakter dan 6 karakter atau lebih
kode lokal (849VCWC8+R9 adalah
key
— Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk tujuan manajemen kuota. Pelajari cara mendapatkan kunci.
Lihat FAQ untuk panduan tambahan.
Parameter opsional dalam permintaan Geocoding:
bounds
— Kotak pembatas area tampilan yang akan digunakan untuk membiaskan hasil geocode secara lebih jelas. Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. (Untuk selengkapnya lihat Pembiasan Area Pandang di bawah ini.)language
— Bahasa yang akan digunakan menampilkan hasil.- Lihat daftar layanan yang didukung bahasa. Google sering memperbarui bahasa yang didukung, sehingga mungkin tidak lengkap.
- Jika
language
tidak diberikan, geocoder akan mencoba untuk gunakan bahasa pilihan seperti yang ditentukan dalam headerAccept-Language
, atau bahasa asli domain tempat permintaan dikirim. - Geocoder akan melakukan yang terbaik untuk menyediakan alamat yang dapat dibaca oleh pengguna dan lokal. Untuk mencapai sasaran tersebut, mengembalikan alamat dalam bahasa lokal, ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika diperlukan, dengan mengamati di bahasa target. Semua alamat lain dikembalikan ke instance di bahasa target. Semua komponen alamat dikembalikan dalam bahasa yang sama, yang dipilih dari komponen pertama.
- Jika nama tidak tersedia dalam bahasa yang dipilih, geocoder akan menggunakan nama terdekat yang sesuai.
- Bahasa yang dipilih berpengaruh kecil terhadap serangkaian hasil yang dipilih API untuk ditampilkan, dan urutan pengembaliannya. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa yang umum, seperti singkatan jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa tetapi tidak valid dalam bahasa lain. Misalnya, utca dan tér adalah sinonim untuk jalan dan persegi dalam bahasa Hungaria.
region
— Kode wilayah, yang ditetapkan sebagai nilai dua karakter ccTLD ("domain level teratas"). Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. (Untuk selengkapnya lihat informasi Pembiasan Wilayah di bawah ini.) Tujuan parameter juga dapat memengaruhi hasil berdasarkan hukum yang berlaku.components
— Filter komponen dengan elemen dipisahkan oleh pipa (|
). Filter komponen adalah wajib jika permintaan tidak menyertakanaddress
. Setiap elemen dalam filter komponen terdiri dari sebuahcomponent:value
pasangan, dan sepenuhnya membatasi hasil dari geocoder tersebut. Lihat informasi selengkapnya tentang pemfilteran komponen di bawah.extra_computations
— Gunakan parameter ini untuk menentukan fitur tambahan berikut ini dalam responsnya:ADDRESS_DESCRIPTORS
— Lihat deskripsi alamat untuk detail selengkapnya.BUILDING_AND_ENTRANCES
— Lihat pintu masuk dan garis batas bangunan untuk mengetahui detail selengkapnya.
extra_computations
dalam permintaan untuk setiap fitur, misalnya:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Respons
Respons geocoding ditampilkan dalam format yang ditunjukkan oleh tanda output
dalam permintaan URL, atau dalam format JSON secara default.
Dalam contoh ini, Geocoding API meminta respons json
untuk kueri di alamat "1600 Amphitheatre Parkway, Mountain View, CA".
Permintaan ini menunjukkan penggunaan tanda output
JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Permintaan ini menunjukkan penggunaan flag output
XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Pilih tab di bawah untuk melihat contoh respons JSON dan XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Perhatikan, respons JSON berisi dua elemen akar:
"status"
berisi metadata pada permintaan. Lihat Kode status di bawah."results"
berisi array informasi alamat dan informasi geometri yang telah di-geocode.
Umumnya, hanya satu entri dalam array "results"
yang ditampilkan untuk
pencarian alamat, meskipun geocoder mungkin menampilkan beberapa hasil ketika alamat
bersifat ambigu.
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 Parkway</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>Santa Clara County</long_name> <short_name>Santa Clara County</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.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Perhatikan, respons XML terdiri dari satu
<GeocodeResponse>
dan dua elemen tingkat atas:
<status>
berisi metadata pada permintaan. Lihat Kode status di bawah.- Nol atau beberapa elemen
<result>
, masing-masing berisi satu sekumpulan informasi alamat dan informasi geometri yang telah di-geocode.
Respons XML jauh lebih panjang daripada respons JSON. Sebagai
oleh karena itu, sebaiknya gunakan json
flag output kecuali jika layanan Anda memerlukan xml
karena alasan tertentu.
Selain itu, pemrosesan hierarki XML memerlukan kehati-hatian, sehingga Anda mereferensikan
simpul dan elemen yang tepat. Lihat
Mengurai XML dengan XPath untuk beberapa pola desain yang direkomendasikan untuk pemrosesan output.
- Hasil XML digabungkan dalam elemen
<GeocodeResponse>
root. - JSON menunjukkan entri yang memiliki beberapa elemen dengan array jamak (
types
), sedangkan XML menunjukkannya dengan menggunakan beberapa elemen tunggal (<type>
). - Elemen kosong ditunjukkan melalui array kosong dalam JSON, tetapi tidak ada elemen tersebut di XML. Respons yang tidak memunculkan hasil akan menampilkan nilai kosong
Array
results
di JSON, tetapi tidak ada elemen<result>
di XML, ke titik akhir pelanggan.
Kode status
Kolom "status"
dalam objek respons Geocoding berisi status
permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak alasan mengapa geocoding
tidak berfungsi. Kolom "status"
dapat berisi nilai berikut:
"OK"
menunjukkan bahwa tidak terjadi error; alamat berhasil diuraikan dan setidaknya satu geocode ditampilkan."ZERO_RESULTS"
menunjukkan bahwa geocoding berhasil, tetapi ditampilkan tanpa hasil. Hal ini dapat terjadi jikaaddress
yang tidak ada diteruskan ke geocoder.OVER_DAILY_LIMIT
menunjukkan salah satu dari hal berikut:- Kunci API tidak ada atau tidak valid.
- Penagihan belum diaktifkan pada akun Anda.
- Batas penggunaan yang Anda tetapkan sendiri telah terlampaui.
- Metode pembayaran yang diberikan tidak lagi valid (misalnya, masa berlaku kartu kredit telah berakhir).
Lihat FAQ Maps untuk mempelajari cara memperbaiki ini.
"OVER_QUERY_LIMIT"
menunjukkan bahwa Anda melebihi kuota."REQUEST_DENIED"
menunjukkan permintaan Anda ditolak."INVALID_REQUEST"
secara umum menunjukkan bahwa kueri (address
,components
, ataulatlng
) tidak ada."UNKNOWN_ERROR"
menunjukkan bahwa permintaan tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.
Pesan error
Jika geocoder menampilkan kode status selain OK
, mungkin ada parameter tambahan
Kolom error_message
dalam objek respons Geocoding. Bidang ini berisi lebih banyak
informasi mendetail tentang alasan di balik kode status yang diberikan.
Hasil
Saat geocoder menampilkan hasilnya, geocoder akan menempatkannya dalam results
(JSON)
. Meskipun geocoder tidak menampilkan hasil (misalnya jika alamat tidak ada), geocoder tetap menampilkan array results
kosong. (Respons XML terdiri dari nol atau beberapa elemen <result>
.)
Hasil biasanya berisi kolom berikut:
- Array
types[]
menunjukkan jenis hasil yang ditampilkan. {i>Array<i} ini berisi nol atau beberapa {i>tag<i} yang mengidentifikasi jenis fitur yang ditampilkan dalam hasil. Misalnya, geocode "Chicago" mengembalikan "lokalitas" yang menunjukkan bahwa "Chicago" adalah kota, dan juga menampilkan nilai "politik" yang menunjukkan bahwa iklan itu adalah entitas politik. Komponen mungkin memiliki array jenis kosong jika tidak ada jenis yang diketahui untuk komponen alamat tersebut. API mungkin menambahkan nilai jenis baru sesuai kebutuhan. Untuk mengetahui informasi selengkapnya, lihat Jenis alamat dan komponen alamat. formatted_address
adalah string yang berisi string yang dapat dibaca manusia alamat lokasi ini.Sering kali alamat ini sama dengan alamat pos. Harap ingat bahwa beberapa negara, seperti Inggris Raya, tidak mengizinkan distribusi alamat pos sebenarnya karena adanya pembatasan pemberian lisensi.
Alamat yang diformat secara logis terdiri dari satu atau beberapa komponen alamat. Misalnya, alamat "111 8th Avenue, New York, NY" terdiri atas komponen berikut: "111" (nomor jalan), "8th Avenue" (rute), "New York" (kota), dan "NY" (negara bagian AS).
Jangan mengurai alamat berformat secara terprogram. Sebagai gantinya, Anda harus menggunakan komponen alamat individual, yang disertakan oleh respons API selain kolom alamat yang diformat.
address_components[]
adalah array yang berisi class komponen yang berlaku untuk alamat ini.Setiap komponen alamat biasanya berisi kolom berikut:
types[]
adalah array yang menunjukkan jenis komponen alamat. Lihat daftar jenis yang didukung.long_name
adalah deskripsi teks lengkap atau nama komponen alamat seperti yang ditampilkan oleh Geocoder.short_name
adalah nama tekstual yang disingkat untuk komponen alamat, jika tersedia. Misalnya, komponen alamat untuk negara bagian Alaska dapat memilikilong_name
"Alaska" danshort_name
"AK" menggunakan 2 huruf singkatan istilah pos.
Perhatikan fakta berikut tentang array
address_components[]
:- Array komponen alamat dapat berisi lebih banyak komponen daripada
formatted_address
. - Array tidak harus selalu menyertakan semua entitas politik yang
berisi alamat, selain dari yang disertakan dalam
formatted_address
. Untuk mengambil semua entitas politik yang berisi alamat tertentu, Anda harus menggunakan geocoding terbalik, yang meneruskan garis lintang/bujur alamat sebagai parameter ke permintaan tersebut. - Format respons tidak dijamin tetap sama di antara
permintaan. Secara khusus, jumlah
address_components
bervariasi berdasarkan alamat yang diminta dan dapat berubah dari waktu ke waktu untuk alamat yang sama. Komponen dapat mengubah posisi dalam array. Jenis komponen dapat berubah. Komponen tertentu mungkin tidak ada dalam respons berikutnya.
Untuk menangani array komponen, Anda harus mengurai respons dan memilih nilai yang sesuai melalui ekspresi. Lihat panduan untuk menguraikan respons.
postcode_localities[]
adalah array yang menunjukkan hingga 100 lokalitas yang terdapat dalam kode pos. Ini hanya ada jika hasilnya adalah pos yang berisi beberapa lokalitas.geometry
berisi informasi berikut:location
berisi nilai geocode dari garis lintang dan bujur. Untuk normal pencarian alamat, bidang ini biasanya yang paling penting.location_type
menyimpan data tambahan tentang lokasi yang ditentukan. Tujuan nilai berikut saat ini didukung:"ROOFTOP"
menunjukkan bahwa hasil yang ditampilkan adalah geocode akurat untuk yang memiliki informasi lokasi yang akurat hingga alamat yang tepat."RANGE_INTERPOLATED"
menunjukkan bahwa hasil yang ditunjukkan mencerminkan perkiraan (biasanya di jalan) interpolasi antara dua titik tepat (seperti persimpangan). Hasil interpolasi umumnya dikembalikan bila rooftop-geocode tidak tersedia untuk suatu jalan alamat IPv6"GEOMETRIC_CENTER"
menunjukkan bahwa hasil yang ditampilkan adalah pusat geometris dari hasil seperti polyline (misalnya, jalan) atau poligon (wilayah)."APPROXIMATE"
menunjukkan bahwa hasil yang ditampilkan adalah perkiraan.
viewport
berisi area pandang yang direkomendasikan untuk ditampilkan hasil yang dikembalikan, ditetapkan sebagai dua nilai garis lintang dan garis bujur yangsouthwest
dan Sudutnortheast
kotak pembatas area pandang. Umumnya area pandang digunakan untuk membingkai hasil saat menampilkannya kepada pengguna.bounds
(ditampilkan secara opsional) menyimpan kotak pembatas yang bisa sepenuhnya berisi hasil yang ditampilkan. Perhatikan, batas-batas ini mungkin tidak cocok dengan area pandang yang direkomendasikan. (Misalnya, San Francisco menyertakan Farallon Island, yang secara teknis merupakan bagian dari kota, namun mungkin tidak boleh ditampilkan dalam area pandang.)
-
plus_code
(lihat Open Location Code dan Plus Codes) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat x 1/8000 derajat (sekitar 14 m x 14 m di khatulistiwa) atau lebih kecil. {i>Plus Codes<i} dapat digunakan sebagai pengganti alamat di tempat yang tidak memiliki alamat (jika gedung tidak ada diberi nomor atau jalan tidak diberi nama). API tidak selalu menampilkan kode plus.Jika layanan menampilkan plus code, kode tersebut diformat sebagai kode global dan kode gabungan:
global_code
adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9).compound_code
adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9, Mountain View, CA, USA). Jangan mengurai konten ini secara terprogram.
-
partial_match
menunjukkan bahwa geocoder tidak menampilkan kecocokan persis untuk permintaan asli, meskipun jika geocoder dapat menampilkan kecocokan parsial dengan alamat yang diminta. Sebaiknya Anda memeriksa permintaan asal untuk mengetahui keberadaan 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 ditampilkan jika sebuah permintaan memiliki kecocokan terhadap dua atau beberapa lokasi di daerah yang sama. Misalnya, "Hillpar St, Bristol, UK" akan menampilkan kecocokan sebagian 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
bersifat unik yang dapat digunakan bersama Google API lainnya. Sebagai contoh, Anda dapat menggunakanplace_id
di Permintaan Places API untuk mendapatkan detail bisnis lokal, seperti nomor telepon, jam buka, pengguna ulasan, dan lainnya. Lihat ID tempat ringkasan.
Jenis alamat dan jenis komponen alamat
Array types[]
dalam hasil menunjukkan
jenis alamat. Contoh jenis alamat meliputi alamat,
negara, atau entitas politik. Terdapat juga array types[]
di
address_components[]
, yang menunjukkan jenis setiap bagian dari
alamat IPv6 Contohnya antara lain nomor rumah atau negara. (Di bawah ini adalah daftar lengkap
types.) Alamat mungkin memiliki beberapa tipe. Jenis-jenis ini dapat dianggap sebagai 'tag'.
Misalnya, banyak kota diberi tag dengan jenis political
dan
locality
.
Jenis berikut didukung dan ditampilkan oleh geocoder dalam jenis alamat dan array jenis komponen alamat:
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 ditampilkan 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 pendek 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 kita 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
hinggasublocality_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 namapremise
menunjukkan lokasi yang telah diberi nama, biasanya bangunan atau sekumpulan bangunan dengan nama umumsubpremise
menunjukkan entitas urutan pertama di bawah lokasi yang telah diberi nama, biasanya sebuah bangunan dalam sekumpulan bangunan dengan nama umumplus_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 ke dalam kategori lain, seperti "Empire State Building" atau "Eiffel Tower".
Daftar kosong dari jenis menunjukkan tidak ada jenis yang diketahui untuk komponen alamat tertentu, misalnya Lieu-dit di Prancis.
Selain yang disebutkan di atas, komponen alamat mungkin menyertakan jenis yang tercantum di sini. Daftar ini tidak lengkap dan dapat berubah sewaktu-waktu.
floor
menunjukkan lantai alamat gedung.establishment
biasanya menunjukkan tempat yang belum dikategorikan.landmark
menunjukkan tempat terdekat yang digunakan sebagai referensi, untuk membantu navigasi.point_of_interest
menunjukkan lokasi menarik yang telah diberi nama.parking
menunjukkan tempat parkir atau gedung parkir.post_box
menunjukkan kotak pos tertentu.postal_town
menunjukkan pengelompokkan area geografis, sepertilocality
dansublocality
, yang digunakan untuk alamat surat di beberapa negara.room
menunjukkan ruang pada alamat gedung.street_number
menunjukkan nomor jalan yang akurat.bus_station
,train_station
dantransit_station
menunjukkan lokasi perhentian bus, kereta api, atau transportasi umum.
Pembiasan area pandang
Dalam permintaan Geocoding, Anda dapat menginstruksikan layanan Geocoding agar lebih memilih hasil dalam area pandang tertentu (dinyatakan dalam bentuk kotak pembatas). Anda yang harus melakukannya
dalam URL permintaan dengan menyetel parameter bounds
.
Parameter bounds
menentukan koordinat lintang/bujur
sudut barat daya dan timur laut kotak pembatas ini menggunakan pipa
(|
) untuk memisahkan koordinat.
Misalnya, geocode untuk "Washington" biasanya akan menampilkan negara bagian Washington di Amerika Serikat:
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Respons:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Namun, menambahkan argumen bounds
yang menentukan kotak pembatas di sekitar
hasil di bagian timur laut AS dalam geocode ini akan menampilkan kota
Washington, D.C.:
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Respons:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Pembiasan wilayah
Dalam permintaan Geocoding, Anda dapat menginstruksikan layanan Geocoding agar menampilkan
hasil dibiaskan ke wilayah tertentu menggunakan region
. Parameter ini menggunakan ccTLD (kode negara level teratas
domain) yang menentukan bias wilayah. Sebagian besar kode ccTLD identik dengan
Kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, Amerika Serikat
ccTLD Kingdom adalah "uk" (.co.uk
) sedangkan kode ISO 3166-1-nya adalah "gb"
(secara teknis untuk entitas "Inggris Raya dan
Irlandia Utara").
Hasil geocoding bisa dibiaskan untuk setiap domain yang Aplikasi Google Maps secara resmi diluncurkan. Perhatikan bahwa hanya pembiasan mengutamakan hasil untuk domain tertentu; jika ada hasil yang lebih relevan luar domain, mereka mungkin akan disertakan.
Misalnya, geocode untuk "Toledo" akan mengembalikan hasil ini, domain untuk Geocoding API ditetapkan ke United States. 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.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Permintaan Geocoding untuk "Toledo" dengan region=es
(Spanyol) akan
mengembalikan kota Spanyol.
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Respons:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "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, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Pemfilteran komponen
Dalam respons Geocoding, Geocoding API dapat menampilkan hasil alamat yang dibatasi pada area tertentu. Anda dapat menetapkan pembatasan menggunakan
filter components
. Sebuah filter terdiri
dari daftar
component:value
pasangan dipisahkan oleh pipa (|
).
Nilai filter mendukung metode yang sama untuk koreksi ejaan dan sebagian
cocok dengan permintaan Geocoding lainnya. Jika geocoder menemukan kecocokan parsial untuk
filter komponen, responsnya akan berisi kolom partial_match
.
components
yang dapat difilter meliputi:
postal_code
cocok denganpostal_code
danpostal_code_prefix
.country
cocok dengan nama negara atau kode negara ISO 3166-1 dua huruf. API mengikuti standar ISO untuk menentukan negara, dan pemfilteran akan berfungsi maksimal saat menggunakan kode ISO negara yang sesuai.
components
berikut dapat digunakan untuk memengaruhi hasil, tetapi tidak akan
diberlakukan:
route
cocok dengan nama panjang atau nama pendek rute.locality
cocok dengan jenislocality
dansublocality
.administrative_area
cocok dengan semuaadministrative_area
level.
Catatan tentang pemfilteran komponen:
- Jangan mengulangi filter komponen ini dalam permintaan, atau API akan menampilkan
Invalid_request
:country
,postal_code
,route
- Jika permintaan berisi filter komponen berulang, API akan mengevaluasi filter tersebut sebagai AND, bukan OR.
- Hasilnya konsisten dengan Google Maps, yang terkadang menghasilkan
respons
ZERO_RESULTS
yang tidak terduga. Menggunakan Place Autocomplete mungkin memberikan hasil yang lebih baik dalam beberapa kasus penggunaan. Untuk mempelajari lebih lanjut, lihat FAQ ini. - Untuk setiap komponen alamat, tentukan dalam
address
atau dalam filtercomponents
, tetapi tidak keduanya. Menentukan nilai yang sama di keduanya dapat menghasilkanZERO_RESULTS
.
Geocode untuk "High St, Hastings" dengan components=country:GB
menampilkan hasil di Hastings, Inggris, bukan di Hastings-On-Hudson, Amerika Serikat.
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Respons:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Permintaan geocode untuk lokalitas "Santa Cruz" dengan components=country:ES
mengembalikan Santa Cruz de Tenerife di Kepulauan Canary, Spanyol.
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|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" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "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"
}
Pemfilteran komponen menampilkan respons ZERO_RESULTS
hanya jika Anda menyediakan filter yang mengecualikan satu sama lain.
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Respons:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Anda dapat membuat kueri yang valid tanpa parameter alamat, menggunakan
Filter components
. (Saat melakukan geocoding alamat lengkap,
parameter address
diperlukan jika permintaan berisi
nama dan nomor bangunan.)
Permintaan:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Respons:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}