Сервис Geocoding

Обзор

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

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

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

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

Начать

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

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

1. Перейдите в консоль Google Cloud.
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 на панели управления.

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

Цены

Узнать больше о ценах и правилах использования сервиса JavaScript Geocoding можно в статье Использование и выставление счетов для Geocoding API.

Правила

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

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

Доступ к сервису Geocoding осуществляется асинхронно, поскольку требуется отправить вызов на внешний сервер. По этой причине метод geocode возвращает объект Promise, который распознается по завершении запроса. После этого вы можете использовать .then() или await для обработки ответа.

Для доступа к сервису геокодирования 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 влияет на результаты работы геокодера, но не ограничивает их полностью. Подробнее о предпочитаемом коде региона…
• extraComputations – единственное допустимое значение для этого параметра – ADDRESS_DESCRIPTORS. Подробнее об описаниях адресов…
• fulfillOnZeroResults – выполнить обещание, если в ответе возвращается статус ZERO_RESULT. Это может быть полезно, поскольку даже при отсутствии результатов геокодирования могут возвращаться дополнительные поля на уровне ответа. Подробнее о выполнении запросов без результатов…

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

Сервису 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[] – массив, указывающий тип компонента адреса. Если для компонента адреса нет известных типов, массив типов может быть пустым. При необходимости в API могут быть добавлены новые значения типов. Подробнее о типах адресов и их компонентов…
  • 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.

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

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

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

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

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

Коды статуса

Код status может возвратить одно из указанных ниже значений.

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

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

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

async function geocode(request: google.maps.GeocoderRequest) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.ts

async function geocode(request) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.js

Посмотреть полный пример

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

Вы можете указать, чтобы сервис геокодирования в первую очередь выводил результаты в указанной области просмотра (выраженной граничной рамкой). Для этого внутри литерала объекта 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. Этот параметр принимает код региона, указанный как вложенный тег region в формате Unicode из двух символов (не цифр). Эти теги напрямую соответствуют известным двухсимвольным значениям национального домена верхнего уровня, например "uk" в "co.uk". В некоторых случаях тег region также поддерживает коды ISO-3166-1, которые иногда отличаются от значений ccTLD (например, "GB" – "Великобритания").

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

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

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

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

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

async function codeAddress(request: google.maps.GeocoderRequest) {
    clear();
    geocoder.geocode({
        componentRestrictions: {
            country: 'AU',
            postalCode: '2000'
        }
    })
    .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        let marker = new google.maps.marker.AdvancedMarkerElement({
            map: innerMap,
            position: results[0].geometry.location
        });
    })
    .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
};

Выполнение при нулевом количестве результатов

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

• 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", если входная координата находится близко к краю области.

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

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

Как оставить отзыв

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

• Если у вас возникли проблемы, связанные с Индией, обратитесь в службу поддержки.
• Если вы хотите оставить отзыв об экспериментальной версии, напишите нам на адрес address-descriptors-feedback@google.com.
• Подробнее о доступности описаний адресов…

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

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

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

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

let marker: google.maps.marker.AdvancedMarkerElement;

async function init() {
    //  Request the needed libraries.
    const [{ 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') as HTMLInputElement;

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

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

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

    marker.anchorTop = '40px';

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

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

    // Add a click event listener to the map.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void 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]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.ts

let marker;

async function init() {
    //  Request the needed libraries.
    const [{ 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,
        mapTypeControl: false,
    });

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

    marker.anchorTop = '40px';

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

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

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

    // Make an initial request upon loading.
    void 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]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.js

/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
gmp-map {
    height: 100%;
}

/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Roboto, sans-serif;
}

#floating-panel {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 10px;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
}

#latlng {
    width: 100%;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
    margin-bottom: 4px;
}

#submit {
    font-size: 1rem;
}
style.css

<html>
    <head>
        <title>Reverse Geocoding</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
            <div id="floating-panel" slot="control-block-start-inline-start">
                <p>
                    Click the map to reverse geocode, or add your own
                    coordinates.
                </p>
                <input
                    id="latlng"
                    type="text"
                    value="40.714224, -73.961452" /><br />
                <input id="submit" type="button" value="Reverse Geocode" />
            </div>
        </gmp-map>
    </body>
</html>
index.html

В предыдущем примере мы показали первый результат, выбрав параметр 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

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

// Initialize the map.
async function init(): Promise<void> {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit')!.addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const placeId = (document.getElementById('place-id') as HTMLInputElement)
        .value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

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

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

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.ts

// Initialize the map.
async function init() {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit').addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(geocoder, map, infoWindow) {
    const placeId = document.getElementById('place-id').value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

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

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

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.js