Использование Region Lookup API

Region Lookup API позволяет находить идентификаторы регионов, которые можно использовать для оформления границ с помощью стилей на основе данных. Region Lookup API поддерживает два типа запросов:

Поиск региона по имени – названию места, коду FIPS (только для штатов и округов США) или коду страны ISO-3166-1.
Поиск региона по местоположению – почтовому адресу, координатам LatLng или идентификатору места.

Поддерживаемые типы регионов

Поддерживаются следующие типы регионов: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Установка библиотеки

Для работы с Region Lookup API выполните следующие действия:

Включите Region Lookup API в консоли.
Установите библиотеку с открытым исходным кодом: npm install @googlemaps/region-lookup.

Импорт зависимостей из библиотеки

Библиотека с открытым исходным кодом Region Lookup – это набор функций и типов TypeScript, которые вам нужно импортировать в свой код.

Для поиска региона по имени импортируйте следующие функции:

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

Для поиска региона по местоположению импортируйте следующие функции:

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

Поиск региона по названию

Такие запросы принимают название или идентифицирующий код места и возвращают его ID. Чтобы найти регион по названию, вызовите метод lookupRegion(), указав данные LookupRegionRequestData со следующими параметрами:

place или unit_code (обязательно) – название региона place или код региона unit_code (unit_code может быть кодом страны ISO-3166-1 или кодом FIPS штатов и округов США).
place_type (обязательно) – тип места, которое нужно найти.
region_code – двухбуквенный код ISO-3166 страны или территории, которую нужно найти. region_code необязательно использовать, если place_type – COUNTRY.
language – код языка по стандарту BCP-47, например "ru-RU" или "sr-Latn". Если не указан, по умолчанию принимается значение "en-US".

В следующем примере показан поисковый запрос для города Ньюарка (штат Нью-Джерси).

// 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 });

Параметр place или unit_code должен быть указан обязательно, иначе будет возвращена ошибка.

Параметр region_code обязателен, если только place_type не равен COUNTRY.

place и unit_code определяют местоположение по идентификатору места. Например, если place – "California", а place_type – ADMINISTRATIVE_AREA_LEVEL_1, API вернет ID штата Калифорния в виде matched_place_id:

place_type: ADMINISTRATIVE_AREA_LEVEL_1

Результаты в matched_place_id: ID штата Калифорния (остальные типы совпадений не возвращаются).

Если unit_code равен "6" (код FIPS для Калифорнии), place_type – ADMINISTRATIVE_AREA_LEVEL_1, а region_code – "US," API вернет идентификатор штата Калифорния:

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

Результаты в matched_place_id: ID штата Калифорния (остальные типы совпадений не возвращаются).

Если unit_code – "US", возвращенный результат будет зависеть от того, какой place_type определен:

place_type: COUNTRY

Результаты в matched_place_id: ID США (остальные типы совпадений не возвращаются).

Если совпадений не найдено, matched_place_id определен не будет.

В случае неоднозначности возвращаются неточные варианты мест. Например, если place – "Santa Clara County", а place_type – LOCALITY, то будет возвращен ID округа Санта-Клара.

Ответ Region Lookup API

Если совпадение найдено, то объект LookupRegionResponse будет содержать matched_place_id. Если результат не найден, то в качестве вероятного совпадения возвращаются ID мест с более низкими уровнями соответствия запросу, а также код ошибки со сведениями для отладки.

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

Запросы поиска по региону

Чтобы найти регион, содержащий определенное местоположение, вызовите searchRegion и определите SearchRegionRequestData, указав следующие параметры:

address, latlng, place_id (обязательно) – неструктурированный адрес, координаты latlng или ID места, находящегося на территории региона (достопримечательности, здания и т. д.). Если в запросе нет таких параметров, будет возвращена ошибка.
place_type (обязательно) – тип места, который нужно найти.
region_code – двухбуквенный код ISO-3166 страны или территории, которую нужно найти (параметр region_code обязателен, когда указан адрес address).
language – код языка по стандарту BCP-47, например "ru-RU" или "sr-Latn". Если не указан, по умолчанию принимается значение "en-US".

В примере ниже показан запрос, возвращающий Бербанк (Калифорния).

// 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 });

Ответ на запрос поиска по региону

Если совпадение найдено, то объект SearchRegionResponse будет содержать matched_place_id. Если совпадений не найдено, в ответе будет возвращено несколько ID возможных совпадений и код ошибки.

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

Справочник

Идентификаторы `LookupRegionRequestData`

