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 określania stylu wielokątów granic w stylu opartym na danych dla granic. Interfejs Region Lookup API obsługuje 2 rodzaje żądań:

  • Wyszukiwanie regionu umożliwia wyszukiwanie regionu według nazwy miejsca, kodu FIPS (tylko stany i hrabstwa 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 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 definicji 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 w regionie zaimportuj te elementy:

    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. W przypadku wszystkich innych obsługiwanych typów nie ma 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. W przypadku wszystkich innych obsługiwanych typów nie ma dopasowania.

Jeśli wartość 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 w Stanach Zjednoczonych. W przypadku wszystkich innych obsługiwanych typów nie ma dopasowania.

Jeśli nie zostanie znalezione dopasowanie, wartość matched_place_id nie zostanie ustawiona.

W przypadku niejednoznaczności zwracane są identyfikatory miejsc kandydackich. 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 (wymagane) 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 (wymagany) 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"
    }
  ]
}

Dokumentacja

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 USA) 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 mieć wartość „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 jest żądanie nazwy i adresu miejsca. Jeśli nie podasz żadnego języka, domyślnie zostanie użyty język angielski.

SearchRegionRequestData identyfikatory,

WYMAGANE: jeden z 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 znajdującego się 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 zostanie użyty język 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 w odpowiedzi nie pasuje do typu miejsca w żądaniu. Na przykład wysłano prośbę o 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 Nie udało się rozpoznać podanej nazwy miejsca jako regionu.
UnitCodeNotFound Nie znaleziono kodu jednostki. 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.