Korzystanie z interfejsu Region Lookup API

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:

  1. Włącz w konsoli interfejs Region Lookup API.
  2. 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 lub unit_code (wymagane) Nazwa regionu (place) lub unit_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. Pole region_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 lub place_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ślono address, 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.