Respons dan permintaan geocoding

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

Permintaan

Permintaan Geocoding API menggunakan format berikut:

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

dengan outputFormat mungkin salah satu dari nilai berikut:

  • json (direkomendasikan) menunjukkan output dalam JavaScript Object Notation (JSON); atau
  • xml menunjukkan output dalam XML

HTTPS diperlukan untuk permintaan yang menggunakan kunci API.

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

Bagian selanjutnya 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 kode plus yang ingin Anda geocoding. Tetapkan alamat sesuai dengan format yang digunakan oleh layanan pos nasional di negara terkait. Elemen alamat tambahan seperti nama bisnis dan unit, suite, atau nomor lantai harus dihindari. Elemen alamat harus dipisahkan dengan spasi (ditampilkan di sini sebagai URL yang di-escape ke %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Format plus kode seperti yang ditunjukkan di sini (tanda plus diubah ke bentuk URL menjadi %2B dan spasi diubah ke bentuk URL menjadi %20):
    • kode global adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9 adalah 849VCWC8%2BR9).
    • kode majemuk adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9 Mountain View, CA, USA adalah CWC8%2BR9%20Mountain%20View%20CA%20USA).

    --OR--
    components — Filter komponen dengan elemen yang dipisahkan dengan pipa (|). Filter komponen juga diterima sebagai parameter opsional jika address disediakan. Setiap elemen dalam filter komponen terdiri dari pasangan component:value, dan sepenuhnya membatasi hasil dari geocoder. Lihat informasi selengkapnya tentang pemfilteran komponen di bawah.
  • key — Kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk tujuan pengelolaan kuota. Pelajari cara mendapatkan kunci.

Lihat FAQ untuk panduan tambahan.

Parameter opsional dalam permintaan Geocoding:

  • bounds — Kotak pembatas area pandang untuk mencondongkan hasil geocoding secara lebih jelas. Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. (Untuk informasi selengkapnya, lihat Mencondongkan Area Pandang di bawah.)
  • language — Bahasa yang digunakan untuk menampilkan hasil.
    • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
    • Jika language tidak disediakan, geocoder akan mencoba menggunakan bahasa pilihan seperti yang ditentukan dalam header Accept-Language, atau bahasa asli domain tempat permintaan dikirim.
    • Geocoder akan menyediakan cara terbaik untuk menyediakan alamat yang dapat dibaca oleh pengguna dan lokal. Untuk mencapai sasaran tersebut, API akan menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi menjadi skrip yang dapat dibaca oleh pengguna jika perlu, dengan mengamati bahasa yang dipilih. Semua alamat lainnya ditampilkan dalam bahasa yang diinginkan. Semua komponen alamat ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa pilihan, geocoder akan menggunakan yang paling cocok.
    • Bahasa pilihan tersebut memiliki pengaruh kecil pada kumpulan hasil yang dipilih oleh API untuk ditampilkan, dan urutan hasil ditampilkan. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa tetapi tidak dalam bahasa lain. Misalnya, utca dan tér adalah sinonim untuk jalan dan persegi masing-masing dalam bahasa Hungaria.
  • region — Kode wilayah, yang ditentukan sebagai nilai dua karakter ccTLD ("domain level teratas"). Parameter ini hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. Untuk informasi selengkapnya, lihat Biasing Wilayah di bawah ini.)
  • components — Filter komponen dengan elemen yang dipisahkan oleh pipa (|). Filter komponen wajib jika permintaan tidak menyertakan address. Setiap elemen dalam filter komponen terdiri dari pasangan component:value, dan sepenuhnya membatasi hasil dari geocoder. Lihat informasi selengkapnya tentang pemfilteran komponen di bawah.

Respons

Respons Geocoding ditampilkan dalam format yang ditunjukkan oleh tanda output dalam jalur permintaan URL.

Dalam contoh ini, Geocoding API meminta respons json untuk kueri pada ID tempat "ChIJeRpOeF67j4AR9ydy_PIzPuM", yang merupakan place_ID untuk bangunan di 1600 Amphitheatre Parkway, Mountain View, CA.

Permintaan ini menunjukkan penggunaan flag output JSON:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Permintaan ini menunjukkan penggunaan flag output XML:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

Perhatikan, respons JSON berisi dua elemen akar:

  • "status" berisi metadata yang diminta. Lihat Kode status di bawah.
  • "results" berisi array informasi alamat dan geometri yang di-geocoding.

