Menggunakan Region Lookup API

Dengan Region Lookup API, Anda dapat menemukan ID tempat untuk wilayah, yang dapat digunakan untuk menata gaya poligon batas dalam gaya visual berbasis data untuk batas. Region Lookup API mendukung dua jenis permintaan:

  • Pencarian wilayah mencari wilayah berdasarkan nama tempat, Kode FIPS (khusus negara bagian dan county AS), atau Kode negara ISO-3166-1.
  • Penelusuran wilayah menelusuri wilayah yang berisi lokasi tertentu seperti yang ditentukan oleh alamat, LatLng, atau ID tempat.

Jenis tempat wilayah yang didukung

Jenis tempat wilayah berikut didukung: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Menginstal library

Untuk menggunakan Region Lookup API, lakukan langkah-langkah berikut:

  1. Aktifkan Region Lookup API di konsol.
  2. Instal library open source: npm install @googlemaps/region-lookup

Mengimpor dependensi dari library

Library open source Region Lookup menyediakan sekumpulan fungsi dan pengetikan TypeScript yang perlu Anda impor ke dalam kode.

  • Untuk permintaan pencarian wilayah, impor hal berikut:

    import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

  • Untuk permintaan penelusuran wilayah, impor hal berikut:

    import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

Permintaan pencarian wilayah

Permintaan pencarian wilayah akan mengambil nama tempat atau kode ID, dan menampilkan ID tempat. Untuk mencari wilayah, panggil lookupRegion() dengan menentukan LookupRegionRequestData menggunakan parameter berikut:

  • place atau unit_code (wajib) Nama wilayah (place) atau unit_code tempat. unit_code dapat berupa kode FIPS (khusus negara bagian dan county AS), atau kode negara ISO-3166-1.
  • place_type (wajib) Nilai jenis tempat untuk jenis tempat yang akan dicari.
  • region_code Kode negara/wilayah dua huruf ISO-3166 untuk lokasi yang akan dicocokkan. region_code bersifat opsional jika place_type adalah COUNTRY.
  • language Kode bahasa BCP-47, seperti "en-US" atau "sr-Latn". Jika tidak ada yang ditentukan, defaultnya adalah en-US.

Contoh berikut menunjukkan permintaan pencarian untuk Newark, NJ.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

Parameter place atau unit_code wajib ada. Jika tidak ada yang ditentukan, pesan error akan muncul.

Parameter region_code wajib ada kecuali jika place_type adalah COUNTRY.

place dan unit_code menentukan ke lokasi mana sebuah ID tempat akan dicocokkan. Misalnya, jika place adalah "California" dan place_type adalah ADMINISTRATIVE_AREA_LEVEL_1, API akan menampilkan ID tempat untuk California sebagai matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    Hasil matched_place_id: ID tempat untuk California. Semua jenis lain yang didukung tidak akan menampilkan kecocokan.

Jika unit_code adalah "6" (Kode FIPS untuk California), place_type adalah ADMINISTRATIVE_AREA_LEVEL_1, dan region_code adalah "US", API akan menampilkan ID tempat untuk California:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    Hasil matched_place_id: ID tempat untuk California. Semua jenis lain yang didukung tidak akan menampilkan kecocokan.

Jika unit_code adalah "US", API akan menampilkan hasil berikut saat place_type berikut ditentukan:

  • place_type: COUNTRY

    Hasil matched_place_id: ID tempat untuk Amerika Serikat. Semua jenis lain yang didukung tidak akan menampilkan kecocokan.

Jika tidak ditemukan kecocokan, matched_place_id tidak ditetapkan.

ID tempat kandidat ditampilkan jika terjadi ambiguitas. Misalnya, jika place adalah "Santa Clara County" dan place_type adalah LOCALITY, ID tempat untuk Santa Clara County akan ditampilkan sebagai kandidat.

Respons pencarian wilayah

Objek LookupRegionResponse berisi matched_place_id jika hasilnya ditemukan. Jika tidak ada hasil yang ditemukan, ID tempat dengan tingkat keyakinan yang lebih rendah akan ditampilkan sebagai ID kandidat, beserta kode error yang berisi informasi proses debug.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Permintaan penelusuran wilayah

Untuk menemukan wilayah yang berisi lokasi tertentu, panggil searchRegion yang menentukan SearchRegionRequestData dengan parameter berikut:

  • address atau latlng atau place_id (wajib) Berisi string alamat yang tidak terstruktur, latlng, atau ID tempat yang berisi wilayah (misalnya, POI, gedung, dan sebagainya). Jika tidak ada yang ditentukan, pesan error akan muncul.
  • place_type (wajib) Nilai jenis tempat untuk jenis wilayah yang akan ditelusuri.
  • region_code Kode negara/wilayah dua huruf ISO-3166 untuk lokasi yang akan dicocokkan. region_code wajib ada saat address ditentukan.
  • language Kode bahasa BCP-47, seperti "en-US" atau "sr-Latn". Jika tidak ada yang ditentukan, defaultnya adalah en-US.

Contoh berikut menunjukkan permintaan pencarian untuk Burbank, CA.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

Respons penelusuran wilayah

Objek SearchRegionResponse berisi matched_place_id jika hasilnya ditemukan. Jika terjadi kecocokan yang gagal, respons berisi satu atau beberapa ID tempat kandidat dan kode error.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Referensi

ID LookupRegionRequestData

