Menggunakan Region Lookup API

Produk atau fitur ini bersifat Eksperimental (pra-GA). Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Penawaran Pra-GA tercakup dalam Persyaratan Khusus Layanan Google Maps Platform. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dengan Region Lookup API, Anda dapat menemukan ID tempat untuk wilayah, yang dapat digunakan untuk menata gaya poligon batas dalam Gaya visual berbasis data. 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 Google.
• 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 typing 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";
  

Perhatian: Region Lookup API dan library open source untuk JavaScript merupakan Rilis Eksperimental.

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, error akan dikembalikan.

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 mengembalikan 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 mengembalikan 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 mengembalikan kecocokan.

Jika tidak ditemukan kecocokan, matched_place_id tidak ditetapkan.

ID tempat kandidat dikembalikan 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 dikembalikan 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, error akan dikembalikan.
• 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 dikembalikan.
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.