Region Lookup API'yi kullanma

Region Lookup API ile bölgelerin yer kimliklerini bulabilirsiniz. Bu kimlikleri, sınırlar için veri odaklı stilde sınır poligonlarını stillendirmek amacıyla kullanabilirsiniz. Region Lookup API iki tür isteği destekler:

  • Bölge arama, bir bölgeyi yer adına, FIPS koduna (yalnızca ABD eyaletleri ve ilçeleri) veya ISO-3166-1 ülke koduna göre arar.
  • Bölge araması, adres, LatLng veya yer kimliği ile belirtilen belirli bir konumu içeren bölgeyi arar.

Desteklenen bölge yer türleri

Aşağıdaki bölge yer türleri desteklenir: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Kitaplığı yükleme

Region Lookup API'yi kullanmak için aşağıdaki adımları uygulayın:

  1. Konsolda Region Lookup API'yi etkinleştirin.
  2. Açık kaynak kitaplığını yükleyin: npm install @googlemaps/region-lookup

Kitaplıktan bağımlılıkları içe aktarma

Region Lookup açık kaynak kitaplığı, kodunuza aktarmanız gereken bir dizi işlev ve TypeScript yazımı sağlar.

  • Bölge arama istekleri için aşağıdakileri içe aktarın:

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

  • Bölge arama istekleri için aşağıdakileri içe aktarın:

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

Bölge arama istekleri

Bölge arama isteği, bir yer adı veya tanımlayıcı kodu alır ve bir yer kimliği döndürür. Bir bölgeyi aramak için lookupRegion() yöntemini çağırın ve aşağıdaki parametreleri içeren bir LookupRegionRequestData belirtin:

  • place veya unit_code (zorunlu) Bölge adı (place) veya yerin unit_code. unit_code, FIPS kodu (yalnızca ABD eyaletleri ve ilçeleri) veya ISO-3166-1 ülke kodu olabilir.
  • place_type (gerekli) Aranacak yer türünün yer türü değeri.
  • region_code Eşleştirilecek konumun iki harfli ISO-3166 ülke/bölge kodu. region_code, place_type COUNTRY ise isteğe bağlıdır.
  • language "en-US" veya "sr-Latn" gibi BCP-47 dil kodu. Hiçbiri belirtilmezse varsayılan değer en-US olur.

Aşağıdaki örnekte Newark, NJ için bir arama isteği gösterilmektedir.

// 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 });

place veya unit_code parametresi zorunludur. Hiçbiri belirtilmezse hata döndürülür.

place_type, COUNTRY olmadığı sürece region_code parametresi zorunludur.

place ve unit_code, bir yer kimliğinin eşleştirileceği konumu belirtir. Örneğin, place "California" ve place_type ADMINISTRATIVE_AREA_LEVEL_1 ise API, California'nın yer kimliğini matched_place_id olarak döndürür:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id sonuç: Kaliforniya'nın yer kimliği. Desteklenen diğer tüm türler eşleşme döndürmez.

