Для методов Geocoding API v4 по умолчанию установлено ограничение в 25 запросов в секунду (QPS). Информацию о запросе увеличения квоты см. в разделе «Просмотр и управление квотами» и выберите Geocoding API в качестве службы.

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

Переход с Geocoding API версии 3 на версию 4

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

В Geocoding API версии 4 добавлены новые методы, которые заменяют функции API версии 3. В этом руководстве рассказывается, как перейти на новые методы версии 4.

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

Переход с геокодирования версии 3

Если вы используете Geocoding v3 для геокодирования адресов, перейдите на метод Geocode an address версии 4, который принимает GET-запросы.

В API v4 изменены названия, структура и поддержка нескольких параметров. Мы настоятельно рекомендуем использовать маску поля, чтобы указать, какие поля должны возвращаться в ответе.

Изменения параметров запроса

Параметр v3	Параметр v4	Примечания
`address`, `components`	`address`	Неструктурированный адрес (v3 `address`) теперь передается в пути URL. Структурированные компоненты адреса (v3 `components`) можно передавать как параметры запроса `address.*`. Подробнее о том, как воспроизвести фильтры компонентов версии 3…
`bounds`	`locationBias.rectangle`	Переименовано; структура изменена на объект.
`language`	`languageCode`	Переименовано. Если параметр не указан, в версии 3 используется заголовок `Accept-Language` или значение по умолчанию `en`, а в версии 4 – язык и письменность, используемые в месте, где находится пользователь.
`region`	`regionCode`	Объект переименован. Если не указать значение, в версии 3 будет использоваться значение по умолчанию `us`, а в версии 4 – нет.
`extra_computations`	Удалено	Заменен методом SearchDestinations.

Изменения в поле ответа

Поле версии 3	Поле v4	Примечания
`status`, `error_message`	Удалено	В версии 4 используются коды статуса HTTP и тела ошибок.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Переименовано.
`results.geometry.location_type`	`results.granularity`	Объект переименован.
`results.geometry.location`	`results.location`	Названия полей: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Названия полей: `northeast`/`southwest` -> `high`/`low`.
`results.postcode_localities`	`results.postalCodeLocalities`	Объект переименован. Теперь возвращается для одного или нескольких населенных пунктов (требуется версия 3 и выше).
`results.partial_match`	Удалено
Новое	`results.addressComponents.languageCode`	Язык определенного компонента адреса.
Новое	`results.bounds`	Явные границы с использованием `high`/`low`.
Новое	`results.place`	Название ресурса для места.
Новое	`results.postalAddress`	Структурированный объект `PostalAddress`.

Воспроизвести фильтры компонентов версии 3

Прямое геокодирование в Geocoding v3 включало параметр components, который позволял выполнять жесткую фильтрацию результатов для определенных компонентов (например, components=country:US). Прямое геокодирование в v4 не поддерживает этот тип жесткой фильтрации в параметрах запроса. В версии 4 вы можете указать адрес в виде одной неструктурированной строки в пути или в виде структурированных параметров запроса, таких как address.addressLines, address.locality, address.administrativeArea, address.postalCode и address.regionCode. Структурированные параметры не действуют как жесткие фильтры. Вместо этого все предоставленные компоненты объединяются в полный адрес, который API попытается геокодировать. API ищет наиболее подходящий вариант для всего указанного адреса по всем компонентам. Предоставление компонентов в структурированном виде может помочь API лучше понять намерение, особенно когда информация об адресе собирается из отдельных полей формы. Это может помочь API обрабатывать незначительные опечатки или двусмысленности в каждом компоненте, поскольку тип информации в каждом поле ясен.

Чтобы добиться поведения, аналогичного жестким фильтрам компонентов версии 3, необходимо реализовать клиентскую фильтрацию для массива results, возвращаемого API версии 4, на основе объектов postalAddress и addressComponents в ответе.

В таблице ниже показано, какие фильтры версии 3 components соответствуют полям версии 4 postalAddress.

Фильтр компонентов версии 3	Поле ответа версии 4
`country`	`postalAddress.regionCode`
`postal_code`	`postalAddress.postalCode`
`administrative_area`	`postalAddress.administrativeArea` или `addressComponents`

Примеры клиентской фильтрации

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

Фильтр по стране

Сопоставьте address.regionCode из запроса с postalAddress.regionCode в каждом результате. Обратите внимание, что, хотя API принимает в запросах коды регионов в нижнем регистре, в ответах они всегда возвращаются в верхнем регистре, поэтому перед сравнением необходимо нормализовать входные данные, приведя их к верхнему регистру.

Пример кода на Python

def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')

Пример кода для Node.js

function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');

Как фильтровать по административному району