Umumnya, hanya satu entri dalam array "results" yang akan ditampilkan untuk pencarian alamat,meskipun geocoder mungkin menampilkan beberapa hasil jika kueri alamatnya tidak jelas.

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 bahwa respons XML terdiri dari satu <GeocodeResponse> dan dua elemen level atas:

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

Respons XML jauh lebih lama daripada respons JSON. Oleh karena itu, sebaiknya gunakan json sebagai flag output pilihan Anda kecuali jika layanan Anda memerlukan xml karena alasan tertentu. Selain itu, pemrosesan hierarki XML memerlukan perhatian, sehingga Anda mereferensikan node dan elemen yang tepat. Lihat Menguraikan XML dengan XPath untuk mengetahui beberapa pola desain yang direkomendasikan bagi pemrosesan output.

  • Hasil XML digabungkan dalam elemen <GeocodeResponse> root.
  • JSON menunjukkan entri yang memiliki beberapa elemen dengan array jamak (types), sedangkan XML menunjukkannya dengan beberapa elemen tunggal (<type>).
  • Elemen kosong ditunjukkan melalui array kosong dalam JSON, tetapi tidak ditemukannya elemen tersebut dalam XML. Respons yang tidak menampilkan hasil akan menampilkan array results kosong dalam JSON, tetapi tidak menampilkan elemen <result> dalam XML, misalnya.

Kode status

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

  • "OK" menunjukkan bahwa tidak terjadi error; alamat berhasil diuraikan dan setidaknya satu geocode dikembalikan.
  • "ZERO_RESULTS" menunjukkan bahwa geocode berhasil, tetapi dikembalikan tanpa hasil. Hal ini dapat terjadi jika pada geocoder diteruskan address yang tidak ada.
  • OVER_DAILY_LIMIT menunjukkan salah satu hal berikut:
    • Kunci API tidak ada atau tidak valid.
    • Penagihan belum diaktifkan di akun Anda.
    • Batas penggunaan yang ditetapkan sendiri telah terlampaui.
    • Metode pembayaran yang diberikan sudah tidak valid (misalnya kartu kredit yang sudah tidak berlaku).

    Lihat FAQ Maps untuk mempelajari cara memperbaikinya.

  • "OVER_QUERY_LIMIT" menunjukkan bahwa Anda melebihi kuota.
  • "REQUEST_DENIED" menunjukkan permintaan Anda ditolak.
  • "INVALID_REQUEST" secara umum menunjukkan bahwa kueri (address, components, atau latlng) tidak ada.
  • "UNKNOWN_ERROR" menunjukkan permintaan tidak bisa diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.

Pesan error

Jika geocoder menampilkan kode status selain OK, mungkin ada kolom error_message tambahan dalam objek respons Geocoding. Kolom ini berisi informasi yang lebih mendetail tentang alasan di balik kode status yang diberikan.

Hasil

Saat geocoder menampilkan hasil, widget tersebut akan menempatkannya dalam array results (JSON). Meskipun geocoder tidak menampilkan hasil (seperti jika alamat tidak ada), coroutine masih menampilkan array results kosong. (Respons XML terdiri dari nol atau beberapa elemen <result>.)

