Korzystanie z interfejsu Region Lookup API

Za pomocą interfejsu API Region Lookup można znaleźć identyfikatory miejsc dla regionów, które można wykorzystać do stylizowania wielokątów granicznych podczas stylizowania granic na podstawie danych. Interfejs API wyszukiwania regionów obsługuje dwa rodzaje żądań:

  • Wyszukiwanie regionu umożliwia wyszukiwanie regionu według nazwy miejsca, kodu FIPS (tylko w przypadku stanów i hrabstw w USA) lub kodu kraju ISO 3166-1.
  • Wyszukiwanie regionu wyszukuje region, w którym znajduje się określona lokalizacja wskazana przez 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 skorzystać z interfejsu API wyszukiwania regionów, wykonaj następujące kroki:

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

Importuj zależności z biblioteki

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

  • W przypadku żądań wyszukiwania regionów należy zaimportować następujące dane:

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

  • W przypadku żądań wyszukiwania regionalnego należy zaimportować następujące dane:

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

Żądania wyszukiwania regionu

Żądanie wyszukiwania regionu przyjmuje nazwę miejsca lub kod identyfikacyjny 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 w przypadku stanów i hrabstw w USA) lub kodem kraju zgodnym z normą ISO-3166-1.
  • place_type (wymagany) Wartość typu miejsca dla typu miejsca, które ma zostać wyszukane.
  • region_code Dwuliterowy kod kraju lub regionu w formacie ISO-3166, który ma być dopasowany do lokalizacji. region_code jest opcjonalny, jeśli typ miejsca to COUNTRY.
  • language Kod języka BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie podasz żadnej wartości, zostanie użyty język domyślny en-US.

Poniższy przykład pokazuje żądanie wyszukiwania dla Newark, 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 podano żadnego z tych argumentów, zwracany jest błąd.

Parametr region_code jest wymagany, chyba że parametr 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 dla 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 dla Kalifornii), place_type to ADMINISTRATIVE_AREA_LEVEL_1, a region_code to „US”, interfejs API zwraca identyfikator miejsca dla 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”, API zwraca następujące wyniki, gdy określone zostaną następujące parametry 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 dopasowanie, wartość matched_place_id nie zostanie ustawiona.

W przypadku niejednoznaczności zwracane są identyfikatory miejsc kandydatów. Jeśli na przykład place to „Santa Clara County”, a place_type to LOCALITY, jako kandydat zostanie zwrócony identyfikator miejsca dla hrabstwa Santa Clara.

Odpowiedź wyszukiwania w regionie

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

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

Żądania wyszukiwania według fragmentu

Aby znaleźć region, w którym znajduje się określona lokalizacja, wywołaj funkcję searchRegion, podając SearchRegionRequestData z tymi parametrami:

  • address lub latlng lub place_id (wymagany) zawiera nieustrukturyzowany ciąg adresu, latlng lub identyfikator miejsca zawarty w regionie (np. punkt orientacyjny, budynek itp.). Jeśli nie podano żadnego z nich, zwracany jest błąd.
  • place_type (wymagane) Wartość place type określająca typ regionu, w którym chcesz wyszukiwać.
  • region_code Dwuliterowy kod kraju lub regionu w formacie ISO-3166, który ma być dopasowany do lokalizacji. Właściwość region_code jest wymagana, jeśli określono address.
  • language Kod języka BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie podasz żadnej wartości, zostanie użyty język domyślny en-US.

Poniższy przykład pokazuje żą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ź wyszukiwania według fragmentu

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

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

Plik referencyjny

LookupRegionRequestData identyfikatory,

