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

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

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

Переход с v3 Forward Geocoding

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

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

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

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

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

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

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

В следующей таблице показано наилучшее соответствие между фильтрами components версии 3 и полями postalAddress версии 4:

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

Следующие примеры показывают, как фильтровать результаты для достижения поведения, аналогичного фильтрации компонента v3, для поддерживаемых полей: страна, административный район и почтовый индекс. Фильтрация по другим полям не рекомендуется, поскольку надежных критериев фильтрации не существует.

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

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

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')

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, не является частью стандартного представления почтовых адресов. Например, в Испании административный район уровня 1 (например, «CN» для Канарских островов) может присутствовать в addressComponents , но postalAddress.administrativeArea может содержать район уровня 2 (например, «Санта-Крус-де-Тенерифе»). Во-вторых, в некоторых районах аббревиатура подразделения используется нечасто, и в postalAddress.administrativeArea она представлена ​​более длинным именем (по аналогичным причинам addressComponents.shortText для компонента адреса, соответствующего подразделению, может не соответствовать суффиксу кода подразделения ISO 3166-2). Кроме того, в некоторых случаях подразделение может быть представлено в компоненте адреса для administrative_area_level_n со значением n больше 1. Для получения наиболее полных результатов следует проверить совпадение как в postalAddress.administrativeArea , так и в любых addressComponents с типом administrative_area_level_n (например, administrative_area_level_1 ).

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')

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» в почтовых индексах США) может потребоваться более сложная нормализация. Конкретная необходимая логика нормализации будет варьироваться в зависимости от страны и форматов используемых почтовых индексов. Возможно, вам потребуется адаптировать предоставленные функции нормализации или реализовать более сложную логику для целевых регионов.

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

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')

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 обратного геокодирования

Если вы используете функцию обратного геокодирования версии 3 для преобразования координат в адреса, вам следует перейти на метод обратного геокодирования местоположения версии 4, который принимает GET-запрос.

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

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

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

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

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

Перенос с версии 3. Размещение геокодирования.

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

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

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

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

Переход от геокодирования гиперлокальных данных к геолокационным данным о местоположении.

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

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

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

Входы

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

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

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

Навигационные точки

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

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

• displayName — это новое необязательное поле, которое будет содержать удобочитаемое имя для точки навигации, например, "5th Ave".
• location — это местоположение типа LatLng , которое отличается от формата, используемого в API геокодирования версии 3.
• travelModes — это поле аналогично полю restrictedTravelModes в точках навигации из API геокодирования версии 3. Возможные значения перечисления те же, единственное отличие заключается в том, что теперь это поле представляет собой допустимые способы передвижения для точки навигации, а не запрещенные способы передвижения.
• usage — это новое поле, содержащее варианты использования, поддерживаемые точкой навигации. Обратите внимание, что для большинства точек навигации будет указано «Использование UNKNOWN , но это не обязательно означает, что использование точки навигации каким-либо образом ограничено.

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

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

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

• destination.primary - это основное местоположение для пункта назначения.
• destination.containingPlaces — это повторяющееся поле, которое может содержать более крупные объекты, «содержащие» основное место. Например, если основное место является subpremise , containingPlaces обычно будет содержать placeView , представляющий здание.
• destination.subDestinations — это повторяющееся поле, которое может содержать подпункты основного места. Например, отдельные квартиры в здании. Обычно это поле не содержит placeView , представляющего здание.

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

Территория

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

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

• destination.primary
• destination.containingPlaces
• destination.subDestinations

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

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

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

В API Destinations (версия 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

Вопросы безопасности

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

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

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

Рекомендуемый способ использования API геокодирования v4 — с вашего собственного бэкэнд-сервера. Ваше клиентское приложение должно отправлять запросы на этот промежуточный сервер, который затем безопасно вызывает API Google, используя защищенный ключ API (например, ключ, хранящийся в переменной окружения или менеджере секретов). Это гарантирует, что ваш ключ API никогда не будет раскрыт во фронтенд-коде.

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

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

• Сервис геокодирования в JavaScript API карт: Сервис геокодирования продолжает использовать бэкэнд версии 3 и предназначен для использования в браузерной среде.
• Набор элементов пользовательского интерфейса «Места»: используйте набор элементов пользовательского интерфейса «Места », включая элементы автозаполнения , для элементов пользовательского интерфейса, связанных с адресами.