Interfejs Region Lookup API pozwala znajdować identyfikatory miejsc dla regionów, których możesz używać do określania stylu wielokątów granic w stylu opartym na danych. Interfejs Region Lookup API obsługuje 2 rodzaje żądań:
- Wyszukiwanie regionu wyszukuje region według nazwy miejsca, kodu FIPS (tylko stany i hrabstwa w USA) lub kod kraju w standardzie ISO-3166-1.
- Wyszukiwanie według fragmentu wyszukuje region, który zawiera konkretną lokalizację określoną za pomocą adresu,
LatLng
lub identyfikatora miejsca.
Obsługiwane typy miejsc w regionie
Obsługiwane są te typy miejsc w regionie: country
, administrative_area_level_1
, administrative_area_level_2
, postal_code
, locality
.
Zainstaluj bibliotekę
Aby użyć interfejsu Region Lookup API, wykonaj te czynności:
- Włącz w konsoli interfejs Region Lookup API.
- Zainstaluj bibliotekę open source:
npm install @googlemaps/region-lookup
Importuj zależności z biblioteki
Biblioteka open source Lookup regionu udostępnia zestaw funkcji i tekstów TypeScriptu, które należy zaimportować do swojego kodu.
W przypadku żądań wyszukiwania według fragmentu zaimportuj te dane:
import { lookupRegion, LookupRegionRequestData, LookupRegionResponseData, LookupRegionResponse, RegionIdentifier } from "@googlemaps/region-lookup";
W przypadku żądań wyszukiwania według fragmentu zaimportuj następujące dane:
import { searchRegion, RegionSearchValue, SearchRegionRequestData, SearchRegionResponse } from "@googlemaps/region-lookup";
Żądania wyszukiwania regionu
Żądanie wyszukiwania według regionu zawiera nazwę lub kod identyfikatora miejsca i zwraca jego identyfikator. Aby wyszukać region, wywołaj lookupRegion()
, określając LookupRegionRequestData
z tymi parametrami:
place
lubunit_code
(wymagane) Nazwa regionu (place
) lubunit_code
miejsca.unit_code
może być kodem FIPS (tylko stany i hrabstwa w USA) lub kodem kraju ISO-3166-1.place_type
(wymagany) Wartość typ miejsca określająca typ szukanego miejsca.region_code
2-literowy kod kraju lub regionu w standardzie ISO-3166 odpowiadający lokalizacji, która ma być dopasowywana. Poleregion_code
jest opcjonalne, jeśli typ_miejsca ma wartośćCOUNTRY
.language
Kod języka BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie podasz żadnej wartości, domyślną wartością będzie en-US.
Poniższy przykład przedstawia żądanie wyszukiwania w Newark w stanie NJ.
// 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 });
Wymagany jest parametr place
lub unit_code
. Jeśli nie podasz żadnej wartości,
zwrócony zostanie błąd.
Parametr region_code
jest wymagany, chyba że place_type
ma wartość COUNTRY
.
Parametry place
i unit_code
określają lokalizację, do której ma pasować identyfikator miejsca. Jeśli np. place
to „Kalifornia”, a place_type
to ADMINISTRATIVE_AREA_LEVEL_1
, interfejs API zwraca identyfikator miejsca Kalifornii jako matched_place_id
:
place_type
:ADMINISTRATIVE_AREA_LEVEL_1
Wyniki (
matched_place_id
): identyfikator miejsca dla województwa mazowieckiego. Pozostałe obsługiwane typy nie zwracają dopasowania.
Jeśli unit_code
to „6” (kod FIPS dla Kalifornii), place_type
ma wartość ADMINISTRATIVE_AREA_LEVEL_1
, a region_code
to „US”, interfejs API zwraca identyfikator miejsca Kalifornii:
place_type
:ADMINISTRATIVE_AREA_LEVEL_1
region_code
:US
Wyniki (
matched_place_id
): identyfikator miejsca dla województwa mazowieckiego. Pozostałe obsługiwane typy nie zwracają dopasowania.
Jeśli unit_code
to „US”, interfejs API zwraca te wyniki, gdy określone są te place_type
:
place_type
:COUNTRY
Wyniki (
matched_place_id
): identyfikator miejsca dla Stanów Zjednoczonych. Pozostałe obsługiwane typy nie zwracają dopasowania.
Jeśli nie znaleziono dopasowania, zasada matched_place_id
nie jest ustawiona.
W przypadku niejasności zwracane są identyfikatory miejsc kandydujących. Jeśli np. place
to „Hrabstwo Santa Clara”, a place_type
to LOCALITY
, jako kandydata zwracany jest identyfikator miejsca z hrabstwa Santa Clara.
Odpowiedź na wyszukiwanie regionu
Jeśli znaleziono wynik, obiekt LookupRegionResponse
zawiera obiekt matched_place_id
. Jeśli nie uda się znaleźć wyniku, jako identyfikatory kandydatów zostaną zwrócone identyfikatory miejsc o niższym poziomie ufności wraz z kodem błędu zawierającym informacje na potrzeby debugowania.
{ "matches": [ { "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs" } ] }
Żądania wyszukiwania według regionu
Aby znaleźć region, który zawiera określoną lokalizację, wywołaj searchRegion
, podając wartość SearchRegionRequestData
z tymi parametrami:
address
,latlng
lubplace_id
(wymagany) zawiera nieuporządkowany ciąg adresu,latlng
lub identyfikator miejsca, który jest częścią regionu (np. ważne miejsce, budynek itp.). Jeśli nie podasz żadnej wartości, zostanie zwrócony błąd.place_type
(wymagany) – wartość typ miejsca określająca typ regionu do wyszukania.region_code
2-literowy kod kraju lub regionu w standardzie ISO-3166 odpowiadający lokalizacji, która ma być dopasowywana. Jeśli określonoaddress
, wymagana jest właściwośćregion_code
.language
Kod języka BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie podasz żadnej wartości, domyślną wartością będzie en-US.
Poniższy przykład przedstawia żądanie wyszukiwania dla Burbank, CA.
// 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 });
Odpowiedź dotycząca wyszukiwania według fragmentu
Jeśli znaleziono wynik, obiekt SearchRegionResponse
zawiera obiekt matched_place_id
. W przypadku niepowodzenia odpowiedź odpowiedź zawiera co najmniej jeden kandydujący identyfikator miejsca oraz kod błędu.
{ "matches": [ { "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs" } ] }
Dokumentacja
LookupRegionRequestData
identyfikatory
Pole | Typ | Opis |
---|---|---|
place |
string, | Nazwa regionu do dopasowania do identyfikatora miejsca. Aby wyszukać identyfikator miejsca w regionie, użyj pola place w połączeniu z place_type . Jeśli na przykład place_type to „locality”, prawidłową wartością place może być „Palo Alto, CA”. Jeśli place_type to „POSTAL_CODE”, prawidłową nazwą miejsca może być „94109”. Jeśli place_type to „COUNTRY”, prawidłową wartością place może być „Stany Zjednoczone” itp. Jeśli określono place , należy podać wartość region_code , chyba że place_type ma wartość „COUNTRY”. |
unit_code |
string, | Kody stanu lub hrabstwa (tylko w USA) albo kod kraju w formacie ISO-3166-1, który należy dopasować. Pole unit_code jest używane w połączeniu z polem place_type do wyszukiwania identyfikatora miejsca w regionie. Jeśli na przykład place_type to COUNTRY , poprawnym kodem jednostki może być „US” (kod ISO-3166-1 alfa-2 dla Stanów Zjednoczonych) lub „BR” (kod ISO-3166-1 alfa-2 dla Brazylii). Jeśli place_type to ADMINISTRATIVE_AREA_LEVEL_1 (stan), a region_code (kod regionu) to „US”, poprawnym kodem jednostki może być „6” (kod FIP dla Kalifornii) lub „12” (kod FIP dla stanu Floryda). Jeśli typ miejsca to ADMINISTRATIVE_AREA_LEVEL_2 (hrabstwo), a kod regionu to „US”, poprawnym kodem jednostki może być „6001” (kod FIP dla hrabstwa Alameda w Kalifornii) lub „12086” (kod FIP dla hrabstwa Miami-Dade na Florydzie). Do określania kodu FIP wymagana jest właściwość region_code . region_code jest ignorowana w przypadku kodów krajów ISO-3166-1. |
place_type |
PlaceType | To pole jest wymagane. Typ regionu do dopasowania. |
region_code |
string, | Dwuliterowy kod kraju lub regionu w standardzie ISO-3166 odpowiadający lokalizacji, którą chcesz dopasować. Region_code (kod regionu) jest opcjonalny, jeśli place_type ma wartość „COUNTRY”. |
language_code |
string, | Kod języka BCP-47, np. „en-US” lub „sr-Latn”, odpowiadający językowi, w którym żądane jest podanie nazwy i adresu miejsca. Jeśli nie zostanie wysłane żadne żądanie, domyślnie zostanie wybrany język angielski. |
SearchRegionRequestData
identyfikatory
REQUIRED:address
, latlng
lub place_id
.
Pole | Typ | Opis |
---|---|---|
address |
string, | Nieuporządkowany adres znajdujący się w obrębie regionu do dopasowania. Jeśli określono address , wymagana jest właściwość region_code . |
latlng |
LatLng | Szerokość i długość geograficzna zawarta w regionie do dopasowania. |
place_id |
string, | Identyfikator miejsca zawarty w regionie, który ma być dopasowywany. |
place_type |
typ miejsca | To pole jest wymagane. Typ regionu do dopasowania. |
language_code |
string, | Kod języka BCP-47, np. „en-US” lub „sr-Latn”, odpowiada językowi, w którym żądane jest podanie nazwy miejsca i adresu. Jeśli nie zostanie wysłane żadne żądanie, domyślnie zostanie wybrany język angielski. |
region_code |
string, | Dwuliterowy kod kraju lub regionu w standardzie ISO-3166 odpowiadający lokalizacji, która ma być dopasowywana.
W przypadku określenia adresu wymagana jest wartość region_code . |
Typy miejsc
Wartość | Opis |
---|---|
POSTAL_CODE |
Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju. |
ADMINISTRATIVE_AREA_LEVEL_1 |
Podmiot cywilny pierwszego stopnia poniżej poziomu kraju. W Stanach Zjednoczonych tymi poziomami administracyjnymi są stany. |
ADMINISTRATIVE_AREA_LEVEL_2 |
Podmiot cywilny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne są hrabstwami. |
LOCALITY |
Jednostka polityczna będąca częścią miasta lub miejscowości. |
COUNTRY |
Narodowy podmiot polityczny, zwykle najwyższego rodzaju. |
LatLng
Obiekt reprezentujący parę szerokości/długości geograficznej. Wartość ta jest wyrażona jako para podwójnej precyzji oznaczająca stopnie szerokości i długości geograficznej w stopniach. O ile nie określono inaczej, ten obiekt musi być zgodny ze standardem WGS84. Wartości muszą się mieścić w znormalizowanych zakresach.
Pole | Typ | Opis |
---|---|---|
latitude |
double, | Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90.0, +90.0] .
Przykład: 47.47583476464538 . |
longitude |
double, | Długość geograficzna w stopniach. Musi mieścić się w zakresie [-180.0, +180.0] .
Przykład: -121.73858779269906 . |
Kody błędów
Wartość | Opis |
---|---|
UnknownError |
Wystąpił nieznany błąd. |
NoMatchFound |
Żądanie nie zwróciło żadnych wyników. Sprawdź atrybut candidate_place_ids , jeśli jest dostępny. |
AddressNotUnderstood |
W przypadku podanego adresu nie udało się przeprowadzić geokodowania. |
PlaceTypeMismatch |
Typ miejsca w odpowiedzi nie pasuje do typu w żądaniu.
Na przykład żądanie locality zostało wysłane, ale zwrócone zostało administrative_area_level_2 . |
MultipleCandidatesFound |
Do danych wejściowych dopasowano więcej niż jednego kandydata. Sprawdź candidate_place_ids .
jeśli są dostępne. |
PlaceNameNotUnderstood |
Nie udało się przypisać podanej nazwy miejsca do regionu. |
UnitCodeNotFound |
Nie znaleziono kodu jednostki. Sprawdź, czy kod jednostki jest prawidłowy i ma prawidłowy format. |
PlaceTypeNotAllowed |
Dopasowanego identyfikatora miejsca nie ma na liście dozwolonych dotyczącej typu miejsca i kraju. |