Korzystanie z interfejsu Region Lookup API

Za pomocą interfejsu Region Lookup API możesz znaleźć identyfikatory miejsc w regionach, których możesz użyć do nadania stylów granicom w ramach stylizacji opartej na danych. Interfejs Region Lookup API obsługuje 2 rodzaje żądań:

  • Wyszukiwanie regionu umożliwia wyszukiwanie regionu według nazwy miejsca, kodu FIPS (tylko w przypadku stanów i hrabstw w Stanach Zjednoczonych) lub kodu kraju ISO-3166-1.
  • Wyszukiwanie regionalne wyszukuje region, w którym znajduje się określona lokalizacja określona przez adres LatLng lub identyfikator miejsca.

Obsługiwane typy miejsc w regionie

Obsługiwane są te typy regionów: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Instalowanie biblioteki

Aby korzystać z interfejsu Region Lookup API, wykonaj te czynności:

  1. Włącz interfejs Region Lookup API w konsoli.
  2. Zainstaluj bibliotekę open source: npm install @googlemaps/region-lookup

Importowanie zależności z biblioteki

Biblioteka open source Region Lookup udostępnia zestaw funkcji i typów TypeScript, które musisz zaimportować do kodu.

  • W przypadku żądań wyszukiwania regionów zaimportuj te dane:

    import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

  • W przypadku żądań wyszukiwania regionalnego zaimportuj te dane:

    import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

żądania wyszukiwania według regionu,

Żądanie wyszukiwania regionu przyjmuje nazwę miejsca lub kod identyfikacyjny, a zwraca identyfikator miejsca. Aby wyszukać region, wywołaj funkcję lookupRegion(), podając parametr LookupRegionRequestData z tymi parametrami:

  • place lub unit_code (wymagane) Nazwa regionu (place) lub unit_codemiejsca. unit_code może być kodem FIPS (tylko stany i hrabstwa w Stanach Zjednoczonych) lub kodem kraju zgodnym z normą ISO-3166-1.
  • place_type (wymagany) Wartość typu miejsca, którego szukasz.
  • region_code Dwuliterowy kod kraju lub regionu w standardzie ISO 3166, który ma zostać dopasowany. region_code jest opcjonalny, jeśli atrybut place_type ma wartość COUNTRY.
  • language Kod języka BCP-47, np. „pl-PL” lub „sr-Latn”. Jeśli nie określisz żadnego języka, domyślnie zostanie użyty język angielski (USA).

Ten przykład pokazuje żądanie wyszukiwania dotyczące Newark w stanie New Jersey.

// 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 zostanie podany żaden argument, zwrócony zostanie błąd.

Parametr region_code jest wymagany, chyba że place_type ma wartość COUNTRY.

place i unit_code określają lokalizację, która ma być dopasowana do identyfikatora miejsca. Jeśli np. place to „California”, a place_type to „ADMINISTRATIVE_AREA_LEVEL_1”, interfejs API zwraca identyfikator miejsca w Kalifornii jako matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id wyniki: identyfikator miejsca w Kalifornii. Wszystkie inne obsługiwane typy nie zwracają dopasowania.

Jeśli unit_code to „6” (kod FIPS stanu Kalifornia), place_type to ADMINISTRATIVE_AREA_LEVEL_1, a region_code to „US”, interfejs API zwraca identyfikator miejsca w Kalifornii:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

    matched_place_id wyniki: identyfikator miejsca w Kalifornii. Wszystkie inne obsługiwane typy nie zwracają dopasowania.

Jeśli unit_code to „US”, interfejs API zwraca te wyniki, gdy określone są te wartości place_type:

  • place_type: COUNTRY

    matched_place_id wyniki: identyfikator miejsca w Stanach Zjednoczonych. Wszystkie inne obsługiwane typy nie zwracają dopasowania.

Jeśli nie zostanie znalezione żadne dopasowanie, parametr matched_place_id nie zostanie ustawiony.

W przypadku niejednoznaczności zwracane są identyfikatory docelowych miejsc. Jeśli na przykład place to „Santa Clara County”, a place_type to LOCALITY, zwracany jest identyfikator miejsca Santa Clara County.

Odpowiedź na zapytanie o region

Jeśli znaleziono wynik, obiekt LookupRegionResponse zawiera obiekt matched_place_id. Jeśli nie zostanie znaleziony żaden wynik, zwracane są identyfikatory miejsc o niższym poziomie ufności jako identyfikatory docelowe, wraz z kodem błędu zawierającym informacje debugujące.

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

Prośby o wyszukiwanie według fragmentu

Aby znaleźć region zawierający określoną lokalizację, wywołaj funkcję searchRegion, podając parametr SearchRegionRequestData z tymi parametrami:

  • address lub latlng lub place_id (wymagany) zawiera nieuporządkowany ciąg adresu latlng lub identyfikator miejsca zawarty w regionie (np. punkt zainteresowania, budynek itp.). Jeśli nie określisz żadnej wartości, zwrócony zostanie błąd.
  • place_type (wymagany) Wartość typu miejsca dla regionu, w którym ma być przeprowadzone wyszukiwanie.
  • region_code Dwuliterowy kod kraju lub regionu w standardzie ISO 3166, który ma zostać dopasowany. Właściwość region_code jest wymagana, jeśli określono address.
  • language Kod języka BCP-47, np. „pl-PL” lub „sr-Latn”. Jeśli nie określisz żadnego języka, domyślnie zostanie użyty język angielski (USA).

Ten przykład pokazuje żądanie wyszukiwania dotyczące Burbank w Kalifornii.

// 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ź wyszukiwania według fragmentu

