Сервис Geocoding

Примечание. Серверные библиотеки.

На этой странице описывается клиентская служба, доступная с помощью Maps JavaScript API. Если вы хотите работать с веб-службами Google Maps на своем сервере, обратите внимание на клиент Node.js для служб Google Maps . На странице по этой ссылке также представлены клиент Java, клиент Python и клиент Go для служб Google Maps.

Обзор

Также см. Справочник по Maps JavaScript API: Геокодер.

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

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

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

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

Начиная

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

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

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

Ценообразование и политика

Цены

С 16 июля 2018 года вступил в силу новый тарифный план с оплатой по мере использования для Карт, Маршрутов и Мест. Чтобы узнать больше о новых ценах и ограничениях на использование службы геокодирования JavaScript, см. раздел «Использование и выставление счетов за API геокодирования».

Политика

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

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

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

Вы получаете доступ к службе геокодирования 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 — код региона, указанный в виде двухсимвольного (нечислового) вложенного тега региона Юникода. В большинстве случаев эти теги напрямую соответствуют знакомым двухсимвольным значениям ccTLD («домен верхнего уровня»). Параметр region будет влиять только на результаты геокодирования, но не ограничивать их полностью. Дополнительную информацию о смещении кода региона см. ниже.
• extraComputations — единственное допустимое значение для этого параметра — ADDRESS_DESCRIPTORS . Дополнительные сведения см. в дескрипторах адресов .
• fulfillOnZeroResults — выполнить обещание при статусе ZERO_RESULT в ответе. Это может быть желательно, поскольку даже при нулевых результатах геокодирования все равно могут быть возвращены дополнительные поля уровня ответа. Дополнительные сведения см. в разделе «Выполнение при нулевых результатах» .

Геокодирование ответов

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

Примечание . Ответ на геокодирование также содержит поля plus_code и address_descriptor на уровне ответа, но они недоступны через обратный вызов. Вместо этого к ним следует обращаться через обещание. Дополнительные сведения см. в разделе «Выполнение при нулевых результатах» .

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

Объект 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 «Аляска» и short_name «АК», используя двухбуквенное почтовое сокращение.

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

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

  Дополнительную информацию о типах адресов и типах компонентов адреса см. ниже.

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

  Частичные совпадения чаще всего встречаются для адресов, которые не существуют в населенном пункте, который вы передаете в запросе. Частичные совпадения также могут быть возвращены, когда запрос соответствует двум или более местоположениям в одном и том же месте. Например, «Хиллпар-стрит, Бристоль, Великобритания» вернет частичное совпадение как для улицы Генри, так и для улицы Генриетты. Обратите внимание: если запрос содержит компонент адреса с ошибкой, служба геокодирования может предложить альтернативный адрес. Предложения, созданные таким образом, также будут помечены как частичное совпадение.

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

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

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

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

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

Массив types[] в GeocoderResult указывает тип адреса . Массив types[] также может быть возвращен внутри GeocoderAddressComponent, чтобы указать тип конкретного компонента адреса. Адреса, возвращаемые геокодером, могут иметь несколько типов; типы можно считать тегами. Например, многие города отмечены тегами political и типа locality .

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

• street_address указывает точный адрес.
• route указывает именованный маршрут (например, «US 101»).
• intersection указывает на крупный перекресток, обычно двух основных дорог.
• political указывает на политическую сущность. Обычно этот тип обозначает полигон какой-либо гражданской администрации.
• country указывает национальное политическое образование и обычно является типом высшего порядка, возвращаемым геокодером.
• administrative_area_level_1 указывает гражданское лицо первого порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются штаты. Не все страны демонстрируют эти административные уровни. В большинстве случаев короткие названия административной_области_уровня_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 указывает на именованную достопримечательность. Как правило, эти «POI» представляют собой известные местные объекты, которые нелегко вписать в другую категорию, например «Эмпайр-Стейт-Билдинг» или «Эйфелева башня».

Пустой список типов указывает на отсутствие известных типов для конкретного компонента адреса, например 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 , определяющего ограничивающую рамку для долины Сан-Фернандо в Лос-Анджелесе, приводит к тому, что этот геокод возвращает район с именем «Виннетка» в этом месте:

{
  "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 . Этот параметр принимает код региона, указанный в виде двухсимвольного (нечислового) вложенного тега региона Юникода. Эти теги напрямую соответствуют знакомым двухсимвольным значениям 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 .

    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({ 
    '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 содержит до трех ответов и ограничивается местами, которые представляют небольшие регионы, такие как кварталы, микрорайоны и крупные комплексы. Области, содержащие запрошенную координату, перечислены первыми и упорядочены от меньшего к большему. Результат каждой areas содержит следующие значения:

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

Охват дескриптора адреса

Эта функция доступна только в некоторых странах .

Это функция предварительной версии, и мы будем признательны за отзывы. Напишите нам по адресу адрес-дескрипторы[e-mail] .

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

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

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

Примечание. Если вы включаете в запрос параметр componentRestrictions , параметр location игнорируется.

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

Машинопись

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

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

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

Примечание. Прочтите руководство по использованию TypeScript и Google Maps.

JavaScript

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

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

window.initMap = initMap;
index.js

Примечание. JavaScript скомпилирован из фрагмента TypeScript.

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

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

JSFiddle.net Google Cloud Shell

Обратите внимание, что в предыдущем примере мы показали первый результат, выбрав 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 Поле results[].types .

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

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

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

Когда вы указываете 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

Примечание. Прочтите руководство по использованию TypeScript и Google Maps.

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

Примечание. JavaScript скомпилирован из фрагмента TypeScript.

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

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

JSFiddle.net Google Cloud Shell