Korzystanie z interfejsu Region Lookup API

Za pomocą interfejsu Region Lookup API możesz znaleźć identyfikatory miejsc w regionach, których możesz używać do stylizowania wielokątów granic w stylu opartym na danych dla granic. Interfejs Region Lookup API obsługuje 2 rodzaje żądań:

  • Wyszukiwanie regionu – wyszukuje region według nazwy miejsca, kodu FIPS (tylko stany i hrabstwa w Stanach Zjednoczonych) lub kodu kraju ISO-3166-1.
  • Wyszukiwanie według fragmentu – wyszukuje region, który zawiera określoną lokalizację podaną jako adres, LatLng lub identyfikator 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.

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 zawiera zestaw funkcji i typów TypeScript, które musisz zaimportować do swojego kodu.

  • W przypadku żądań wyszukiwania regionu zaimportuj te elementy:

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

  • W przypadku żądań wyszukiwania według fragmentu zaimportuj te elementy:

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

Żądania wyszukiwania regionu

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

  • place lub unit_code (wymagane) – nazwa regionu (place) lub unit_code miejsca. unit_code może być kodem FIPS (tylko stany i hrabstwa w Stanach Zjednoczonych) lub kodem kraju ISO-3166-1.
  • place_type (wymagane) – wartość typu miejsca, które chcesz wyszukać.
  • region_code – dwuliterowy kod kraju/regionu ISO-3166 dla lokalizacji, która ma pasować. region_code jest opcjonalny, jeśli place_type to COUNTRY.
  • language – kod języka w formacie BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie określisz żadnego kodu, domyślnie zostanie użyty kod en-US.

Ten przykład pokazuje żądanie wyszukiwania dla 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 określisz żadnego z nich, zostanie zwrócony błąd.

Parametr region_code jest wymagany, chyba że place_type to COUNTRY.

place i unit_code określają lokalizację, do której ma pasować identyfikator miejsca. Jeśli np. jeśli place to „Kalifornia”, a place_type to ADMINISTRATIVE_AREA_LEVEL_1, interfejs API zwróci identyfikator miejsca w Kalifornii jako matched_place_id:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

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

Jeśli unit_code to „6” (kod FIPS dla Kalifornii), place_type to ADMINISTRATIVE_AREA_LEVEL_1, a region_code to „US”, interfejs API zwróci identyfikator miejsca w Kalifornii:

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

  • region_code: US

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

Jeśli unit_code to „US”, interfejs API zwróci te wyniki, gdy zostaną określone te wartości place_types:

  • place_type: COUNTRY

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

Jeśli nie znaleziono dopasowania, matched_place_id nie jest ustawiony.

W przypadku niejednoznaczności zwracane są identyfikatory miejsc kandydatów. Jeśli np. place to „Santa Clara County”, a place_type to LOCALITY, identyfikator miejsca w hrabstwie Santa Clara jest zwracany jako kandydat.

Odpowiedź na żądanie wyszukiwania regionu

Jeśli znaleziono wynik, obiekt LookupRegionResponse zawiera matched_place_id. Jeśli nie znaleziono wyniku, identyfikatory miejsc o niższym poziomie ufności są zwracane jako identyfikatory kandydatów, wraz z kodem błędu zawierającym informacje na potrzeby debugowania.

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

Żądania wyszukiwania według fragmentu

Aby znaleźć region, który zawiera określoną lokalizację, wywołaj funkcję searchRegion podając SearchRegionRequestData z tymi parametrami:

  • address lub latlng lub place_id (wymagane) – zawiera nieustrukturyzowany ciąg znaków adresu, latlng lub identyfikator miejsca znajdującego się w regionie (np. punkt orientacyjny, budynek itp.). Jeśli nie określisz żadnego z nich, zostanie zwrócony błąd.
  • place_type (wymagane) – wartość typu regionu, który chcesz wyszukać.
  • region_code – dwuliterowy kod kraju/regionu ISO-3166 dla lokalizacji, która ma pasować. region_code jest wymagany, gdy określono address.
  • language – kod języka w formacie BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie określisz żadnego kodu, domyślnie zostanie użyty kod en-US.

Ten przykład pokazuje żądanie wyszukiwania dla 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ź na żądanie wyszukiwania według fragmentu

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

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

Dokumentacja

Identyfikatory LookupRegionRequestData