Hasil umum berisi kolom berikut:

  • Array types[] menunjukkan jenis hasil yang ditampilkan. Array ini berisi serangkaian tag nol atau lebih yang mengidentifikasi jenis fitur yang ditampilkan dalam hasil. Misalnya, geocode "Chicago" akan menampilkan "lokalitas" yang menunjukkan bahwa "Chicago" adalah kota, dan juga menampilkan "politik" yang menunjukkan bahwa itu adalah entitas politik.
  • formatted_address adalah string yang berisi alamat lokasi ini yang dapat dibaca manusia.

    Sering kali alamat ini sama dengan alamat pos. Perhatikan, beberapa negara, seperti Kerajaan Inggris, 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 komponen terpisah 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 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 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 semua lokalitas yang terdapat dalam kode pos. Ini hanya ada jika hasilnya adalah kode pos yang berisi beberapa lokalitas.
  • geometry berisi informasi berikut:
    • location berisi nilai lintang dan bujur yang di-geocoding. Untuk pencarian alamat normal, kolom ini biasanya yang paling penting.
    • location_type menyimpan data tambahan tentang lokasi yang ditentukan. Nilai-nilai berikut saat ini didukung:

      • "ROOFTOP" menunjukkan bahwa hasil yang ditampilkan adalah geocode akurat yang informasi lokasinya kita miliki secara akurat dengan presisi hingga ke alamat jalan.
      • "RANGE_INTERPOLATED" menunjukkan bahwa hasil yang ditampilkan mencerminkan perkiraan (biasanya di jalan) interpolasi antara dua titik akurat (seperti persimpangan). Hasil interpolasi umumnya ditampilkan jika geocode rooftop tidak tersedia untuk alamat jalan.
      • "GEOMETRIC_CENTER" menunjukkan bahwa hasil yang ditampilkan adalah pusat geometris dari hasil seperti polyline (misalnya, jalan) atau poligon (region).
      • "APPROXIMATE" menunjukkan bahwa hasil yang ditampilkan adalah perkiraan.
    • viewport berisi area pandang yang direkomendasikan untuk menampilkan hasil yang ditampilkan, yang ditentukan sebagai dua nilai lintang dan bujur yang menentukan sudut southwest dan northeast dari kotak pembatas area pandang. Umumnya area pandang digunakan untuk membingkai hasil saat menampilkannya kepada pengguna.
    • bounds (secara opsional ditampilkan) menyimpan kotak pembatas yang dapat sepenuhnya berisi hasil yang ditampilkan. Perhatikan bahwa batas ini mungkin tidak cocok dengan area pandang yang direkomendasikan. (Misalnya, San Francisco menyertakan Farallon Islands, yang secara teknis merupakan bagian dari kota, tetapi mungkin tidak boleh ditampilkan di area pandang.)
  • plus_code (lihat Buka Kode Lokasi dan kode plus) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat kali 1/8.000 derajat (sekitar 14 x 14 m pada khatulistiwa) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat yang tidak ada (tempat bangunan tidak diberi nomor atau jalan tidak diberi nama).

    Plus Codes 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.
    Biasanya, kode global dan kode gabungan akan ditampilkan. Namun, jika hasilnya berada di lokasi terpencil (misalnya, lautan atau gurun), hanya kode global yang dapat ditampilkan.
  • partial_match menunjukkan bahwa geocoder tidak mengembalikan hasil yang benar-benar cocok untuk permintaan asli, 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 jika sebuah permintaan memiliki kecocokan terhadap dua atau beberapa lokasi di daerah yang sama. Misalnya, "Hillpar St, Bristol, UK" akan mengembalikan 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 adalah ID unik yang dapat digunakan dengan Google API lainnya. Misalnya, Anda dapat menggunakan place_id dalam permintaan Places API untuk mendapatkan detail bisnis lokal, seperti nomor telepon, jam buka, ulasan pengguna, dan lainnya. Lihat ringkasan ID tempat.

Jenis alamat dan jenis komponen alamat

Array types[] dalam hasil menunjukkan jenis alamat. Contoh jenis alamat mencakup alamat, negara, atau entitas politik. Ada juga array types[] di address_components[], yang menunjukkan jenis setiap bagian alamat. Contohnya antara lain nomor rumah atau negara. (Berikut adalah daftar lengkap jenisnya.) Alamat mungkin memiliki beberapa tipe. Jenisnya dapat dianggap sebagai 'tag'. Misalnya, banyak kota diberi tag dengan jenis political dan locality.

Jenis-jenis berikut didukung dan ditampilkan oleh geocoder dalam array jenis alamat dan 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 dikembalikan oleh Geocoder.
  • administrative_area_level_1 menunjukkan entitas sipil urutan pertama di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah negara bagian. Tidak semua negara memiliki tingkat administratif ini. Di hampir semua kasus, nama-nama singkat administrative_area_level_1 akan hampir cocok dengan subdivisi ISO 3166-2 dan daftar lainnya yang beredar luas; akan tetapi, hal ini bukan jaminan karena hasil geocoding kami didasarkan pada aneka macam sinyal dan data lokasi.
  • administrative_area_level_2 menunjukkan entitas sipil urutan kedua di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah county. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_3 menunjukkan entitas sipil urutan ketiga di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_4 menunjukkan entitas sipil urutan keempat di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_5 menunjukkan entitas sipil urutan kelima di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_6 menunjukkan entitas sipil urutan keenam di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_7 menunjukkan entitas sipil urutan ketujuh di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • colloquial_area menunjukkan nama alternatif yang biasa digunakan untuk entitas.
  • locality menunjukkan gabungan entitas politik kota besar atau kota kecil.
  • sublocality menunjukkan entitas sipil urutan pertama di bawah lokalitas. Beberapa lokasi dapat menerima salah satu dari jenis tambahan: sublocality_level_1 hingga sublocality_level_5. Setiap tingkat sublokalitas adalah entitas sipil. Angka yang lebih besar menunjukkan area geografis yang lebih kecil.
  • neighborhood menunjukkan daerah sekitar yang telah diberi nama
  • premise menunjukkan lokasi yang telah diberi nama, biasanya bangunan atau sekumpulan bangunan dengan nama umum
  • subpremise menunjukkan entitas urutan pertama di bawah lokasi yang telah diberi nama, biasanya sebuah bangunan dalam sekumpulan bangunan dengan nama umum
  • plus_code menunjukkan referensi lokasi yang dienkode, yang berasal dari lintang dan bujur. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika bangunan tidak diberi nomor atau jalan tidak diberi nama). Lihat https://plus.codes untuk mengetahui detailnya.
  • postal_code menunjukkan kode pos seperti yang biasa digunakan untuk penulisan alamat pos dalam negara tersebut.
  • natural_feature menunjukkan fitur alam terkemuka.
  • airport menunjukkan bandara.
  • park menunjukkan taman yang telah diberi nama.
  • point_of_interest menunjukkan lokasi menarik yang telah diberi nama. Biasanya, "POI" ini adalah entitas lokal terkenal yang tidak mudah dimasukkan dalam kategori lain, seperti "Empire State Building" atau "Eiffel Tower".