Сопоставьте address.administrativeArea из запроса с postalAddress.administrativeArea в каждом результате. Как и в случае с кодами стран, перед сравнением необходимо нормализовать входные данные, преобразовав их в верхний регистр. Это значение будет точным, только если в запросе administrativeArea указано стандартное двухбуквенное сокращение. Символ postalAddress.administrativeArea в ответе может не совпадать с суффиксами кодов ISO 3166-2 по нескольким причинам. Во-первых, в некоторых регионах административная единица, соответствующая коду ISO 3166-2, не является частью стандартного представления почтовых адресов. Например, в Испании административный район первого уровня (например, "CN" для Канарских островов) может быть указан в поле addressComponents, а в поле postalAddress.administrativeArea может содержаться район второго уровня (например, "Санта-Крус-де-Тенерифе"). Во-вторых, в некоторых регионах сокращение административной единицы не используется, и в postalAddress.administrativeArea она представлена более длинным названием. По аналогичным причинам addressComponents.shortText для компонента адреса, соответствующего административной единице, может не совпадать с суффиксом кода ISO 3166-2 административной единицы. Кроме того, в некоторых случаях подразделение может быть представлено в компоненте адреса для administrative_area_level_n, где n больше 1. Чтобы получить наиболее полные результаты, проверьте наличие совпадений в postalAddress.administrativeArea и любых addressComponents с типом administrative_area_level_n (например, administrative_area_level_1).

Пример кода на Python

def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')

Пример кода Node.js

function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');

Фильтр по почтовому индексу

Сопоставьте address.postalCode из запроса с postalAddress.postalCode в каждом результате. Перед сравнением необходимо нормализовать как исходные, так и полученные почтовые индексы. Логика нормализации сильно зависит от региона. Простейший подход заключается в удалении пробелов и дефисов и преобразовании в единый регистр.

Для обработки префиксов (например, "L2" в Великобритании) или суффиксов (например, "+4" в США) почтовых индексов может потребоваться более сложная нормализация. Логика нормализации зависит от страны и формата почтовых индексов. Возможно, вам потребуется адаптировать предоставленные функции нормализации или реализовать более сложную логику для регионов, на которые вы настраиваете таргетинг.

В приведенном примере используются почтовые индексы США и допускается сопоставление по пятизначному коду, даже если указан или возвращен индекс ZIP+4.

Пример кода на Python (для почтовых индексов США)

import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')

Пример кода Node.js (для почтовых индексов США)

function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

Переход с обратного геокодирования версии 3

Если вы используете обратное геокодирование v3 для преобразования координат в адреса, перейдите на метод обратного геокодирования v4, который принимает GET-запросы.

В API версии 4 изменены названия, структура и поддержка некоторых параметров. Мы настоятельно рекомендуем использовать маску полей, чтобы указать, какие поля должны возвращаться в ответе.

Изменения параметров запроса

Параметр v3	Параметр v4	Примечания
`language`	`languageCode`	Объект переименован. Если параметр не указан, в версии 3 используется заголовок `Accept-Language` или значение по умолчанию `en`, а в версии 4 – язык и письменность, используемые в месте, где находится пользователь.
`region`	`regionCode`	Переименовано. Если параметр опущен, в v3 по умолчанию используется `us`, а в v4 значения по умолчанию нет.
`result_type`	`types`	Переименован; использует повторяющиеся параметры запроса.
`location_type`	`granularity`	Переименовано; используются повторяющиеся параметры запроса.
`extra_computations`	Удалено	Заменен методом SearchDestinations.

Изменения в поле ответа

Поле версии 3	Поле v4	Примечания
`status`, `error_message`	Удалено	В версии 4 используются коды статуса HTTP и тела ошибок.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Переименовано.
`results.geometry.location_type`	`results.granularity`	Объект переименован.
`results.geometry.location`	`results.location`	Названия полей: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Названия полей: `northeast`/`southwest` -> `high`/`low`.
Новое	`results.addressComponents.languageCode`	Язык определенного компонента адреса.
Новое	`results.bounds`	Явные границы с использованием `high`/`low`.
Новое	`results.place`	Название ресурса для места.
Новое	`results.postalAddress`	Структурированный объект `PostalAddress`.

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

Если вы используете address_descriptor, чтобы получить дополнительную информацию о местоположении с помощью Geocoding v3, вам нужно перейти на поле landmarks в SearchDestinationsResponse.

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

Если вы используете place_id, чтобы получить адрес для определенного идентификатора места с помощью Geocoding v3, вам нужно перейти на метод Place Geocoding v4, который принимает GET-запрос.

В API версии 4 изменены названия, структура и поддержка некоторых параметров. Мы настоятельно рекомендуем использовать маску поля, чтобы указать, какие поля должны возвращаться в ответе.

Изменения параметров запроса

