Korzystanie z interfejsu Region Lookup API

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

  • Wyszukiwanie regionu wyszukuje region według nazwy miejsca, kodu FIPS (tylko stany i hrabstwa USA) lub kodu kraju ISO-3166-1.
  • Wyszukiwanie regionu wyszukuje region zawierający konkretną lokalizację określoną przez adres, LatLng lub identyfikator miejsca.

Typy miejsc w obsługiwanych regionach

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

Instalowanie biblioteki

Aby użyć interfejsu Region Lookup API, wykonaj te czynności:

  1. Włącz 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 regionu zaimportuj te elementy:

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

  • W przypadku żądań wyszukiwania regionu 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 lookupRegion(), podając LookupRegionRequestData z tymi parametrami:

  • place lub unit_code (wymagany): nazwa regionu (place) lub unit_code miejsca. unit_code może być kodem FIPS (tylko stany i hrabstwa USA) lub kodem kraju ISO-3166-1.
  • place_type (wymagany) Wartość typu miejsca dla typu miejsca, które chcesz wyszukać.
  • region_code Dwuliterowy kod kraju lub regionu w standardzie ISO-3166, który ma być dopasowany do lokalizacji. Atrybut region_code jest opcjonalny, jeśli atrybut place_type ma wartość COUNTRY.
  • language Kod języka w standardzie BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie określisz żadnego, domyślnie zostanie użyty 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, zwracany jest błąd.

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

place i unit_code określają lokalizację, do której ma zostać dopasowany identyfikator miejsca. Jeśli na przykład 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

    Wyniki dla zapytania matched_place_id: identyfikator miejsca dla 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 dla Kalifornii. Wszystkie inne obsługiwane typy nie zwracają dopasowania.

Jeśli unit_code to „US”, interfejs API zwraca te wyniki, gdy podane 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 dopasowanie, parametr matched_place_id nie zostanie ustawiony.

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, identyfikator miejsca Santa Clara County zostanie zwrócony jako kandydat.

Odpowiedź na wyszukiwanie regionu

Jeśli wynik został znaleziony, obiekt LookupRegionResponse zawiera matched_place_id. Jeśli nie zostanie znaleziony żaden wynik, 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 fragmentu

Aby znaleźć region zawierający konkretną lokalizację, wywołaj searchRegion, podając SearchRegionRequestData z tymi parametrami:

  • address lub latlng lub place_id (wymagany) Zawiera nieuporządkowany ciąg znaków adresu, latlng lub identyfikator miejsca w regionie (np. ciekawe miejsce, budynek itp.). Jeśli nie podano żadnego, zwracany jest błąd.
  • place_type (wymagany) Wartość typu miejsca dla typu regionu, który chcesz wyszukać.
  • region_code Dwuliterowy kod kraju lub regionu w standardzie ISO-3166, który ma być dopasowany do lokalizacji. Właściwość region_code jest wymagana, gdy określono address.
  • language Kod języka w standardzie BCP-47, np. „en-US” lub „sr-Latn”. Jeśli nie określisz żadnego, domyślnie zostanie użyty en-US.

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

Jeśli wynik został znaleziony, obiekt SearchRegionResponse zawiera matched_place_id. W przypadku nieudanego dopasowania odpowiedź zawiera co najmniej 1 identyfikator miejsca kandydującego i kod błędu.

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

Dokumentacja

LookupRegionRequestData identyfikatorów

Pole Typ Opis
place tekst Nazwa regionu, który ma zostać dopasowany 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łowa wartość place_name to np. „94109”. Jeśli place_type to `COUNTRY`, prawidłową wartością place może być „Polska” itp. Jeśli określono place, wymagana jest wartość region_code, chyba że place_type to `COUNTRY`.
unit_code tekst Kody stanów lub hrabstw FIPS (tylko w Stanach Zjednoczonych) albo kody krajów ISO-3166-1, które mają być dopasowane. Pole unit_code jest używane w połączeniu z polem place_type do wyszukiwania identyfikatora miejsca w regionie. Na przykład: jeśli place_type to COUNTRY, prawidłowy kod unit_code może mieć wartość „US” (kod ISO-3166-1 Alpha-2 dla Stanów Zjednoczonych) lub „BR” (kod ISO-3166-1 Alpha-2 dla Brazylii). Jeśli place_type to ADMINISTRATIVE_AREA_LEVEL_1 (stan), a region_code to „US”, prawidłowym kodem 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łowym unit_code może być „6001” (kod FIPs hrabstwa Alameda w Kalifornii) lub „12086” (kod FIPs hrabstwa Miami-Dade na Florydzie). Jeśli podajesz kod FIPS, musisz też podać region_code. Wartość region_code jest ignorowana w przypadku kodów krajów w formacie ISO-3166-1.
place_type PlaceType Wymagane. Typ regionu do dopasowania.
region_code tekst Dwuliterowy kod kraju lub regionu w formacie ISO-3166 dla lokalizacji, którą chcesz dopasować. Parametr region_code jest opcjonalny, jeśli place_type ma wartość `COUNTRY`.
language_code tekst Kod języka w standardzie 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 określony, domyślnie używany jest język angielski.

SearchRegionRequestData identyfikatorów

WYMAGANE: jedna z tych wartości: address, latlng lub place_id.

Pole Typ Opis
address tekst Nieustrukturyzowany adres, który znajduje się w regionie, do którego ma zostać dopasowany. Właściwość region_code jest wymagana, gdy określono address.
latlng LatLng Szerokość i długość geograficzna zawarte w regionie, który ma zostać dopasowany.
place_id tekst Identyfikator miejsca, który znajduje się w regionie, który ma zostać dopasowany.
place_type place type Wymagane. Typ regionu do dopasowania.
language_code tekst 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 określony, domyślnie używany jest język angielski.
region_code tekst Dwuliterowy kod kraju lub regionu w standardzie ISO-3166, który odpowiada lokalizacji. Jeśli podano adres, wymagane jest pole 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 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 miasta lub miejscowości;
COUNTRY Narodowy podmiot polityczny, zwykle najwyższego poziomu.

LatLng

Obiekt reprezentujący parę współrzędnych szerokości i długości geograficznej. Jest ona wyrażona jako 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 przyniosło żadnych wyników. Sprawdź candidate_place_ids, jeśli jest dostępny.
AddressNotUnderstood Nie udało się przeprowadzić geokodowania podanego adresu.
PlaceTypeMismatch Typ miejsca w odpowiedzi nie pasuje do typu miejsca w żądaniu. Na przykład żądano locality, ale zwrócono administrative_area_level_2.
MultipleCandidatesFound Do danych wejściowych dopasowano kilka opcji. Sprawdź candidate_place_ids. (jeśli jest dostępny).
PlaceNameNotUnderstood Podana nazwa miejsca nie została rozpoznana jako region.
UnitCodeNotFound Nie znaleziono kodu jednostki. Sprawdź, czy kod jednostki jest prawidłowy i podany we właściwym formacie.
PlaceTypeNotAllowed Dopasowany identyfikator miejsca nie znajduje się na liście dozwolonych typów miejsc i krajów.