Melakukan geocoding terbalik suatu lokasi

Developer Wilayah Ekonomi Eropa (EEA)

Geocoding terbalik menerjemahkan lokasi peta menjadi alamat yang dapat dibaca manusia. Anda merepresentasikan lokasi peta dengan koordinat lintang dan bujur lokasi.

Saat Anda melakukan geocoding terbalik suatu lokasi, respons akan berisi:

API ini menampilkan berbagai jenis alamat, dari alamat jalan yang paling spesifik hingga entitas politik yang kurang spesifik seperti lingkungan, kota, wilayah, dan negara bagian. Alamat yang paling akurat biasanya merupakan hasil pertama. Jika Anda ingin mencocokkan jenis alamat tertentu, gunakan parameter types.

Permintaan geocoding terbalik

Permintaan reverse geocoding adalah permintaan HTTP GET. Anda dapat menentukan lokasi sebagai string tidak terstruktur:

https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE

Atau sebagai kumpulan koordinat lintang dan bujur terstruktur yang diwakili oleh parameter kueri:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

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

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

Meneruskan string lokasi yang tidak terstruktur

Lokasi yang tidak terstruktur adalah lokasi yang diformat sebagai string koordinat lintang dan bujur yang dipisahkan koma:

https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY

Atau dalam perintah curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"

Meneruskan lokasi terstruktur

Tentukan lokasi terstruktur menggunakan parameter kueri location, dengan jenis LatLng. Objek LatLng memungkinkan Anda menentukan garis lintang dan bujur sebagai parameter kueri terpisah:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Menggunakan OAuth untuk membuat permintaan

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

  • https://www.googleapis.com/auth/maps-platform.geocode — Gunakan dengan semua endpoint Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Hanya gunakan dengan GeocodeLocation untuk geocoding terbalik.

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

Untuk informasi dan contoh selengkapnya, lihat Menggunakan OAuth.

Respons geocoding terbalik

Geocoding balik menampilkan objek GeocodeLocationResponse yang berisi:

  • Array results dari objek GeocodeResult yang merepresentasikan tempat.

    Geocoder terbalik menampilkan lebih dari satu hasil dalam array results. Hasilnya tidak hanya alamat pos, melainkan cara apa saja untuk menamai lokasi secara geografis. Misalnya, saat melakukan geocoding terhadap suatu titik di kota Chicago, titik yang diberi geocode mungkin akan diberi label sebagai alamat jalan, sebagai kota (Chicago), sebagai negara bagian (Illinois), atau sebagai negara (Amerika Serikat). Semua adalah "alamat" untuk geocoder. Geocoder terbalik menampilkan salah satu jenis ini sebagai hasil yang valid.

  • Kolom plusCode, dengan jenis PlusCode, berisi Kode Plus yang paling mendekati garis lintang dan bujur dalam permintaan. Selain itu, setiap elemen array results berisi Plus Code. Jarak antara Plus Code yang didekodekan dan titik permintaan kurang dari 10 meter.

Objek JSON lengkapnya berbentuk:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Parameter wajib

  • lokasi

    Koordinat lintang dan bujur yang menentukan lokasi alamat terdekat yang dapat dibaca manusia.

Parameter opsional

  • languageCode

    Bahasa yang digunakan untuk menampilkan hasil.

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

  • regionCode

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

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

  • perincian

    Satu atau beberapa perincian lokasi, yang ditentukan sebagai parameter kueri terpisah, seperti yang ditentukan oleh Granularity. Jika Anda menentukan beberapa parameter granularity, API akan menampilkan semua alamat yang cocok dengan salah satu perincian.

    Parameter granularity tidak membatasi penelusuran ke perincian lokasi yang ditentukan. Sebaliknya, granularity berfungsi sebagai filter pasca-penelusuran. API mengambil semua hasil untuk location yang ditentukan, lalu menghapus hasil yang tidak cocok dengan perincian lokasi yang ditentukan.

    Jika Anda menentukan types dan granularity, maka API hanya akan menampilkan hasil yang cocok dengan keduanya. Contoh:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • tipe

    Satu atau beberapa jenis alamat, yang ditentukan sebagai parameter kueri terpisah. Jika Anda menentukan beberapa parameter types, API akan menampilkan semua alamat yang cocok dengan salah satu jenis.

    Parameter types tidak membatasi penelusuran ke jenis alamat yang ditentukan. Sebaliknya, types berfungsi sebagai filter pasca-penelusuran. API mengambil semua hasil untuk lokasi yang ditentukan, lalu menghapus hasil yang tidak cocok dengan jenis alamat yang ditentukan.

    Jika Anda menentukan types dan granularity, maka API hanya akan menampilkan hasil yang cocok dengan keduanya. Contoh:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Nilai-nilai berikut didukung:

    Jenis alamat dan jenis komponen alamat

    Array types dalam isi GeocodeResult dalam respons menunjukkan jenis alamat. Contoh jenis alamat mencakup alamat jalan, negara, atau entitas politik. Array types dalam kolom AddressComponents pada isi GeocodeResult menunjukkan jenis setiap bagian alamat. Contohnya antara lain nomor rumah atau negara.

    Alamat mungkin memiliki beberapa tipe. Jenisnya dapat dianggap sebagai 'tag'. Misalnya, banyak kota diberi tag dengan jenis political dan locality.

    Jenis berikut didukung dan ditampilkan dalam array jenis alamat dan jenis komponen alamat:

    Jenis Alamat Deskripsi
    street_address Alamat yang akurat.
    route Rute yang telah diberi nama (seperti "US 101").
    intersection Persimpangan utama, biasanya persimpangan dua jalan utama.
    political Entitas politik. Biasanya, tipe ini menunjukkan poligon dari beberapa pemerintahan sipil.
    country Entitas politik nasional, dan biasanya merupakan jenis urutan tertinggi yang ditampilkan oleh Geocoder.
    administrative_area_level_1 Entitas sipil urutan pertama di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah negara bagian. Tidak semua negara memiliki tingkat administratif ini. Dalam sebagian besar kasus, nama pendek administrative_area_level_1 akan hampir cocok dengan subdivisi ISO 3166-2 dan daftar lainnya yang beredar luas; namun, hal ini bukan jaminan karena hasil geocoding kami didasarkan pada berbagai sinyal dan data lokasi.
    administrative_area_level_2 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 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 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 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 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 Entitas sipil urutan ketujuh di bawah tingkat negara. Jenis ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
    colloquial_area Nama alternatif yang biasa digunakan untuk entitas.
    locality Gabungan entitas politik kota besar dan kota kecil.
    sublocality Entitas sipil urutan pertama di bawah lokalitas. Beberapa lokasi dapat menerima salah satu jenis 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 Lingkungan yang telah diberi nama.
    premise Lokasi yang diberi nama, biasanya berupa bangunan atau sekumpulan bangunan dengan nama umum.
    subpremise Entitas yang dapat dialamatkan di bawah tingkat tempat, seperti apartemen, unit, atau suite.
    plus_code 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 Kode pos seperti yang biasa digunakan untuk penulisan alamat pos dalam negara tersebut.
    natural_feature Fitur alam yang menonjol.
    airport Bandara.
    park Taman yang telah diberi nama.
    point_of_interest 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).