Pole Typ Opis
place ciąg znaków Nazwa regionu, która ma pasować do identyfikatora miejsca. Aby wyszukać identyfikator miejsca w regionie, użyj pola place w połączeniu z place_type. Jeśli np. place_type to „locality”, prawidłowa wartość place może być „Palo Alto, CA”. Jeśli place_type to `POSTAL_CODE`, prawidłowa wartość place_name może być "94109". Jeśli place_type to `COUNTRY`, prawidłowa wartość place może być „Stany Zjednoczone” itp. Jeśli określono place, wymagany jest region_code, chyba że place_type to `COUNTRY`.
unit_code ciąg znaków Kody stanu lub hrabstwa FIPS (tylko w Stanach Zjednoczonych) lub kod kraju ISO-3166-1 do dopasowania. Pole unit_code jest używane w połączeniu z place_type do wyszukiwania identyfikatora miejsca w regionie. Przykład: jeśli place_type to COUNTRY, prawidłowa wartość 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łowa wartość unit_code może być „6” (kod FIPS dla Kalifornii) lub „12” (kod FIPS dla Florydy). Jeśli place_type to ADMINISTRATIVE_AREA_LEVEL_2 (hrabstwo), a region_code to "US", prawidłowa wartość unit_code może być "6001" (kod FIPS dla hrabstwa Alameda w Kalifornii) lub "12086" (kod FIPS dla hrabstwa Miami-Dade na Florydzie). region_code jest wymagany podczas określania kodu FIPS. region_code jest ignorowany w przypadku kodów krajów ISO-3166-1.
place_type PlaceType Wymagane. Typ regionu, który ma pasować.
region_code ciąg znaków Dwuliterowy kod kraju/regionu ISO-3166 dla lokalizacji, która ma pasować do dopasowania. region_code jest opcjonalny, jeśli place_type to `COUNTRY`.
language_code ciąg znaków Kod języka w formacie BCP-47, np. "en-US" lub "sr-Latn", odpowiadający językowi, w którym jest żądana nazwa miejsca i adres. Jeśli nie określisz żadnego kodu, domyślnie zostanie użyty język angielski.

Identyfikatory SearchRegionRequestData

WYMAGANE: jeden z tych elementów: address, latlng lub place_id.

Pole Typ Opis
address ciąg znaków Nieustrukturyzowany adres ulicy, który znajduje się w regionie, który ma pasować. region_code jest wymagany, jeśli określono address.
latlng LatLng Szerokość i długość geograficzna, które znajdują się w regionie, który ma pasować.
place_id ciąg znaków Identyfikator miejsca, które znajduje się w regionie, który ma pasować.
place_type typ miejsca Wymagane. Typ regionu, który ma pasować.
language_code ciąg znaków Kod języka w formacie BCP-47, np. „en-US” lub „sr-Latn”, odpowiadający językowi, w którym jest żądana nazwa miejsca i adres. Jeśli nie określisz żadnego kodu, domyślnie zostanie użyty język angielski.
region_code ciąg znaków Dwuliterowy kod kraju/regionu ISO-3166 dla lokalizacji, która ma pasować. Jeśli określono adres, wymagany jest region_code.

Typy miejsc

Wartość Opis
POSTAL_CODE Kod pocztowy używany do adresowania przesyłek pocztowych w danym kraju.
ADMINISTRATIVE_AREA_LEVEL_1 Jednostka administracyjna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to stany.
ADMINISTRATIVE_AREA_LEVEL_2 Jednostka administracyjna drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych te poziomy administracyjne to hrabstwa.
LOCALITY Podmiot polityczny w postaci miasta lub miasteczka.
COUNTRY Narodowy podmiot polityczny, zwykle najwyższy typ.

LatLng

Obiekt reprezentujący parę szerokości i długości geograficznej. Jest on wyrażony jako para liczb zmiennoprzecinkowych reprezentujących stopnie szerokości i długości geograficznej. O ile nie określono inaczej, ten obiekt musi być zgodny ze standardem WGS84. Wartości muszą mieścić się w znormalizowanych zakresach.

Pole Typ Opis
latitude podwójny Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90.0, +90.0]. Na przykład 47.47583476464538.
longitude podwójny 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 dopasowania. Jeśli jest dostępny, sprawdź candidate_place_ids .
AddressNotUnderstood Nie udało się przeprowadzić geokodowania podanego adresu.
PlaceTypeMismatch Typ miejsca w odpowiedzi nie jest zgodny z typem miejsca w żądaniu. Na przykład zażądano locality, ale zwrócono administrative_area_level_2.
MultipleCandidatesFound Do danych wejściowych dopasowano wielu kandydatów. Sprawdź candidate_place_ids. jeśli jest dostępny.
PlaceNameNotUnderstood Nie udało się rozpoznać nazwy miejsca jako regionu.
UnitCodeNotFound Nie znaleziono kodu jednostki. Sprawdź, czy kod jednostki jest prawidłowy i podany w prawidłowym formacie.
PlaceTypeNotAllowed Dopasowany identyfikator miejsca nie znajduje się na liście dozwolonych typów miejsc i krajów.