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:
- Konsolda Region Lookup API'yi etkinleştirin.
- 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
veyaunit_code
(zorunlu) Yerin bölge adı (place
) veyaunit_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_typeCOUNTRY
iseregion_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
veyalatlng
ya daplace_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ğinderegion_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. |