Kolom Jenis Deskripsi
place string Nama wilayah yang akan dicocokkan dengan ID tempat. Gunakan kolom place yang dikombinasikan dengan place_type untuk mencari ID tempat wilayah. Misalnya, jika place_type adalah "locality", place yang valid dapat berupa "Palo Alto, CA". Jika place_type adalah `POSTAL_CODE`, place_name yang valid dapat berupa "94109". Jika place_type adalah `COUNTRY`, place yang valid dapat berupa "United States", dll. region_code wajib ada saat place ditentukan, kecuali jika place_type adalah `COUNTRY`.
unit_code string Kode county atau negara bagian FIP (khusus AS) atau kode negara ISO-3166-1 yang akan dicocokkan. Kolom unit_code digunakan bersama dengan place_type untuk mencari ID tempat wilayah. Misalnya: Jika place_type adalah COUNTRY, unit_code yang valid dapat berupa "US" (kode ISO-3166-1 Alpha-2 untuk Amerika Serikat) atau "BR" (kode ISO-3166-1 Alpha-2 untuk Brasil). Jika place_type adalah ADMINISTRATIVE_AREA_LEVEL_1 (state) dan region_code adalah "US", unit_code yang valid dapat berupa "6" (kode IPF untuk California) atau "12" (kode FIP untuk Florida). Jika place_type adalah ADMINISTRATIVE_AREA_LEVEL_2 (county) dan region_code adalah "US", unit_code yang valid dapat berupa "6001" (kode FIP untuk Alameda County di California) atau "12086" (kode FIP untuk Miami-Dade County di Florida). region_code wajib ada saat menentukan kode FIP. region_code diabaikan untuk kode negara ISO-3166-1.
place_type PlaceType Wajib. Jenis wilayah yang akan dicocokkan.
region_code string Kode negara/wilayah dua huruf ISO-3166 untuk lokasi yang ingin Anda cocokkan. region_code bersifat opsional jika place_type adalah `COUNTRY`.
language_code string Kode bahasa BCP-47, seperti "en-US" atau "sr-Latn", yang sesuai dengan bahasa yang digunakan untuk meminta nama dan alamat tempat. Jika tidak ada yang diminta, maka default-nya adalah bahasa Inggris.

ID SearchRegionRequestData

WAJIB: Salah satu dari address, latlng, atau place_id.

Kolom Jenis Deskripsi
address string Alamat tidak terstruktur yang terdapat di dalam suatu wilayah yang akan dicocokkan. region_code wajib ada saat address ditentukan.
latlng LatLng Lintang dan bujur yang terdapat di dalam suatu wilayah yang akan dicocokkan.
place_id string ID tempat yang terdapat dalam wilayah yang akan dicocokkan.
place_type place type Wajib. Jenis wilayah yang akan dicocokkan.
language_code string Kode bahasa BCP-47, seperti "en-US" atau "sr-Latn", yang sesuai dengan bahasa yang digunakan untuk meminta nama dan alamat tempat. Jika tidak ada yang diminta, maka default-nya adalah bahasa Inggris.
region_code string Kode negara/wilayah ISO-3166 dua huruf untuk lokasi yang akan dicocokkan. region_code wajib ada saat alamat ditentukan.

Jenis tempat

Nilai Deskripsi
POSTAL_CODE Kode pos, seperti yang biasa digunakan untuk penulisan alamat pos dalam negara tersebut.
ADMINISTRATIVE_AREA_LEVEL_1 Entitas sipil urutan pertama di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah negara bagian.
ADMINISTRATIVE_AREA_LEVEL_2 Entitas sipil urutan kedua di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah county.
LOCALITY Gabungan entitas politik kota besar dan kota kecil.
COUNTRY Entitas politik nasional, biasanya jenis urutan tertinggi.

LatLng

Objek yang merepresentasikan pasangan garis lintang/bujur. Objek ini dinyatakan sebagai pasangan double untuk mewakili derajat lintang dan derajat bujur. Kecuali jika ditentukan lain, objek ini harus sesuai dengan standar WGS84. Nilai harus berada dalam rentang yang dinormalisasi.

Kolom Jenis Deskripsi
latitude double Lintang dalam derajat. Nilainya harus dalam rentang [-90.0, +90.0]. Misalnya, 47.47583476464538.
longitude double Bujur dalam derajat. Nilainya harus dalam rentang [-180.0, +180.0]. Misalnya, -121.73858779269906.

Kode error

Nilai Deskripsi
UnknownError Terjadi error tak dikenal.
NoMatchFound Permintaan tidak menghasilkan kecocokan, periksa candidate_place_ids jika tersedia.
AddressNotUnderstood Geocoding gagal untuk alamat yang diberikan.
PlaceTypeMismatch Jenis tempat dalam respons tidak sesuai dengan jenis permintaan. Misalnya, locality yang diminta, tetapi administrative_area_level_2 yang ditampilkan.
MultipleCandidatesFound Beberapa kandidat cocok dengan input. Periksa candidate_place_ids. jika tersedia.
PlaceNameNotUnderstood Nama tempat yang diberikan gagal di-resolve ke suatu wilayah.
UnitCodeNotFound Kode unit tidak ditemukan. Pastikan bahwa kode unit valid dan diberikan dalam format yang benar.
PlaceTypeNotAllowed ID tempat yang cocok tidak ada dalam daftar jenis tempat dan negara yang disetujui.