Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

Включить 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";

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

Запрос на поиск региона принимает название места или код идентификатора и возвращает идентификатор места. Чтобы найти регион, вызовите функцию 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 — «Калифорния», а 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 , либо идентификатор места, входящего в регион (например, POI, здание и т. д.). Если ничего не указано, возвращается ошибка.
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`	нить	Коды штатов или округов FIP (только для США) или код страны 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» (код FIP для Калифорнии) или «12» (код FIP для Флориды). Если place_type — `ADMINISTRATIVE_AREA_LEVEL_2` (округ), а region_code — «US», допустимым unit_code может быть «6001» (код FIP для округа Аламеда в Калифорнии) или «12086» (код FIP для округа Майами-Дейд во Флориде). `region_code` требуется при указании кода FIP. `region_code` игнорируется для кодов стран ISO-3166-1.
`place_type`	PlaceType	Обязательно. Тип региона для сопоставления.
`region_code`	нить	Двухбуквенный код страны/региона ISO-3166 для местоположения, которое вы пытаетесь сопоставить. region_code необязателен, если `place_type` — `COUNTRY`.
`language_code`	нить	Код языка BCP-47, например, «en-US» или «sr-Latn», соответствующий языку, на котором запрашиваются название места и адрес. Если запрос не выполнен, по умолчанию используется английский.

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

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

Поле	Тип	Описание
`address`	нить	Неструктурированный почтовый адрес, содержащийся в регионе для сопоставления. При указании `address` требуется `region_code` .
`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`	Национальная политическая единица, как правило, высшего типа.

Широта и долгота

Объект, представляющий пару широта/долгота. Выражается в виде пары чисел двойной точности, представляющих градусы широты и долготы. Если не указано иное, этот объект должен соответствовать стандарту 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`	Совпадающий идентификатор места не входит в список разрешенных типов мест и стран.

Использование Region Lookup API Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

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

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

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

Ссылка

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

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

Типы мест

Широта и долгота

Коды ошибок

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

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

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