Daftar kosong dari jenis menunjukkan tidak ada jenis yang diketahui untuk komponen alamat tertentu, misalnya Lieu-dit di Prancis.

Selain hal di atas, komponen alamat dapat 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 pengelompokan area geografis, seperti locality dan sublocality, 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, dan transit_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 yang ditentukan (dinyatakan sebagai kotak pembatas). Anda melakukannya di dalam URL permintaan dengan menetapkan parameter bounds.

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

Misalnya, geocode untuk "Washington" biasanya menampilkan negara bagian Washington:

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 bagian timur laut Amerika Serikat akan menyebabkan geocode ini 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 region

Dalam permintaan Geocoding, Anda dapat menginstruksikan layanan Geocoding agar menampilkan hasil yang bias ke region tertentu dengan menggunakan parameter region. Parameter ini mengambil argumen ccTLD (domain level teratas kode negara) yang menentukan bias region. Sebagian besar kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Raya Inggris adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Inggris Raya dan Irlandia Utara").

Hasil Geocoding dapat dibiaskan untuk setiap domain tempat aplikasi Google Maps utama diluncurkan secara resmi. Perlu diperhatikan bahwa bias ini hanya memprioritaskan pemilih hasil untuk domain tertentu; jika hasil yang lebih relevan ada di luar domain tersebut, hasil tersebut mungkin akan disertakan.

Misalnya, geocode untuk "Toledo" akan menampilkan hasil ini, karena domain default untuk 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.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 menampilkan kota 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" : "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 ke area tertentu. Anda dapat menentukan batasan menggunakan filter components. Filter terdiri dari daftar pasangan component:value yang dipisahkan dengan pipa (|). Nilai filter mendukung metode koreksi ejaan dan pencocokan sebagian yang sama dengan permintaan Geocoding lainnya. Jika geocoder menemukan kecocokan sebagian untuk filter komponen, respons akan berisi kolom partial_match.

components yang dapat difilter meliputi:

  • postal_code cocok dengan postal_code dan postal_code_prefix.
  • country cocok dengan nama negara atau kode negara ISO 3166-1 dua huruf. API mengikuti standar ISO untuk menentukan negara, dan pemfilteran berfungsi paling baik saat menggunakan kode ISO negara yang sesuai.

components berikut dapat digunakan untuk memengaruhi hasil, tetapi tidak akan diterapkan:

  • route cocok dengan nama panjang atau pendek rute.
  • locality cocok dengan jenis locality dan sublocality.
  • administrative_area cocok dengan semua level administrative_area.

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.
  • Hasil ini konsisten dengan Google Maps, yang terkadang menghasilkan respons ZERO_RESULTS yang tidak terduga. Menggunakan Place Autocomplete dapat memberikan hasil yang lebih baik dalam beberapa kasus penggunaan. Untuk mempelajari lebih lanjut, lihat FAQ ini.
  • Untuk setiap komponen alamat, tentukan dalam parameter address atau dalam filter components, tetapi jangan keduanya. Menentukan nilai yang sama di keduanya dapat menghasilkan ZERO_RESULTS.

Geocode untuk "High St, Hastings" dengan components=country:GB menampilkan hasil di Hastings, Inggris, bukan di Hastings-On-Hudson, AS.

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 menampilkan 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 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"
}

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 jumlah 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"
}