Region Lookup API'yi kullanın

Region Lookup API ile bölgelere ait yer kimliklerini bulabilir ve veriye dayalı stilde sınır poligonlarının stilini belirleyebilirsiniz. Bölge Arama API'si iki tür isteği destekler:

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

Desteklenen bölge yer türleri

Şu bölgedeki 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 şu adımları uygulayın:

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

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

Bölge Araması açık kaynak kitaplığı, kodunuza aktarmanız gereken bir dizi işlev ve TypeScript yazması 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 yer kimliği döndürür. Bölge aramak için aşağıdaki parametrelerle bir LookupRegionRequestData belirterek lookupRegion() yöntemini çağırın:

  • place veya unit_code (zorunlu) Yerin bölge adı (place) veya unit_code. unit_code bir 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 place type değeri.
  • region_code Eşleşecek konum için 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. Herhangi bir değer 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. Herhangi bir değer belirtilmezse hata döndürülür.

place_type COUNTRY değilse region_code parametresi gereklidir.

place ve unit_code, bir yer kimliğinin eşleştirileceği konumu belirtir. Örneğin place değeri "Kaliforniya" ve place_type değeri 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ç: Kaliforniya için yer kimliği. Desteklenen diğer türler eşleşme döndürmez.

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

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1
  • region_code: US

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

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

  • place_type: COUNTRY

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

Eşleşme bulunmazsa matched_place_id ayarlanmamıştır.

Aday yer kimlikleri belirsizlik durumunda döndürülür. Örneğin, place değeri "Santa Clara İlçesi" ve place_type değeri LOCALITY ise Santa Clara İlçesinin yer kimliği aday olarak döndürülür.

Bölge arama yanıtı

Sonuç bulunursa LookupRegionResponse nesnesi bir matched_place_id içerir. Hiçbir sonuç bulunmazsa güvenirliği düşük 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 searchRegion yöntemini kullanarak aşağıdaki parametrelerle bir SearchRegionRequestData belirtin:

  • address veya latlng ya da place_id (zorunlu) Bölge (örneğin ÖY, bina vb.) içeren yapılandırılmamış adres dizesi, latlng veya yer kimliği içerir. Herhangi bir değer belirtilmezse hata döndürülür.
  • place_type (zorunlu) Aranacak bölge türü için place type değeri.
  • region_code Eşleşecek konum için 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. Herhangi bir değer 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ı

Sonuç bulunursa SearchRegionResponse nesnesi bir matched_place_id içerir. Başarısız eşleşme olması durumunda yanıt, bir veya daha fazla aday yer kimliği ve 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" olursa geçerli bir place değeri "Palo Alto, CA" olabilir. place_type değeri "POSTAL_CODE" ise geçerli yer_adı "94109" olabilir. place_type değeri "COUNTRY" ise geçerli place değeri "United States" vb. olabilir. place_type değeri "COUNTRY" değilse place belirtildiğinde region_code gereklidir.
unit_code dize Eşleştirilecek FIP eyalet veya bölge kodları (yalnızca ABD) ya da ISO-3166-1 ülke kodu. unit_code alanı, bölgenin yer kimliğini aramak için place_type ile birlikte kullanılır. Örneğin: place_type değeri COUNTRY ise geçerli bir birim_kodu "US" (ABD için ISO-3166-1 Alpha-2 kodu) veya "BR" (Brezilya için ISO-3166-1 Alfa-2 kodu) olabilir. place_type değeri ADMINISTRATIVE_AREA_LEVEL_1 (eyalet) ve bölge_kodu değeri "US" ise geçerli bir birim_kodu "6" (Kaliforniya için FIP kodu) veya "12"(Florida için FIP kodu) olabilir. Yer_türü ADMINISTRATIVE_AREA_LEVEL_2 (il) ve bölge_kodu değeri "US" ise geçerli birim_kodu "6001" (Kaliforniya'daki Alameda İlçesi için FIP kodu) veya "12086" (Florida'daki Miami-Dade İlçesi için FIP kodu) olabilir. FIPs kodu belirtirken region_code gereklidir. region_code, ISO-3166-1 ülke kodları için yoksayılır.
place_type PlaceType Zorunlu. Eşleştirilecek 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 değeri "COUNTRY" ise bölge_kodu isteğe bağlıdır.
language_code dize Yer adı ve adresinin istendiği dile karşılık gelen "en-US" veya "sr-Latn" gibi BCP-47 dil kodu. Hiçbiri istenmezse varsayılan olarak İngilizce olur.

SearchRegionRequestData tanımlayıcı

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

Alan Tür Açıklama
address dize Eşleştirilecek bir bölgenin içinde yer alan yapılandırılmamış bir sokak adresi. address belirtildiğinde region_code gereklidir.
latlng LatLng Eşleştirilecek bir bölgenin içinde yer alan enlem ve boylam.
place_id dize Eşleştirilecek bir bölgenin içinde yer alan yer kimliği.
place_type yer türü Zorunlu. Eşleştirilecek bölgenin türü.
language_code dize Yer adı ve adresinin istendiği dile karşılık gelen BCP-47 dil kodu (ör. "en-US" veya "sr-Latn"). Hiçbir dil istenmezse varsayılan olarak İngilizce olur.
region_code dize Eşleşen 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çindeki posta postalarının gönderilmesi için kullanılan posta kodu.
ADMINISTRATIVE_AREA_LEVEL_1 Ülke düzeyinin altındaki birinci dereceden sivil tüzel kişi. ABD'de bu idari düzeyler eyaletlerdir.
ADMINISTRATIVE_AREA_LEVEL_2 Ülke düzeyinin altındaki ikinci derece sivil tüzel kişi. ABD'de bu idari düzeyler ilçelerdir.
LOCALITY anonim bir şehir veya kasaba siyasi tüzel kişiliği
COUNTRY Ulusal siyasi varlık, genellikle en üst düzey tüzel kişidir.

LatLng

Enlem/boylam çiftini temsil eden bir nesne. Enlem ve boylam derecelerini temsil eden çiftler çifti 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 kontrol edin.
AddressNotUnderstood Sağlanan adres için coğrafi kodlama başarısız oldu.
PlaceTypeMismatch Yanıttaki yer türü, isteğinle eşleşmiyor. Örneğin, locality istendi ancak administrative_area_level_2 döndürüldü.
MultipleCandidatesFound Girişle birden fazla öneri eşleştirildi. candidate_place_ids'a göz atın. (varsa)
PlaceNameNotUnderstood Girilen yer adı, 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.