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

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

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

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

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

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

Для использования API поиска регионов выполните следующие действия:

  1. Включите API поиска регионов в консоли .
  2. Установите библиотеку с открытым исходным кодом : 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";

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

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

  • place или unit_code (обязательно) — либо название региона ( place ), либо unit_code этого места. unit_code может быть либо кодом FIPS (только для штатов и округов США), либо кодом страны ISO-3166-1.
  • place_type (обязательно) Значение типа места , для которого следует выполнить поиск.
  • region_code Двухбуквенный код страны/региона ISO-3166 для сопоставления местоположения. region_code является необязательным, если place_type имеет значение COUNTRY .
  • language это код языка BCP-47, например, "en-US" или "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 вернет идентификатор места для Калифорнии в качестве matched_place_id :

  • place_type : ADMINISTRATIVE_AREA_LEVEL_1

    Результат matched_place_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 : идентификатор места для Калифорнии. Все остальные поддерживаемые типы не дают совпадений.

Если unit_code имеет значение "US", API возвращает следующие результаты при указании следующих place_type :

  • place_type : COUNTRY

    Результат matched_place_id : идентификатор места для Соединенных Штатов. Все остальные поддерживаемые типы не дают совпадений.

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

В случае неоднозначности возвращаются идентификаторы мест-кандидатов. Например, если place — «Округ Санта-Клара», а place_type — LOCALITY то в качестве кандидата возвращается идентификатор места для округа Санта-Клара.

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

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

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

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

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

  • address , широта и latlng или place_id (обязательно). Содержит либо неструктурированную строку адреса, latlng , либо идентификатор места, относящийся к региону (например, точка интереса, здание и т. д.). Если ни один из параметров не указан, возвращается ошибка.
  • place_type (обязательно) Значение типа места , определяющее тип региона для поиска.
  • region_code Двухбуквенный код страны/региона ISO-3166 для сопоставления местоположения. region_code обязателен, если указан address .
  • language это код языка BCP-47, например, "en-US" или "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 , если результат найден. В случае неудачного совпадения ответ содержит один или несколько идентификаторов мест-кандидатов и код ошибки .

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

Ссылка

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

Поле Тип Описание
place нить Название региона, которому нужно присвоить идентификатор места. Используйте поле place в сочетании с place_type для поиска идентификатора места в регионе. Например, если place_type равно "locality", допустимым place может быть "Palo Alto, CA". Если place_type равно `POSTAL_CODE`, допустимым названием места может быть "94109". Если place_type равно `COUNTRY`, допустимым 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" (код Alpha-2 ISO-3166-1 для Соединенных Штатов) или "BR" (код Alpha-2 ISO-3166-1 для Бразилии). Если 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 для округа Майами-Дейд во Флориде). region_code обязателен при указании кода FIPS. region_code игнорируется для кодов стран ISO-3166-1.
place_type Тип места Обязательно. Тип региона, который необходимо сопоставить.
region_code нить Двухбуквенный код страны/региона ISO-3166 для местоположения, которое вы пытаетесь сопоставить. region_code является необязательным, если place_type имеет значение `COUNTRY`.
language_code нить Языковой код BCP-47, например, "en-US" или "sr-Latn", соответствует языку, на котором запрашиваются название места и адрес. Если язык не указан, по умолчанию используется английский.

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

ОБЯЗАТЕЛЬНО: Один из следующих параметров: address , latlng или place_id .

Поле Тип Описание
address нить Неструктурированный уличный адрес, находящийся в пределах соответствующего региона. region_code обязателен при указании address .
latlng LatLng Широта и долгота, содержащиеся в соответствующем регионе.
place_id нить Идентификатор места, находящегося внутри соответствующего региона.
place_type тип места Обязательно. Тип региона, который необходимо сопоставить.
language_code нить Языковой код BCP-47 , например, "en-US" или "sr-Latn", соответствует языку, на котором запрашиваются название места и адрес. Если язык не указан, по умолчанию используется английский.
region_code нить Двухбуквенный код страны/региона ISO-3166 для сопоставления местоположения. region_code обязателен, если указан адрес.

Типы мест

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

LatLng

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

Поле Тип Описание
latitude двойной Широта в градусах. Она должна находиться в диапазоне [-90.0, +90.0] . Например, 47.47583476464538 .
longitude двойной Долгота в градусах. Она должна находиться в диапазоне [-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 Идентификатор соответствующего места отсутствует в списке разрешенных типов мест и стран.