unit_code "6" (Kaliforniya'nın FIPS kodu), place_type ADMINISTRATIVE_AREA_LEVEL_1 ve region_code "US" ise API, Kaliforniya'nın yer kimliğini döndürür:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    matched_place_id sonuç: Kaliforniya'nın yer kimliği. Desteklenen diğer tüm türler eşleşme döndürmez.

unit_code "US" ise API, aşağıdaki place_type belirtildiğinde şu sonuçları döndürür:

  • place_type: COUNTRY

    matched_place_id sonuç: Amerika Birleşik Devletleri için yer kimliği. Desteklenen diğer tüm türler eşleşme döndürmez.

Eşleşme bulunamazsa matched_place_id ayarlanmaz.

Belirsizlik durumunda aday yer kimlikleri döndürülür. Örneğin, place "Santa Clara County" ve place_type LOCALITY ise Santa Clara County'nin yer kimliği aday olarak döndürülür.

Bölge arama yanıtı

Bir sonuç bulunursa LookupRegionResponse nesnesi bir matched_place_id içerir. Sonuç bulunamazsa daha düşük güven düzeyine sahip yer kimlikleri, hata ayıklama bilgilerini içeren bir hata koduyla birlikte aday kimlikler olarak döndürülür.

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

Bölge arama istekleri

Belirli bir konumu içeren bir bölgeyi bulmak için aşağıdaki parametrelerle bir SearchRegionRequestData belirterek searchRegion yöntemini çağırın:

  • address veya latlng ya da place_id (gerekli) Yapılandırılmamış bir adres dizesi, bölgede bulunan latlng veya yer kimliği (ör. ÖY, bina vb.) içerir. Hiçbiri belirtilmezse hata döndürülür.
  • place_type (gerekli) Aranacak bölge türünün yer türü değeri.
  • region_code Eşleştirilecek konumun iki harfli ISO-3166 ülke/bölge kodu. address belirtildiğinde region_code gereklidir.
  • language "en-US" veya "sr-Latn" gibi BCP-47 dil kodu. Hiçbiri belirtilmezse varsayılan değer en-US olur.

Aşağıdaki örnekte Burbank, CA için bir arama isteği gösterilmektedir.

// 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 });

Bölge arama yanıtı

Bir sonuç bulunursa SearchRegionResponse nesnesi bir matched_place_id içerir. Eşleşme başarısız olursa yanıt, bir veya daha fazla aday yer kimliği ve bir hata kodu içerir.

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

Referans

LookupRegionRequestData tanımlayıcı

Alan Tür Açıklama
place dize Bir yer kimliğiyle eşleştirilecek bölgenin adı. Bölge yer kimliğini aramak için place alanını place_type ile birlikte kullanın. Örneğin, place_type "locality" ise geçerli bir place "Palo Alto, CA" olabilir. place_type, `POSTAL_CODE` ise geçerli bir place_name "94109" olabilir. place_type değeri `COUNTRY` ise geçerli bir place "Türkiye" vb. olabilir. place_type değeri `COUNTRY` olmadığı sürece place belirtildiğinde region_code gereklidir.
unit_code dize Eşleştirilecek FIPS eyalet veya ilçe kodları (yalnızca ABD) ya da ISO-3166-1 ülke kodu. unit_code alanı, bölge yer kimliğini aramak için place_type ile birlikte kullanılır. Örneğin: place_type, COUNTRY ise geçerli bir unit_code "US" (ABD için ISO-3166-1 Alpha-2 kodu) veya "BR" (Brezilya için ISO-3166-1 Alpha-2 kodu) olabilir. place_type, ADMINISTRATIVE_AREA_LEVEL_1 (eyalet) ve region_code "US" ise geçerli bir unit_code "6" (Kaliforniya için FIPs kodu) veya "12"(Florida için FIPs kodu) olabilir. place_type ADMINISTRATIVE_AREA_LEVEL_2 (ilçe) ve region_code "US" ise geçerli bir unit_code "6001" (California'daki Alameda ilçesinin FIPs kodu) veya "12086" (Florida'daki Miami-Dade ilçesinin FIPs kodu) olabilir. FIPS kodu belirtilirken region_code gereklidir. ISO-3166-1 ülke kodları için region_code yok sayılır.
place_type PlaceType Zorunlu. Eşleştirilecek bölge türü.
region_code dize Eşleştirmeye çalıştığınız konumun iki harfli ISO-3166 ülke/bölge kodu. place_type, `COUNTRY` ise region_code isteğe bağlıdır.
language_code dize Yer adının ve adresinin istendiği dile karşılık gelen BCP-47 dil kodu (ör. "en-US" veya "sr-Latn"). Herhangi bir dil istenmezse varsayılan olarak İngilizce kullanılır.

SearchRegionRequestData tanımlayıcı

ZORUNLU: address, latlng veya place_id değerlerinden biri.

Alan Tür Açıklama
address dize Eşleştirilecek bölge içinde yer alan yapılandırılmamış bir açık adres. address belirtildiğinde region_code gereklidir.
latlng LatLng Eşleştirilecek bölgede bulunan enlem ve boylam.
place_id dize Eşleştirilecek bölgenin içinde yer alan bir yer kimliği.
place_type yer türü Zorunlu. Eşleştirilecek bölge türü.
language_code dize Yer adının ve adresinin istendiği dile karşılık gelen "en-US" veya "sr-Latn" gibi BCP-47 dil kodu. Herhangi bir dil istenmezse varsayılan olarak İngilizce kullanılır.
region_code dize Eşleştirilecek konumun iki harfli ISO-3166 ülke/bölge kodu. Adres belirtildiğinde region_code gereklidir.

Yer türleri

Değer Açıklama
POSTAL_CODE Ülke içinde posta göndermek için kullanılan posta kodu.
ADMINISTRATIVE_AREA_LEVEL_1 Ülke düzeyinin altındaki birinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir.
ADMINISTRATIVE_AREA_LEVEL_2 Ülke düzeyinin altındaki ikinci dereceden idari bölge. Amerika Birleşik Devletleri'nde bu idari düzeyler ilçelerdir.
LOCALITY Anonim bir şehir veya kasaba siyasi kuruluşu.
COUNTRY Ulusal siyasi tüzel kişi, genellikle en yüksek düzeydeki türdür.

LatLng

Enlem/boylam çiftini temsil eden bir nesne. Bu, enlem ve boylam derecelerini temsil eden bir çift double değeri olarak ifade edilir. Aksi belirtilmedikçe bu nesne WGS84 standardına uygun olmalıdır. Değerler normalleştirilmiş aralıklarda olmalıdır.

Alan Tür Açıklama
latitude çift Derece cinsinden enlem. [-90.0, +90.0] aralığında olmalıdır. Örneğin, 47.47583476464538.
longitude çift Derece cinsinden boylam. [-180.0, +180.0] aralığında olmalıdır. Örneğin, -121.73858779269906.

Hata kodları

Değer Açıklama
UnknownError Bilinmeyen bir hata oluştu.
NoMatchFound İstek sonucunda eşleşme bulunamadı. Varsa candidate_place_ids adresini kontrol edin.
AddressNotUnderstood Sağlanan adres için coğrafi kodlama başarısız oldu.
PlaceTypeMismatch Yanıttaki yer türü, istekteki yer türüyle eşleşmiyor. Örneğin, locality istendi ancak administrative_area_level_2 döndürüldü.
MultipleCandidatesFound Girişle eşleşen birden fazla aday var. candidate_place_ids kontrol edin. (varsa).
PlaceNameNotUnderstood Sağlanan yer adı bir bölgeyle eşleştirilemedi.
UnitCodeNotFound Birim kodu bulunamadı. Birim kodunun geçerli olduğundan ve doğru biçimde sağlandığından emin olun.
PlaceTypeNotAllowed Eşleşen yer kimliği, yer türü ve ülke izin verilenler listesinde değil.