Region Lookup API'yi kullanma

Bölge Arama API'si ile bölgelerin yer kimliklerini bulabilir ve bunları, sınırlara yönelik veriye dayalı stil oluşturmada sınır poligonlarını stilize etmek için kullanabilirsiniz. Bölge Arama API'si iki tür isteği destekler:

  • Bölge arama, 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ı, bir 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 Bölge Arama API'sini 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 tür tanımları 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 aşağıdaki parametrelerle LookupRegionRequestData belirterek lookupRegion() işlevini çağırın:

  • place veya unit_code (zorunlu) Bölge adı (place) veya unit_code yeri. unit_code, FIPS kodu (yalnızca ABD eyaletleri ve ilçeleri) veya ISO-3166-1 ülke kodu olabilir.
  • place_type (zorunlu) Aranacak yer türü için yer türü değeri.
  • region_code Eşleştirilecek konumun iki harfli ISO-3166 ülke/bölge kodu. place_type COUNTRY ise region_code isteğe bağlıdır.
  • language BCP-47 dil kodu (ör. "en-US" veya "sr-Latn"). 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.

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

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

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id sonuçları: Kaliforniya'nın yer kimliği. Diğer tüm desteklenen 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çları: Kaliforniya'nın 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'nin yer kimliği. Diğer tüm desteklenen türler eşleşme döndürmez.

Eşleşme bulunmazsa matched_place_id ayarlanmaz.

Açıklık olmaması durumunda aday yer kimlikleri döndürülür. Örneğin, place "Santa Clara County" ise 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 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 kodu ile birlikte aday kimlikleri 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 searchRegion işlevini çağırın. Bu işlevde aşağıdaki parametrelerle SearchRegionRequestData belirtilir:

  • address veya latlng veya place_id (zorunlu) Yapılandırılmamış bir adres dizesi, latlng ya da bölge tarafından kapsanan yer kimliği (ör. önemli yer, 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ştirilecek konumun iki harfli ISO-3166 ülke/bölge kodu. address belirtildiğinde region_code gereklidir.
  • language BCP-47 dil kodu (ör. "en-US" veya "sr-Latn"). 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 matched_place_id içerir. Eşleşme başarısız olduğunda yanıtta bir veya daha fazla aday 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 "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 değeri "United States" 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'nin ISO-3166-1 Alfa-2 kodu) veya "BR" (Brezilya'nın ISO-3166-1 Alfa-2 kodu) olabilir. place_type ADMINISTRATIVE_AREA_LEVEL_1 (eyalet) ise ve region_code "US" ise geçerli bir unit_code "6" (Kaliforniya'nın FIP'leri kodu) veya "12"(Florida'nın FIP'leri kodu) olabilir. place_type ADMINISTRATIVE_AREA_LEVEL_2 (ilçe) ve region_code "US" ise geçerli bir unit_code "6001" (Kaliforniya'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 yoksayılır. kodları için region_code yoksayılır.
place_type PlaceType Zorunlu. Eşleştirilecek bölge türü.
region_code dize Eşleştirmeye çalıştığınız konum için 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"). Hiçbiri istenmezse varsayılan olarak İngilizce kullanılır.

SearchRegionRequestData tanımlayıcılar

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

Alan Tür Açıklama
address dize Eşleştirilecek bir bölge 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ölge içinde yer alan yer kimliği.
place_type place type Zorunlu. Eşleştirilecek bölge tü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"). Hiçbiri 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 Tüzel kişiliğe sahip bir şehir veya kasaba siyasi tüzel kişiliği.
COUNTRY Genellikle en üst düzey tür olan ulusal siyasi varlık.

LatLng

Bir enlem/boylam çiftini temsil eden nesne. Bu değer, enlem derecelerini ve boylam derecelerini temsil eden bir çift çift sayı olarak ifade edilir. Aksi belirtilmediği sürece 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 Enlem (derece cinsinden). [-90.0, +90.0] aralığında olmalıdır. Örneğin 47.47583476464538.
longitude double Boylam (derece cinsinden). [-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şme sağlamadı. candidate_place_ids varsa kontrol edin.
AddressNotUnderstood Belirtilen adres için coğrafi kodlama başarısız oldu.
PlaceTypeMismatch Yanıttaki yer türü, isteğin türüyle eşleşmiyor. Örneğin, locality istenmiş ancak administrative_area_level_2 döndürülmüştür.
MultipleCandidatesFound Girişle eşleşen birden fazla aday oldu. 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ğunu ve doğru biçimde sağlandığını doğrulayın.
PlaceTypeNotAllowed Eşleşen yer kimliği, yer türü ve ülke izin verilenler listesinde değil.