Сервис Geocoding

Примечание: серверные библиотеки
Разработчики из Европейской экономической зоны (ЕЭЗ)

Обзор

Геокодирование — это процесс преобразования адресов (например, «1600 Amphitheatre Parkway, Mountain View, CA») в географические координаты (например, широта 37.423021 и долгота -122.083739), которые можно использовать для размещения маркеров или позиционирования на карте.

Обратное геокодирование — это процесс преобразования географических координат в удобочитаемый адрес (см. Обратное геокодирование (поиск адреса) ).

Вы также можете использовать геокодер для поиска адреса для заданного идентификатора места .

API JavaScript для работы с картами предоставляет класс Geocoder для динамического геокодирования и обратного геокодирования на основе пользовательского ввода. Если же вам необходимо геокодировать статические, известные адреса, см. веб-сервис Geocoding .

Начать

Прежде чем использовать сервис геокодирования в JavaScript API карт, убедитесь, что API геокодирования включен в консоли Google Cloud в том же проекте, который вы настроили для JavaScript API карт.

Чтобы просмотреть список включенных API:

  1. Перейдите в консоль Google Cloud .
  2. Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для API JavaScript карт, и нажмите «Открыть» .
  3. В списке API на панели управления найдите API геокодирования .
  4. Если вы видите API в списке, значит, все в порядке. Если API отсутствует в списке, включите его:
    1. В верхней части страницы выберите «Включить API» , чтобы отобразить вкладку «Библиотека» . В качестве альтернативы, в меню слева выберите «Библиотека» .
    2. Найдите в поиске «Geocoding API» , затем выберите его из списка результатов.
    3. Выберите «Включить» . После завершения процесса API геокодирования появится в списке API на панели управления .

Цены и политика

Цены

Чтобы узнать о ценообразовании и политике использования сервиса геокодирования JavaScript, см. раздел «Использование и выставление счетов для API геокодирования».

Политики

Использование вами сервиса геокодирования должно осуществляться в соответствии с Политикой использования API геокодирования .

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

Доступ к сервису геокодирования осуществляется асинхронно, поскольку API Google Maps должен обращаться к внешнему серверу. По этой причине необходимо передать метод обратного вызова , который будет выполнен после завершения запроса. Этот метод обратного вызова обрабатывает результат(ы). Обратите внимание, что геокодер может вернуть более одного результата.

Вы можете получить доступ к сервису геокодирования Google Maps API в своем коде, используя конструктор google.maps.Geocoder . Метод Geocoder.geocode() инициирует запрос к сервису геокодирования, передавая ему литерал объекта GeocoderRequest содержащий входные параметры, и метод обратного вызова, который будет выполнен после получения ответа.

Литерал объекта GeocoderRequest содержит следующие поля:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Обязательные параметры: Необходимо указать одно, и только одно, из следующих полей:

  • address — адрес, который вы хотите геолоцировать.
    или
    location — координаты LatLng (или LatLngLiteral ), для которых вы хотите получить ближайший, удобочитаемый адрес. Геокодер выполняет обратное геокодирование . Дополнительную информацию см. в разделе «Обратное геокодирование» .
    или
    placeId — Идентификатор места, для которого вы хотите получить ближайший, удобочитаемый адрес. Подробнее о получении адреса для идентификатора места см . здесь.

Дополнительные параметры:

  • bounds — Диапазон LatLngBounds в пределах которого результаты геокодирования будут более заметно смещены. Параметр bounds будет влиять только на результаты геокодирования, но не ограничивать их полностью. Дополнительную информацию о смещении области просмотра см. ниже.
  • componentRestrictions — Используется для ограничения результатов поиска определенной областью. Подробнее о фильтрации компонентов см. ниже.
  • region — Код региона, заданный в виде двухсимвольного (нечислового) субтега региона Unicode. В большинстве случаев эти теги напрямую соответствуют привычным двухсимвольным значениям ccTLD («домен верхнего уровня»). Параметр region будет только влиять на результаты работы геокодера, но не ограничивать их полностью. Дополнительную информацию о смещении кода региона см. ниже.
  • extraComputations — Единственное допустимое значение для этого параметра — ADDRESS_DESCRIPTORS . Дополнительные сведения см. в разделе «Описания адресов» .
  • fulfillOnZeroResults — Выполнить обещание при статусе ZERO_RESULT в ответе. Это может быть необходимо, поскольку даже при нулевых результатах геокодирования могут быть возвращены дополнительные поля уровня ответа. Подробнее см. в разделе «Выполнение при нулевых результатах» .

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

