Region Lookup API'yi kullanın

Bölge arama API'si ile bölgelerin yer kimliklerini bulabilirsiniz. Bu kimlikleri, sınırlar için veriye dayalı stillendirmede sınır poligonlarına stil uygulamak üzere kullanabilirsiniz. Bölge Arama API'si 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ğiyle 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

Bölge arama API'sini kullanmak için aşağıdaki adımları uygulayın:

  1. Konsolda Bölge Arama API'sini etkinleştirin.
  2. Açık kaynak kitaplığını yükleyin: npm install @googlemaps/region-lookup

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

Region Lookup açık kaynak kitaplığı, kodunuza içe aktarmanız gereken bir dizi işlev ve TypeScript yazım biçimi 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() işlevini çağırın ve aşağıdaki parametrelerle bir LookupRegionRequestData belirtin:

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

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 gereklidir. Hiçbiri belirtilmezse hata döndürülür.

place_type COUNTRY olmadığı sürece region_code parametresi gereklidir.

place ve unit_code, bir yer kimliğiyle eşleştirilecek bir konum belirtir. Örneğin, place "California" ve place_type ADMINISTRATIVE_AREA_LEVEL_1 ise API, Kaliforniya için yer kimliğini matched_place_id olarak döndürür:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id sonuçları: Kaliforniya için yer kimliği. Diğer tüm desteklenen türler eşleşme döndürmez.

unit_code "6" (Kaliforniya için FIPS kodu), place_type ADMINISTRATIVE_AREA_LEVEL_1 ve region_code "US" ise API, Kaliforniya için konum kimliğini döndürür:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    matched_place_id sonuçları: Kaliforniya için yer kimliği. Diğer tüm desteklenen türler eşleşme döndürmez.

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

  • place_type: COUNTRY

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

Eşleşme bulunmazsa matched_place_id ayarlanmaz.

Belirsizlik olması durumunda olası yer kimlikleri döndürülür. Örneğin, place "Santa Clara County" ve place_type LOCALITY ise Santa Clara County için 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. Hiçbir sonuç bulunamazsa daha düşük güven düzeyine sahip yer kimlikleri, hata ayıklama bilgilerini içeren bir hata kodu ile 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 işlevini çağırın:

  • address veya latlng veya place_id (zorunlu) Bölgenin içerdiği yapılandırılmamış bir adres dizesini, latlng veya yer kimliğini (ör. ÖY, bina vb.) içerir. Hiçbiri belirtilmezse hata döndürülür.
  • place_type (zorunlu) Aranacak bölge türü için yer türü değeri.
  • region_code Eşleşmesi gereken 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 olarak en-US kullanılır.

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ıtta bir veya daha fazla olası yer kimliği ve bir hata kodu bulunur.

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

Referans

LookupRegionRequestData tanımlayıcıları

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 "yerleşim" ise geçerli bir place değeri "Palo Alto, CA" olabilir. place_type, "POSTAL_CODE" ise geçerli bir yer_adı "94109" olabilir. place_type, "COUNTRY" ise geçerli bir place değeri "United States" vb. olabilir. place_type, "COUNTRY" olmadığı sürece place belirtildiğinde region_code gereklidir.
unit_code dize Eşleştirilecek FIP 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 değeri "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) ise ve region_code "US" ise geçerli bir unit_code "6" (California için FIPs kodu) veya "12"(Florida için FIPs kodu) olabilir. place_type ADMINISTRATIVE_AREA_LEVEL_2 (county) ve region_code "US" ise geçerli bir unit_code "6001" (Kaliforniya'daki Alameda County için FIPS kodu) veya "12086" (Florida'daki Miami-Dade County için FIPS kodu) olabilir. FIPs kodu belirtilirken region_code gereklidir. region_code, ISO-3166-1 ülke kodları için yoksayılır.
place_type PlaceType Zorunlu. Eşlenecek bölgenin 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 ("en-US" veya "sr-Latn" gibi). Hiçbir dil istek

SearchRegionRequestData tanımlayıcıları

ZORUNLU: address, latlng veya place_id'den biri.

Alan Tür Açıklama
address dize Eşleşmek için bir bölgenin içinde bulunan yapılandırılmamış bir açık adres. address belirtildiğinde region_code gereklidir.
latlng LatLng Eşleşecek bir bölgenin içinde bulunan enlem ve boylam.
place_id dize Eşleştirilecek bir bölgenin içinde bulunan yer kimliği.
place_type place type Zorunlu. Eşlenecek bölgenin türü.
language_code dize Yer adının ve adresinin istendiği dile karşılık gelen BCP-47 dil kodu ("en-US" veya "sr-Latn" gibi). Hiçbir dil istek gönderilmezse varsayılan dil İngilizce olur.
region_code dize Eşleşmesi gereken konum için 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 sivil tüzel kişi. Amerika Birleşik Devletleri'nde bu idari düzeyler eyaletlerdir.
ADMINISTRATIVE_AREA_LEVEL_2 Ülke düzeyinin altındaki ikinci düzey sivil tüzel kişi. Amerika Birleşik Devletleri'nde bu idari düzeyler illerdir.
LOCALITY Tüzel kişiliğe sahip bir şehir veya kasaba.
COUNTRY Ulusal siyasi varlık, genellikle en yüksek düzey türüdür.

LatLng

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

Alan Tür Açıklama
latitude double Derece cinsinden enlem. [-90.0, +90.0] aralığında olmalıdır. Örneğin 47.47583476464538.
longitude double 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 eşleşmeyle sonuçlanmadı. Varsa candidate_place_ids simgesini 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 istenmiş ancak administrative_area_level_2 döndürülmüştür.
MultipleCandidatesFound Girişle birden fazla aday eşleştirildi. candidate_place_ids'ü kontrol edin. varsa
PlaceNameNotUnderstood Sağlanan yer adı bir bölgeye çözümlenemedi.
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.