Jeśli znaleziono wynik, obiekt SearchRegionResponse zawiera obiekt matched_place_id. W przypadku nieudanego dopasowania odpowiedź zawiera co najmniej 1 identyfikator miejsca docelowego i kod błędu.

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

Dokumentacja

LookupRegionRequestData identyfikatory

Pole Typ Opis
place ciąg znaków Nazwa regionu do dopasowania do identyfikatora miejsca. Aby wyszukać identyfikator miejsca regionu, użyj pola place w połączeniu z polem place_type. Jeśli na przykład place_type to „miejscowość”, prawidłową wartością place może być „Palo Alto, CA”. Jeśli place_type to „POSTAL_CODE”, prawidłową wartością dla place_name może być "94109". Jeśli place_type to „COUNTRY”, prawidłowa wartość place może być np. „United States”. Wartość region_code jest wymagana, gdy określono place, chyba że place_type to „COUNTRY”.
unit_code ciąg znaków Kody stanów lub powiatów FIPs (tylko w Stanach Zjednoczonych) lub kody krajów w formacie ISO-3166-1, które mają być dopasowywane. Pole unit_code jest używane w połączeniu z polem place_type do wyszukiwania identyfikatora miejsca regionu. Przykład: jeśli place_type to COUNTRY, prawidłowy kod unit_code 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 to „US”, prawidłowy kod unit_code może być „6” (kod Fips dla Kalifornii) lub „12” (kod Fips dla Florydy). Jeśli wartość place_type to ADMINISTRATIVE_AREA_LEVEL_2 (hrabstwo) i region_code to „US”, prawidłowy kod unit_code może być „6001” (kod FIPS hrabstwa Alameda w Kalifornii) lub „12086” (kod FIPS hrabstwa Miami-Dade na Florydzie). region_code jest wymagany, jeśli podajesz kod FIPS. Wartość region_code jest ignorowana w przypadku kodów ISO-3166-1.
place_type PlaceType Wymagane. Typ regionu, który ma być dopasowywany.
region_code ciąg znaków Dwuliterowy kod kraju/regionu w formacie ISO-3166 dla lokalizacji, którą chcesz dopasować. Parametr region_code jest opcjonalny, jeśli place_type to „COUNTRY”.
language_code ciąg znaków Kod języka w formacie BCP-47, np. „pl-PL” lub „sr-Latn”, odpowiadający językowi, w którym podano nazwę i adres miejsca. Jeśli nie zostanie podany żaden język, domyślnie zostanie wybrany język angielski.

SearchRegionRequestData identyfikatory

WYMAGANE: address, latlng lub place_id.

Pole Typ Opis
address ciąg znaków Nieustrukturyzowany adres ulicy zawarty w regionie dopasowania. Właściwość region_code jest wymagana, jeśli określono address.
latlng LatLng Szerokość i długość geograficzna zawarta w regionie dopasowania.
place_id ciąg znaków Identyfikator miejsca, który znajduje się w regionie dopasowania.
place_type Typ miejsca Wymagane. Typ regionu, który ma być dopasowywany.
language_code ciąg znaków Kod języka BCP-47, na przykład „pl-PL” lub „sr-Latn”, odpowiadający językowi, w którym wymagana jest nazwa i adres miejsca. Jeśli nie podasz języka, domyślnie zostanie użyty język angielski.
region_code ciąg znaków Dwuliterowy kod kraju/regionu w standardzie ISO 3166, który ma być dopasowywany. Jeśli podany jest adres, musisz podać wartość region_code.

Typy miejsc

Wartość Opis
POSTAL_CODE Kod pocztowy, który służy do adresowania przesyłek pocztowych na terenie danego kraju.
ADMINISTRATIVE_AREA_LEVEL_1 Jednostka prawna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany.
ADMINISTRATIVE_AREA_LEVEL_2 Podmiot prawny drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa.
LOCALITY zarejestrowany podmiot polityczny miasta lub gminy.
COUNTRY Narodowy podmiot polityczny, zwykle najwyższy typ.

LatLng

Obiekt reprezentujący parę szerokości i długości geograficznej. Jest ona wyrażana jako para liczb podwójnie po przecinku reprezentujących stopnie szerokości i długości geograficznej. O ile nie określono inaczej, obiekt ten musi być zgodny ze standardem WGS84. Wartości muszą mieścić się w normalizowanych zakresach.

Pole Typ Opis
latitude double, Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90.0, +90.0]. Na przykład 47.47583476464538.
longitude double, Długość geograficzna w stopniach. Musi mieścić się w zakresie [-180.0, +180.0]. Na przykład -121.73858779269906.

Kody błędów

Wartość Opis
UnknownError Wystąpił nieznany błąd.
NoMatchFound Żądanie nie zwróciło żadnego dopasowania. Sprawdź, czy jest dostępna opcja candidate_place_ids.
AddressNotUnderstood Nie udało się przeprowadzić geokodowania podanego adresu.
PlaceTypeMismatch Typ miejsca w odpowiedzi nie jest zgodny z typem w żądaniu. Na przykład locality zostało żądane, ale administrative_area_level_2 zostało zwrócone.
MultipleCandidatesFound wiele kandydatów zostało dopasowanych do danych wejściowych; Sprawdź candidate_place_ids. jeśli jest dostępna.
PlaceNameNotUnderstood Nie udało się rozpoznać nazwy miejsca jako regionu.
UnitCodeNotFound Nie znaleziono kodu jednostki. Sprawdź, czy kod jednostki jest prawidłowy i podany we właściwym formacie.
PlaceTypeNotAllowed Znaleziony identyfikator miejsca nie znajduje się na liście dozwolonych miejsc o danym typie i w danym kraju.