Сервису геокодирования требуется метод обратного вызова, который будет выполняться после получения результатов геокодирования. Этот метод обратного вызова должен передавать два параметра: results и код status , в указанном порядке.

Результаты геокодирования

Объект GeocoderResult представляет собой один результат геокодирования. Запрос на геокодирование может возвращать несколько объектов результатов:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Ниже приведено описание этих полей:

  • массив types[] указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, определяющих тип объекта, возвращаемого в результате. Например, геокод "Чикаго" возвращает "местность", что указывает на то, что "Чикаго" — это город, а также возвращает "политический", что указывает на то, что это политическое образование. Дополнительную информацию о типах адресов и типах компонентов адресов см. ниже.
  • formatted_address — это строка, содержащая удобочитаемый адрес данного местоположения.

    Часто этот адрес совпадает с почтовым адресом. Следует отметить, что в некоторых странах, например, в Великобритании, распространение настоящих почтовых адресов запрещено из-за ограничений, связанных с лицензированием.

    Отформатированный адрес логически состоит из одного или нескольких компонентов . Например, адрес «111 8th Avenue, New York, NY» состоит из следующих компонентов: «111» (номер дома), «8th Avenue» (маршрут), «New York» (город) и «NY» (штат США).

    Не следует программно обрабатывать отформатированный адрес. Вместо этого следует использовать отдельные компоненты адреса, которые, помимо поля отформатированного адреса, содержатся в ответе API.

  • address_components[] — это массив, содержащий отдельные компоненты, применимые к данному адресу.

    Каждый компонент адреса обычно содержит следующие поля:

    • массив types[] указывает тип компонента адреса. См. список поддерживаемых типов .
    • long_name — это полное текстовое описание или название компонента адреса, возвращаемое геокодером.
    • short_name — это сокращенное текстовое название компонента адреса, если таковое имеется. Например, компонент адреса для штата Аляска может иметь long_name как "Alaska" и short_name как "AK", используя двухбуквенное почтовое сокращение.

    Обратите внимание на следующие факты о массиве address_components[] :

    • Массив компонентов адреса может содержать больше компонентов, чем formatted_address .
    • Массив не обязательно включает все политические образования, содержащие адрес, за исключением тех, которые указаны в formatted_address . Чтобы получить все политические образования, содержащие конкретный адрес, следует использовать обратное геокодирование, передав широту/долготу адреса в качестве параметра запроса.
    • Формат ответа не гарантирует сохранения неизменности между запросами. В частности, количество address_components варьируется в зависимости от запрошенного адреса и может меняться со временем для одного и того же адреса. Компонент может изменить свою позицию в массиве. Тип компонента может измениться. Конкретный компонент может отсутствовать в последующем ответе.

    Более подробная информация о типах адресов и типах компонентов адресов приведена ниже.

  • partial_match указывает на то, что геокодер не вернул точное совпадение с исходным запросом, хотя и смог сопоставить часть запрошенного адреса. Возможно, вам стоит проверить исходный запрос на наличие орфографических ошибок и/или неполного адреса.

    Частичные совпадения чаще всего встречаются для адресов улиц, которых нет в указанном вами населенном пункте. Частичные совпадения также могут быть получены, когда запрос соответствует двум или более местоположениям в одном и том же населенном пункте. Например, запрос "Hillpar St, Bristol, UK" вернет частичное совпадение как для Henry Street, так и для Henrietta Street. Обратите внимание, что если запрос содержит орфографическую ошибку в адресе, служба геокодирования может предложить альтернативный адрес. Предложения, срабатывающие таким образом, также будут помечены как частичное совпадение.

  • place_id — это уникальный идентификатор места, который можно использовать с другими API Google. Например, вы можете использовать place_id с библиотекой Google Places API , чтобы получить подробную информацию о местном предприятии, такую ​​как номер телефона, часы работы, отзывы пользователей и многое другое. См. обзор идентификаторов мест .
  • массив postcode_localities[] содержит все населенные пункты, входящие в почтовый индекс, и присутствует только в том случае, если результат представляет собой почтовый индекс, содержащий несколько населенных пунктов.

  • geometry содержат следующую информацию:

    • location содержит геокодированные значения широты и долготы. Обратите внимание, что мы возвращаем это местоположение в виде объекта LatLng , а не в виде отформатированной строки.
    • location_type хранит дополнительные данные об указанном местоположении. Поддерживаются следующие значения:
      • ROOFTOP указывает, что полученный результат отражает точный геокод.
      • RANGE_INTERPOLATED указывает, что возвращаемый результат представляет собой приближение (обычно на дороге), интерполированное между двумя точными точками (например, перекрестками). Интерполированные результаты обычно возвращаются, когда геокоды крыш для адреса улицы недоступны.
      • GEOMETRIC_CENTER указывает, что возвращаемый результат представляет собой геометрический центр объекта, такого как полилиния (например, улица) или многоугольник (регион).
      • APPROXIMATE указывает на то, что возвращаемый результат является приблизительным.

    • viewport сохраняет рекомендуемый размер области просмотра для возвращаемого результата.
    • bounds (возвращается опционально) хранит координаты LatLngBounds , которые могут полностью вместить возвращаемый результат. Обратите внимание, что эти границы могут не соответствовать рекомендуемому размеру области просмотра. (Например, Сан-Франциско включает в себя Фараллонские острова , которые технически являются частью города, но не должны отображаться в области просмотра.)