Параметр v3	Параметр v4	Примечания
`place_id`	Поле `place` в протоколе запроса	Теперь идентификатор места указывается в качестве параметра пути `places/{place}`, например `https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw`. Это поле соответствует полю place в основном запросе.
`language`	`languageCode`	Объект переименован. Если параметр не указан, в версии 3 используется заголовок `Accept-Language` или значение по умолчанию `en`, а в версии 4 – язык и письменность, используемые в месте, где находится пользователь.
`region`	`regionCode`	Объект переименован. Если не указать значение, в версии 3 будет использоваться значение по умолчанию `us`, а в версии 4 – нет.

Изменения в поле ответа

Поле версии 3	Поле v4	Примечания
`status`, `error_message`	Удалено	В версии 4 используются коды статуса HTTP и тела ошибок.
`results`	(root)	v4 возвращает один объект результата, а не массив `results`.
`results.address_components.long_name`/`results.address_components.short_name`	`addressComponents.longText`/`addressComponents.shortText`	Объект переименован.
`results.geometry.location_type`	`granularity`	Объект переименован.
`results.geometry.location`	`location`	Названия полей: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`viewport`	Названия полей: `northeast`/`southwest` -> `high`/`low`.
`results.postcode_localities`	`postalCodeLocalities`	Объект переименован. Теперь возвращается для одного или нескольких населенных пунктов (в версии 3 требовалось больше одного).
Новое	`addressComponents.languageCode`	Язык определенного компонента адреса.
Новое	`bounds`	Явные границы с использованием `high`/`low`.
Новое	`place`	Название ресурса для места.
Новое	`postalAddress`	Структурированный объект `PostalAddress`.

Переход с геокодирования гиперлокальных данных на конечные точки

Следующие функции Geocoding API версии 3 заменяются методом SearchDestinations Geocoding API версии 4:

Входы
Точки навигации
Контуры зданий
Территория

Если вы использовали Geocoding API версии 3 для указанных выше функций, используйте этот документ, чтобы перейти на метод SearchDestinations. В этом документе рассказывается, где в ответе SearchDestinations можно найти эти функции, а также о различиях в том, как эти функции представлены в ответах API между Geocoding API версии 3 и методом SearchDestinations Geocoding API версии 4.

Входы

Чтобы получить входы, связанные с destination, используйте поле destination.entrances.

Обратите внимание, что формат entrance немного отличается от формата входа в Geocoding API версии 3. Каждый вход в destination.entrances содержит следующие поля:

displayName – новое необязательное поле, в котором будет указано удобочитаемое название входа, например "Ворота Б".
location – это местоположение типа LatLng, которое отличается от формата, используемого в Geocoding API версии 3.
tags – то же самое, что и поле tags для входов из Geocoding API версии 3.
place – аналогично полю buildingPlaceId входов из Geocoding API версии 3. Однако идентификатор места в этом поле может относиться к месту любого типа, а не только к зданию.

Точки навигации

Чтобы получить точки навигации, связанные с destination, используйте поле destination.navigationPoints.

Обратите внимание, что формат navigationPoint немного отличается от формата точки навигации в Geocoding API версии 3. Каждая точка навигации в destination.navigationPoints имеет следующие поля:

displayName – новое необязательное поле, в котором будет указано понятное название точки навигации, например "5th Ave".
location – это местоположение типа LatLng, которое отличается от формата, используемого в Geocoding API версии 3.
travelModes – аналогично полю restrictedTravelModes точек навигации из Geocoding API версии 3. Возможные значения перечисления остались прежними. Единственное отличие в том, что теперь это поле представляет допустимые способы передвижения для точки навигации, а не запрещенные.
usage – новое поле, в котором перечислены сценарии использования, поддерживаемые точкой навигации.

Контуры зданий

Чтобы получить контуры зданий, связанные с объектом destination, используйте поле displayPolygon объектов placeView в объекте destination, представляющих здания. Для каждого объекта placeView можно проверить, является ли он зданием, с помощью поля placeView.structureType. Если тип структуры – BUILDING, вы можете получить контур из поля placeView.displayPolygon. В placeView также будут дополнительные поля для здания, которых не было в Geocoding API v3.

Примечание. Если вам нужно только найти многоугольник здания в определенном месте, Чтобы сузить результаты поиска, используйте в запросе параметр placeFilter. Чтобы в результатах поиска показывались только здания, задайте для параметра structureType значение "BUILDING" в placeFilter. Если для вас в приоритете получение многоугольника (даже для местоположений без точных адресов), задайте для параметра addressability значение "ANY" в placeFilter, чтобы получить наиболее точный доступный многоугольник.

Пример

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}

Объект destination может содержать объект placeView, представляющий здание, в следующих полях:

