Использование 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 является необязательным, если тип_места равен 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 — «США», 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 имеет значение «местность», допустимым place может быть «Пало-Альто, Калифорния». Если place_type равен POSTAL_CODE, допустимое имя_места может быть «94109». Если place_type имеет значение «СТРАНА», допустимым place может быть «США» и т. д. region_code требуется, когда указано place , если только place_type не имеет значение «СТРАНА».
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 (штат), а регион_code — «США», допустимым unit_code может быть «6» (код FIPs для Калифорнии) или «12» (код FIPs для Флориды). Если Place_type — ADMINISTRATIVE_AREA_LEVEL_2 (округ), а регион_код — «США», действительным unit_code может быть «6001» (код FIPs для округа Аламеда в Калифорнии) или «12086» (код FIPs для округа Майами-Дейд во Флориде). region_code требуется при указании кода FIPs. region_code игнорируется для кодов стран ISO-3166-1.
place_type Тип места Необходимый. Тип региона для сопоставления.
region_code нить Двухбуквенный код страны/региона ISO-3166 для местоположения, которое вы пытаетесь сопоставить. Код_региона является необязательным, если place_type имеет значение «СТРАНА».
language_code нить Код языка BCP-47, например «en-US» или «sr-Latn», соответствующий языку, на котором запрашиваются название места и адрес. Если ничего не запрашивается, то по умолчанию используется английский язык.

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

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

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