Адреса возвращаются геокодером с использованием предпочтительного языка браузера или языка, указанного при загрузке JavaScript API с помощью параметра language . (Дополнительную информацию см. в разделе «Локализация». )

Типы адресов и типы компонентов адресов

Массив types[] в объекте GeocoderResult в ответе указывает тип адреса . Примеры типов адресов включают адрес улицы, страну или административно-территориальную единицу. Массив types в объекте GeocoderAddressComponent указывает тип каждой части адреса. Примеры включают номер дома или страну.

Адреса могут иметь несколько типов. Эти типы можно рассматривать как «теги». Например, многие города помечены тегами political и locality типов.

Поддерживаются и возвращаются следующие типы данных как в массивах типов адресов, так и в массивах типов компонентов адресов:

Тип адреса Описание
street_address Точный адрес улицы.
route Названный маршрут (например, "US 101").
intersection Крупный перекресток, как правило, двух крупных дорог.
political Политическое образование. Обычно этот тип обозначает многоугольник какой-либо гражданской администрации.
country Национальное политическое образование, как правило, являющееся типом наивысшего порядка, возвращаемым геокодером.
administrative_area_level_1 Административный уровень первого порядка ниже уровня страны. В Соединенных Штатах такими уровнями являются штаты. Не все страны имеют такие административные уровни. В большинстве случаев короткие названия administrative_area_level_1 будут точно соответствовать подразделениям ISO 3166-2 и другим широко распространенным спискам; однако это не гарантируется, поскольку наши результаты геокодирования основаны на различных сигналах и данных о местоположении.
administrative_area_level_2 Гражданское образование второго порядка, находящееся ниже уровня страны. В Соединенных Штатах этим административным уровнем являются округа. Не во всех странах существуют такие административные уровни.
administrative_area_level_3 Гражданское образование третьего порядка, находящееся ниже уровня страны. Этот тип указывает на незначительное административное подразделение. Не все страны имеют такие административные уровни.
administrative_area_level_4 Гражданское образование четвертого порядка, находящееся ниже уровня страны. Этот тип указывает на незначительное административное подразделение. Не все страны имеют такие административные уровни.
administrative_area_level_5 Гражданское образование пятого порядка, находящееся ниже уровня страны. Этот тип указывает на незначительное административное подразделение. Не все страны имеют такие административные уровни.
administrative_area_level_6 Гражданское образование шестого порядка, находящееся ниже уровня страны. Этот тип указывает на незначительное административное подразделение. Не все страны имеют такие административные уровни.
administrative_area_level_7 Гражданское образование седьмого порядка, находящееся ниже уровня страны. Этот тип указывает на незначительное административное подразделение. Не все страны имеют такие административные уровни.
colloquial_area Распространенное альтернативное название для данной сущности.
locality Городское или поселковое политическое образование, имеющее статус муниципалитета.
sublocality Гражданская единица первого порядка ниже населенного пункта. Для некоторых населенных пунктов может быть добавлен один из следующих типов: sublocality_level_1 — sublocality_level_5 . Каждый уровень субнаселенного пункта представляет собой гражданскую единицу. Большие числа указывают на меньшую географическую область.
neighborhood Названный район.
premise Названное место, обычно здание или комплекс зданий, имеющие общепринятое название.
subpremise Объект, на который можно ссылаться, расположенный ниже уровня основного здания, например, квартира, блок или апартаменты.
plus_code Кодированная координата местоположения, полученная на основе широты и долготы. Плюс-коды могут использоваться вместо уличных адресов в местах, где они отсутствуют (где здания не нумеруются или улицы не имеют названий). Подробнее см. https://plus.codes .
postal_code Почтовый индекс, используемый для адресации почтовых отправлений внутри страны.
natural_feature Выдающаяся природная особенность.
airport Аэропорт.
park Парк, имеющий своё название.
point_of_interest Названная достопримечательность. Как правило, это известные местные объекты, которые сложно отнести к какой-либо другой категории, например, «Эмпайр-стейт-билдинг» или «Эйфелева башня».