Поле	Тип	Описание
`place`	строка	Название региона, найденного по ID места. Для поиска по идентификатору места используйте поле `place` в сочетании с `place_type`. Например, если `place_type` – locality (населенный пункт), возможным результатом `place` может быть "Palo Alto, CA" (Пало-Альто, Калифорния). Если `place_type` – "POSTAL_CODE" (почтовый индекс), возможным значением place_name can может быть "94109"; если `place_type` – возможным значением `place` может быть "United States" (США) и т. д. В запросе `region_code` необходимо указывать `place`, если только вы не ищете страну (переменной `place_type` присвоено значение "COUNTRY").
`unit_code`	строка	FIPS-коды штатов или округов (только для США) или код страны ISO-3166-1, по которым нужно найти результат. Поле `unit_code` используется в сочетании с `place_type` для поиска идентификатора региона. Например, если `place_type` – `COUNTRY` (страна), то допустимым значением unit_code может быть "US" (код ISO-3166-1 Alpha-2 для США) или "BR" (код ISO-3166-1 Alpha-2 для Бразилии). Если `place_type` – `ADMINISTRATIVE_AREA_LEVEL_1` (штат), а region_code – "US", то допустимым значением unit_code может быть "6" (FIPS-код для Калифорнии) или "12" (FIPS-код для Флориды). Если place_type – `ADMINISTRATIVE_AREA_LEVEL_2` (округ), а region_code – "US", то допустимым значением unit_code может быть "6001" (FIPS-код округа Аламеда, штат Калифорния) или "12086" (FIPS-код округа Майами-Дейд, штат Флорида). При запросе с кодом FIPS обязательно указывать `region_code`. Значение `region_code` игнорируется, если в поиске запрашивается код ISO-3166-1 страны.
`place_type`	PlaceType	Это обязательное поле. Тип региона, который нужно найти.
`region_code`	строка	Двухбуквенный код ISO-3166 страны или территории, которую нужно найти (region_code необязательно указывать, если для `place_type` задано значение "COUNTRY").
`language_code`	строка	Код языка, на котором сделан запрос с названием места или адресом, по стандарту BCP-47, например "ru-RU" или "sr-Latn". Если не указан, по умолчанию применяется английский.

Идентификаторы `SearchRegionRequestData`

ОБЯЗАТЕЛЬНО: address, latlng или place_id.

Поле	Тип	Описание
`address`	строка	Неструктурированный почтовый адрес, относящийся к искомому региону (параметр `region_code` обязателен, когда указан адрес `address`).
`latlng`	LatLng	Географическая координата на территории искомого региона.
`place_id`	строка	Идентификатор места, находящегося в искомом регионе.
`place_type`	тип места	Это обязательное поле. Тип региона, который нужно найти.
`language_code`	строка	Код языка, на котором сделан запрос с названием места или адресом, по стандарту BCP-47, например "ru-RU" или "sr-Latn". Если не указан, по умолчанию применяется английский.
`region_code`	строка	Двухбуквенный код ISO-3166 страны или территории, которую нужно найти (параметр `region_code` обязателен, если в запросе указан адрес).

Типы мест

Значение	Описание
`POSTAL_CODE`	Почтовый округ (соответствует почтовому индексу).
`ADMINISTRATIVE_AREA_LEVEL_1`	Первый уровень национального административного деления. В США такому уровню соответствуют штаты.
`ADMINISTRATIVE_AREA_LEVEL_2`	Второй уровень национального административного деления. В США такому уровню соответствуют округа.
`LOCALITY`	Городская административная единица.
`COUNTRY`	Политическое образование национального уровня (как правило, он самый высокий).

LatLng

Объект, содержащий географические координаты в виде значений широты и долготы. Представляет собой пару значений с плавающей запятой (double). Если не указано иное, координаты задаются в системе WGS84. Также они должны попадать в нормализованные диапазоны значений.

Поле	Тип	Описание
`latitude`	double	Градусная мера широты. Должна попадать в диапазон `[-90.0, +90.0]`. Пример: `47.47583476464538`.
`longitude`	double	Градусная мера долготы. Должна попадать в диапазон `[-180.0, +180.0]`. Пример: `-121.73858779269906`.

Коды ошибок

Значение	Описание
`UnknownError`	Произошла неизвестная ошибка.
`NoMatchFound`	Запрос не дал результатов, проверьте возможные совпадения `candidate_place_ids` (если есть).
`AddressNotUnderstood`	Не удалось геокодировать адрес из запроса.
`PlaceTypeMismatch`	Тип места в ответе не соответствует типу места в запросе. Например, вы запросили `locality`, а в ответ получили `administrative_area_level_2`.
`MultipleCandidatesFound`	По запросу найдено несколько возможных вариантов. Проверьте значения `candidate_place_ids` (если есть).
`PlaceNameNotUnderstood`	По запросу с названием места не найдено региона.
`UnitCodeNotFound`	Нет информации о системе единиц. Проверьте, верно ли указана система единиц и предоставлены ли данные в нужном формате.
`PlaceTypeNotAllowed`	Найденный ID не входит в белый список (по типу мест или стране).