Pole Typ Opis
place ciąg znaków Nazwa regionu, który ma być dopasowany do identyfikatora miejsca. Użyj pola place w połączeniu z place_type, aby wyszukać identyfikator miejsca regionu. Jeśli na przykład place_type to „locality”, prawidłowa wartość place może być „Palo Alto, CA”. Jeśli place_type ma wartość „POSTAL_CODE”, prawidłowa wartość place_name może być „94109”. Jeśli place_type ma wartość „COUNTRY”, prawidłowa wartość place może być np. „United States”. Właściwość region_code jest wymagana, gdy określono place, chyba że place_type ma wartość „COUNTRY”.
unit_code ciąg znaków Kody stanu lub hrabstwa FIPS (tylko w Stanach Zjednoczonych) lub kod kraju ISO 3166-1, który ma być dopasowany. 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 jednostki może być „US” (kod Stanów Zjednoczonych w formacie ISO-3166-1 alfa-2) lub „BR” (kod Brazylii w formacie ISO-3166-1 alfa-2). Jeśli place_type jest ADMINISTRATIVE_AREA_LEVEL_1 (stan), a region_code to „US”, prawidłowy kod jednostki może mieć wartość „6” (kod FIP dla Kalifornii) lub „12” (kod FIP dla Florydy). Jeśli place_type to ADMINISTRATIVE_AREA_LEVEL_2 (hrabstwo), a region_code to „US”, prawidłowy unit_code może mieć wartość „6001” (kod FIPs hrabstwa Alameda w Kalifornii) lub „12086” (kod FIPs hrabstwa Miami-Dade na Florydzie). region_code jest wymagany, gdy podajesz kod FIP. W przypadku kodów krajów zgodnych z normą ISO-3166-1 znak region_code jest ignorowany.
place_type PlaceType Wymagane. Typ regionu do dopasowania.
region_code ciąg znaków Dwuliterowy kod kraju lub regionu w formacie ISO 3166 dla lokalizacji, do której chcesz dopasować dane. Parametr region_code jest opcjonalny, jeśli place_type ma wartość „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 wysyłane są żądania dotyczące nazwy i adresu miejsca. Jeśli nie podasz żadnego języka, domyślnie zostanie użyty język angielski.

SearchRegionRequestData identyfikatory,

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 do dopasowania. Właściwość region_code jest wymagana, jeśli określono address.
latlng LatLng Szerokość i długość geograficzna, które znajdują się w regionie, aby pasować.
place_id ciąg znaków Identyfikator miejsca zawarty w regionie, który ma być dopasowany.
place_type typ miejsca Wymagane. Typ regionu do dopasowania.
language_code ciąg znaków Kod języka BCP-47, np. „en-US” lub „sr-Latn”, odpowiadający językowi, w którym żądana jest nazwa i adres miejsca. Jeśli nie zostanie podany żaden język, domyślnie będzie to angielski.
region_code ciąg znaków Dwuliterowy kod kraju lub regionu w standardzie ISO 3166, który ma pasować do lokalizacji. Właściwość region_code jest wymagana, jeśli podano adres.

Typy miejsc

Wartość Opis
POSTAL_CODE Kod pocztowy używany do adresowania przesyłek pocztowych na terenie danego kraju.
ADMINISTRATIVE_AREA_LEVEL_1 Jednostka administracyjna pierwszego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to stany.
ADMINISTRATIVE_AREA_LEVEL_2 Jednostka administracyjna drugiego rzędu poniżej poziomu kraju. W Stanach Zjednoczonych są to hrabstwa.
LOCALITY podmiot polityczny w postaci miasta lub miejscowości;
COUNTRY Narodowy podmiot polityczny, zwykle typ najwyższego rzędu.

LatLng

Obiekt reprezentujący parę szerokości i długości geograficznej. Jest to para liczb zmiennoprzecinkowych podwójnej precyzji, które reprezentują 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 żadnych wyników. Sprawdź, czy candidate_place_idsjest dostępny.
AddressNotUnderstood Nie udało się geokodować podanego adresu.
PlaceTypeMismatch Typ miejsca podany w odpowiedzi nie zgadza się z typem podanym w zapytaniu. Na przykład zażądano locality, ale zwrócono administrative_area_level_2.
MultipleCandidatesFound Do danych wejściowych dopasowano kilku kandydatów. Sprawdź candidate_place_ids. jeśli jest dostępna.
PlaceNameNotUnderstood Podana nazwa miejsca nie została przekształcona w nazwę regionu.
UnitCodeNotFound Kod jednostki nie został znaleziony. Sprawdź, czy kod jednostki jest prawidłowy i podany w odpowiednim formacie.
PlaceTypeNotAllowed Dopasowany identyfikator miejsca nie znajduje się na liście dozwolonych typów miejsc i krajów.