Пустой список типов указывает на то, что для данного компонента адреса не существует известных типов (например, Lieu-dit во Франции).

Помимо вышеперечисленного, в состав адресных компонентов могут входить следующие типы.

Примечание: Этот список не является исчерпывающим и может изменяться.

Помимо вышеперечисленного, в состав адресных компонентов могут входить следующие типы.

Тип компонента адреса Описание
floor Адрес этажа здания.
establishment Как правило, это место, которое еще не классифицировано.
landmark Ближайшее место, используемое в качестве ориентира для навигации.
point_of_interest Названная достопримечательность.
parking Парковка или многоуровневая парковка.
post_box Конкретный почтовый ящик.
postal_town Группа географических областей, таких как locality и sublocality , используемая для почтовых адресов в некоторых странах.
room Адрес помещения в здании.
street_number Точный номер дома.
bus_station , train_station и transit_station Местоположение остановки автобуса, поезда или другого общественного транспорта.

Коды состояния

Код status может возвращать одно из следующих значений:

  • "OK" означает, что ошибок не произошло; адрес был успешно обработан, и был возвращен как минимум один геокод.
  • Значение "ZERO_RESULTS" указывает на то, что геокодирование прошло успешно, но не дало результатов. Это может произойти, если геокодеру был передан несуществующий address .
  • "OVER_QUERY_LIMIT" означает, что вы превысили свою квоту.
  • "REQUEST_DENIED" означает, что ваш запрос был отклонен. Веб-страница не имеет права использовать геокодер.
  • "INVALID_REQUEST" обычно указывает на отсутствие запроса ( address , components или latlng ).
  • "UNKNOWN_ERROR" указывает на то, что запрос не удалось обработать из-за ошибки сервера. Возможно, запрос будет успешно выполнен, если вы попробуете еще раз.
  • "ERROR" означает, что запрос истек по времени или возникла проблема со связью с серверами Google. Запрос может быть успешно выполнен, если вы повторите попытку.

В этом примере мы определяем географические координаты адреса и устанавливаем маркер в точке, соответствующей полученным значениям широты и долготы. Обратите внимание, что обработчик передается в виде анонимного функционального литерала.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Посмотреть пример.

Смещение области просмотра

Вы можете указать службе геокодирования отдавать предпочтение результатам в пределах заданной области видимости (выраженной в виде ограничивающего прямоугольника). Для этого установите параметр bounds в литерале объекта GeocoderRequest , чтобы определить границы этой области видимости. Обратите внимание, что предпочтение отдается только результатам в пределах этих границ; если за пределами этих границ существуют более релевантные результаты, они могут быть включены.

Например, при вводе геокода для "Уиннетка" обычно возвращается следующий пригород Чикаго:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Однако, если указать параметр bounds , определяющий ограничивающий прямоугольник для долины Сан-Фернандо в Лос-Анджелесе, то этот геокод вернет район с названием "Winnetka" в этом месте:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Смещение регионального кода

Вы можете настроить службу геокодирования таким образом, чтобы она возвращала результаты, смещенные в сторону определенного региона, используя параметр region . Этот параметр принимает код региона, указанный в виде двухсимвольного (нечислового) субтега региона Unicode. Эти теги напрямую соответствуют привычным двухсимвольным значениям ccTLD («домен верхнего уровня»), таким как, например, «uk» в «co.uk». В некоторых случаях тег region также поддерживает коды ISO-3166-1, которые иногда отличаются от значений ccTLD («GB» для «Великобритании», например).

При использовании параметра region :

  • Укажите только одну страну или регион. Множественные значения игнорируются и могут привести к неудачному запросу.
  • Используйте только двухсимвольные подтеги регионов (формат Unicode CLDR). Все остальные варианты ввода приведут к ошибкам.
  • Поддерживаются только страны и регионы, указанные в разделе «Подробная информация о покрытии платформы Google Maps» .

