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, responsnya 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/v4/geocode/location/LATITUDE,LONGITUDE

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

https://geocode.googleapis.com/v4/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/v4/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/v4/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/v4/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 metode Geocoding API.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Hanya digunakan dengan GeocodeLocation untuk geocoding terbalik.

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

Untuk informasi dan contoh selengkapnya, lihat Menggunakan OAuth.

Respons geocoding terbalik

Geocoding balik menampilkan objek GeocodeLocationResponse yang berisi:

  • Array results dari objek GeocodeResult yang mewakili tempat.

    Respons Geocoding API mencakup array types di dua tempat utama dalam GeocodeResult:

    1. GeocodeResult.types: Array ini menunjukkan jenis hasil secara keseluruhan. Kemungkinan nilai diambil dari Tabel A dan Tabel B di halaman Jenis Tempat (Baru).
    2. GeocodeResult.addressComponents[].types: Setiap komponen alamat memiliki array types yang menunjukkan jenis bagian alamat tertentu tersebut. Nilai ini diambil dari tabel Jenis alamat dan jenis komponen alamat di halaman Jenis Tempat (Baru).

    Geocoder terbalik menampilkan lebih dari satu hasil dalam array results. Hasilnya tidak hanya alamat pos, tetapi 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 akan 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 didekode dan titik permintaan kurang dari 10 meter.

    Catatan: API tidak selalu menampilkan Plus Codes.

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 yang diperlukan

  • 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 nilai default en. 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 skrip yang dapat dibaca oleh pengguna jika perlu, dengan memperhatikan bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Komponen alamat semuanya 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, geocoding maju, 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/v4/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. Nilai yang mungkin diambil dari tabel Jenis Alamat dan jenis komponen alamat di halaman Jenis Tempat (Baru). 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/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    Buat mask kolom respons untuk menentukan kolom yang akan ditampilkan dalam respons. Teruskan mask kolom respons ke metode menggunakan parameter URL $fields atau fields, atau menggunakan header HTTP X-Goog-FieldMask. Misalnya, permintaan di bawah hanya akan menampilkan kolom placeID dari respons.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    Responsnya adalah: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Lihat Memilih kolom yang akan ditampilkan untuk mengetahui detail selengkapnya.