Сервис Geocoding

Обзор

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

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

Кроме того, геокодер можно использовать для поиска адреса, соответствующего заданному идентификатору места.

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

Начало работы

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

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

  1. Войдите в Google Cloud Console.
  2. Нажмите кнопку Select a project (Выбрать проект), затем выберите тот же проект, который вы установили для Maps JavaScript API, и нажмите Open (Открыть).
  3. В списке API на панели управления поищите Geocoding API.
  4. Если этот API есть в списке – все готово к работе. Если API в списке нет, включите его:
    1. Вверху страницы нажмите Enable API (Включить API), чтобы перейти на вкладку Library (Библиотека). Вы также можете выбрать в меню слева пункт Library (Библиотека).
    2. Введите поисковый запрос Geocoding API, а затем выберите API из списка результатов.
    3. Нажмите Enable (Включить). Когда процесс завершится, Geocoding API появится в списке API на панели управления.

Цены и правила

Цены

С 16 июля 2018 года действует новый тарифный план с оплатой по мере использования для API Maps, Routes и Places. Узнать больше о новых ценах и лимитах на использование сервиса JavaScript Geocoding можно в статье Статистика использования и оплата для Geocoding API.

Ограничения частоты запросов

Учитывайте описанные ниже ограничения по частоте дополнительных запросов.

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

Ограничение частоты запросов за один сеанс не позволяет использовать сервисы на стороне клиента для пакетных запросов, например для пакетного геокодирования. Для пакетных запросов используйте веб-сервис Geocoding API.

Правила

Сервис Geocoding нужно использовать в соответствии с правилами, описанными для Geocoding API.

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

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

Для доступа к сервису геокодирования 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 – код региона, указываемый как вложенный тег region в формате Unicode из двух символов (не цифр). В большинстве случаев эти теги напрямую соответствуют известным двухсимвольным значениям национального домена верхнего уровня. Параметр region влияет на результаты работы геокодера, но не ограничивает их полностью. Подробнее о предпочитаемом коде региона

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

Сервису Geocoding необходим метод обратного вызова для исполнения после получения результатов от геокодера. Обратный вызов должен передать два параметра для хранения результатов 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[] – это массив, указывающий тип адреса возвращаемого результата. Этот массив содержит набор из нескольких тегов (или ни одного), которые определяют тип возвращаемого элемента. Например, геокодирование для "Chicago" возвращает тег "locality", указывающий, что Чикаго является городом, а также тег "political", указывающий, что этот объект является также административной единицей. Подробнее о типах адресов и их компонентов
  • 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 указывает, что геокодер не вернул точное совпадение для исходного запроса, хотя и обнаружил частичное совпадение с запрашиваемым адресом. Рекомендуется проверить исходный запрос на наличие в нем опечаток и/или неполного адреса.

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

  • 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 указывает код местоположения на основе широты и долготы. Коды 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>

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

Предпочтение области просмотра

Вы можете указать, чтобы сервис Geocoding в первую очередь выводил результаты в указанной области просмотра (выраженной ограничивающим прямоугольником). Для этого внутри литерала объекта 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"
}

Предпочтение кода региона

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

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

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

Запросы на геокодирование можно отправлять для любого домена, в котором главное приложение Google Карт поддерживает геокодирование. Следует отметить, что этот параметр указывает только на предпочтение результатов, найденных в рамках определенных границ. Если за пределами этих границ обнаруживаются более релевантные результаты, они могут быть включены в результат.

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

{
  "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"
}

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

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

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

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

  • route – соответствие длинному или короткому названию маршрута.
  • locality – соответствие типам locality и sublocality.
  • 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);
  }
});
}

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

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

Вместо текстового значения address предоставьте в параметре location разделенные запятой значения широты и долготы.

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

TypeScript

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;

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;
Посмотреть пример

Примеры кода

В предыдущем примере мы показали первый результат, выбрав параметр 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, чтобы найти адрес заданного идентификатора места. Это уникальный идентификатор, который можно использовать и с другими интерфейсами Google API. Например, вы можете указать идентификатор placeId, возвращаемый Roads API, чтобы получить адрес фиксированной точки. Подробнее об идентификаторах мест

Если вы указываете placeId, запрос не должен содержать ни одного из следующих полей:

  • address
  • latLng
  • location
  • componentRestrictions

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

TypeScript

// 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;

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;
Посмотреть пример

Примеры кода