Запросы на геокодирование можно отправлять для любого домена, в котором основное приложение Google Maps поддерживает геокодирование. Обратите внимание, что предпочтение отдается результатам только для определенного домена; если существуют более релевантные результаты за пределами этого домена, они могут быть включены в запрос.

Например, при геокодировании "Толедо" результат будет таким, поскольку домен по умолчанию для службы геокодирования установлен на Соединенные Штаты:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

При вводе геокода для "Толедо" с указанием region в поле 'es' (Испания) будет возвращен испанский город:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Фильтрация компонентов

Вы можете настроить службу геокодирования таким образом, чтобы она возвращала результаты поиска адресов, ограниченные определенной областью, используя фильтр компонентов. Укажите фильтр в параметре componentRestrictions . Значения фильтра поддерживают те же методы исправления орфографии и частичного сопоставления, что и другие запросы геокодирования.

Геокодер возвращает только те результаты, которые соответствуют всем компонентам фильтров. То есть, он оценивает спецификации фильтров как операцию И, а не ИЛИ.

Фильтр компонентов состоит из одного или нескольких следующих элементов:

  • Название route соответствует полному или сокращенному названию маршрута.
  • Сопоставление locality с типами местоположения и сублокальности.
  • administrativeArea соответствует всем уровням административной зоны.
  • postalCode сопоставляет почтовые индексы и префиксы почтовых индексов.
  • country соответствует названию страны или двухбуквенному коду страны ISO 3166-1 . Примечание: API соответствует стандарту ISO для определения стран, и фильтрация работает лучше всего при использовании соответствующего кода страны по стандарту ISO.

В следующем примере показано, как использовать параметр componentRestrictions для фильтрации по country и postalCode :

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Выполнение безрезультатно

При обратном геокодировании по умолчанию промис нарушается при status=ZERO_RESULTS . Однако дополнительные поля уровня ответа plus_code и address_descriptor могут быть заполнены и в этом случае. Если для параметра fulfillOnZeroResults указано значение true, поля заполняются в этом случае. Если для параметра fulfillOnZeroResults указано значение true, промис не нарушается, и эти дополнительные поля доступны из промиса, если они присутствуют.

Ниже приведён пример такого поведения для широты/долготы в Антарктиде. Даже если результаты обратного геокодирования отсутствуют, мы всё равно можем вывести код плюса в промисе, если установим fulfillOnZeroResults=true .

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Описание адреса

В описаниях адресов содержится дополнительная информация, помогающая описать местоположение с помощью ориентиров и районов. Посмотрите демонстрацию описаний адресов, чтобы ознакомиться с этой функцией.

Описание адресов можно включить с помощью параметра extraComputations . Чтобы получить описание адресов в ответе, добавьте extra_computations=ADDRESS_DESCRIPTORS в запрос геокодирования , запрос обратного геокодирования или запрос геокодирования мест .

Пример геокодирования мест

Следующий запрос содержит адрес места в Дели. 

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Пример обратного геокодирования

Следующий запрос содержит значения широты и долготы для местоположения в Дели. 

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

Пример описания адреса

Примером address_descriptor может служить следующий документ. 

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

В каждом объекте address_descriptor содержатся два массива: landmarks и areas . Массив landmarks содержит до 5 результатов, ранжированных по степени релевантности с учетом близости к запрошенной координате, распространенности ориентира и его видимости. Каждый результат, относящийся к ориентиру, содержит следующие значения:

  • place_id — это идентификатор места в результатах поиска достопримечательностей. См. обзор идентификаторов мест .
  • display_name — это отображаемое имя достопримечательности, содержащее language_code и text .
  • straight_line_distance_meters — это расстояние в метрах между входными координатами и полученными ориентирами.
  • travel_distance_meters — это расстояние в метрах, пройденное по дорожной сети (без учета ограничений движения) между входными координатами и результатом определения ориентиров.
  • spatial_relationship — это предполагаемая взаимосвязь между входными координатами и результатом определения ориентиров:
    • "NEAR" — это отношение по умолчанию, когда ни одно из следующих условий не выполняется.
    • "WITHIN" когда входная координата находится в пределах границ структуры, связанной с опорным ориентиром.
    • "BESIDE" это когда входные координаты находятся непосредственно рядом с ориентиром или точкой доступа к ориентиру.
    • "ACROSS_THE_ROAD" это когда входные координаты находятся прямо напротив ориентира на другой стороне маршрута.
    • "DOWN_THE_ROAD" когда входные координаты находятся вдоль того же маршрута, что и ориентир, но не "BESIDES" или "ACROSS_THE_ROAD" .
    • "AROUND_THE_CORNER" , когда в качестве ориентира используется перпендикулярная траектория маршрута (ограничено одним поворотом).
    • "BEHIND" это когда входная координата пространственно близка к ориентиру, но находится далеко от точки доступа.
  • types — это типы мест, относящиеся к достопримечательности.