destination.primary – основное место для указания целевого URL.
destination.containingPlaces – повторяющееся поле, в котором могут быть указаны более крупные места, "содержащие" основное место. Например, если основное местоположение – subpremise, то в containingPlaces обычно будет указан placeView, представляющий здание.
destination.subDestinations – повторяющееся поле, которое может содержать дополнительные пункты назначения основного места. Например, отдельные квартиры в здании. Обычно в этом поле нет значения placeView, представляющего здание.

Обратите внимание, что формат placeView.displayPolygon соответствует формату контура здания в Geocoding API версии 3, который представляет собой формат GeoJSON, использующий формат RFC 7946.

Территория

Как и в случае с контурами зданий, чтобы получить территорию, связанную с объектом destination, используйте поле displayPolygon объектов placeView в объекте destination, представляющем территорию. Для каждого placeView можно проверить, является ли оно основанием, с помощью поля placeView.structureType. Если тип структуры – GROUNDS, то план можно получить из поля placeView.displayPolygon. В placeView также будут дополнительные поля для оснований, которых не было в Geocoding API версии 3.

Объект destination может содержать объект placeView, который представляет территорию в следующих полях:

destination.primary
destination.containingPlaces
destination.subDestinations

Обратите внимание, что формат placeView.displayPolygon соответствует формату контура территории в Geocoding API версии 3, который представляет собой формат GeoJSON, использующий формат RFC 7946.

Точность результатов

В Geocoding API v3 поле location_type в геометрии ответа указывало на точность результатов, и некоторые клиенты ранжировали или фильтровали результаты на основе этих значений (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER и APPROXIMATE). В стандартных переходах на Geocoding API v4 это поле переименовывается в granularity.

В Destinations API (версия 4 SearchDestinations) нет поля location_type. Пространственная информация обрабатывается иначе:

Не требуется ручная клиентская фильтрация: Стандартное геокодирование предоставляет несколько результатов с разной степенью детализации, а метод SearchDestinations позволяет избежать неоднозначности, по возможности определяя один оптимизированный пункт назначения. Это избавляет клиентов от необходимости фильтровать результаты по типу местоположения, чтобы определить, какой из них лучше.
Пространственная информация, представленная типом структуры и многоугольниками отображения. Пространственная геометрия и структура обозначаются следующим образом:
- displayPolygon (для точной геометрии).
- Поле structureType в объекте placeView.
Сопоставление типов структуры:
- structureType со значением POINT, BUILDING или SECTION обычно соответствует тому, что ранее называлось ROOFTOP.
- structureType из GROUNDS обычно соответствует GEOMETRIC_CENTER.

Как использовать маску полей для запроса этих функций

Для метода SearchDestinations требуется маска поля, как описано в разделе Выбор полей для возврата. Чтобы получить все поля, задайте маску *. Вы также можете указать только нужные поля. Например, следующий запрос к API задает маску поля, чтобы получить все поля, необходимые для получения входов, точек навигации, контуров зданий и территории пункта назначения:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

Безопасность

Geocoding API версии 4 предназначен для межсерверного взаимодействия. Для пользователей JavaScript нет прямого пути перехода с версии 3 на версию 4. Вызов методов v4 непосредственно из клиентского кода JavaScript (например, в браузере) с использованием ключа API подвергает этот ключ высокому риску кражи и неправомерного использования.

Ограничения по заголовку HTTP referer полезны, но недостаточны для защиты конечных точек веб-сервисов, поскольку злоумышленники могут легко обойти их, подделав заголовок Referer в своих запросах.

Альтернативные варианты для клиентской стороны

Если вам нужно геокодирование на стороне клиента, рассмотрите одно из существующих решений:

Сервис Geocoding в Maps JavaScript API. Сервис Geocoding по-прежнему использует серверную часть версии 3 и предназначен для использования в браузере.
Places UI Kit. Используйте Places UI Kit, включая элементы автозаполнения мест, для элементов пользовательского интерфейса, связанных с адресами.

Переход с Geocoding API версии 3 на версию 4 Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Переход с геокодирования версии 3

Изменения параметров запроса

Изменения в поле ответа

Воспроизвести фильтры компонентов версии 3

Примеры клиентской фильтрации

Фильтр по стране

Как фильтровать по административному району

Фильтр по почтовому индексу

Переход с обратного геокодирования версии 3

Изменения параметров запроса

Изменения в поле ответа

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

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

Изменения параметров запроса

Изменения в поле ответа

Переход с геокодирования гиперлокальных данных на конечные точки

Входы

Точки навигации

Контуры зданий

Территория

Точность результатов

Как использовать маску полей для запроса этих функций

Безопасность

Рекомендуемый подход

Альтернативные варианты для клиентской стороны

Переход с Geocoding API версии 3 на версию 4