Объект areas содержит до 3 ответов и ограничивается местами, представляющими небольшие регионы, такие как районы, микрорайоны и крупные комплексы. Области, содержащие запрошенные координаты, перечислены первыми и упорядочены от наименьшей к наибольшей. Каждый результат areas содержит следующие значения:

  • place_id — это идентификатор места в результатах поиска по областям. См. обзор идентификаторов мест .
  • display_name — это отображаемое имя области, содержащее language_code и text .
  • containment это оценочное соотношение ограничения между входной координатой и результатом определения площади:
    • "NEAR" — это отношение по умолчанию, когда ни одно из следующих условий не выполняется.
    • "WITHIN" когда входная координата находится близко к центру области.
    • "OUTSKIRTS" , когда входная координата находится близко к краю области.

Покрытие дескрипторов адресов

В Индии в общий доступ включены описания адресов. Использование описаний адресов в Индии не влечет за собой дополнительных затрат и покрывается существующим пакетом услуг Geocoding (India) Essentials .

Обратная связь

Эта функция доступна во всех регионах. В Индии она находится на стадии общего запуска, а во всех остальных регионах — на стадии экспериментального запуска (предварительная версия). Будем благодарны за ваши отзывы.

Обратное геокодирование (поиск адреса)

Термин «геокодирование» обычно относится к преобразованию удобочитаемого адреса в местоположение на карте. Процесс обратного преобразования, то есть преобразования местоположения на карте в удобочитаемый адрес, известен как обратное геокодирование .

Вместо текстового address укажите в параметре location пару координат (широта/долгота), разделенных запятыми.

В следующем примере выполняется геокодирование значений широты и долготы, карта центрируется в этой точке, после чего открывается информационное окно с отформатированным адресом:

Машинопись 

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infowindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                infowindow.setContent(response.results[0].formatted_address);
                infowindow.open(map, marker);
            } else {
                window.alert('No results found');
            }
        })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}

initMap();
index.ts

JavaScript 

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async function geocodeLatLng(geocoder, map, infowindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infowindow.setContent(response.results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert('No results found');
        }
    })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}
initMap();
index.js
Посмотреть пример

Попробуйте образец

Обратите внимание, что в предыдущем примере мы показали первый результат, выбрав results[0] . Обратный геокодер часто возвращает более одного результата. Геокодированные адреса — это не только почтовые адреса, но и любой способ географического обозначения местоположения. Например, при геокодировании точки в городе Чикаго, геокодированная точка может быть обозначена как адрес улицы, как город (Чикаго), как штат (Иллинойс) или как страна (Соединенные Штаты). Все это — адреса для геокодера. Обратный геокодер возвращает все эти результаты.

Обратный геокодер сопоставляет политические образования (страны, провинции, города и районы), адреса улиц и почтовые индексы.

Вот пример списка адресов, которые может вернуть приведенный выше запрос: 

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Адреса возвращаются в порядке от наилучшего к наихудшему совпадению. Как правило, наиболее точный адрес является наиболее заметным результатом, как и в данном случае. Обратите внимание, что мы возвращаем адреса разных типов, от наиболее точных адресов улиц до менее точных политических образований, таких как районы, города, округа, штаты и т. д. Если вы хотите найти более общий адрес, вы можете обратиться к полю results[].types .

Примечание: Обратное геокодирование — это не точная наука. Геокодер попытается найти ближайшее доступное местоположение с определенной погрешностью.

Получение адреса по идентификатору места

Укажите placeId , чтобы найти адрес для заданного идентификатора места. PlaceId — это уникальный идентификатор, который можно использовать с другими API Google. Например, вы можете указать placeId возвращаемый API дорог , чтобы получить адрес для точки привязки. Для получения дополнительной информации об идентификаторах мест см. обзор идентификаторов мест .

При указании placeId запрос не может содержать ни одного из следующих полей:

  • address
  • latLng
  • location
  • componentRestrictions

В следующем примере программа принимает идентификатор места, находит соответствующий адрес и центрирует карту в этом месте. Также отображается информационное окно с отформатированным адресом соответствующего места:

Машинопись 

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript 

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js
Посмотреть пример

Попробуйте образец