Migrer de Geocoding v3 vers v4

La version 4 de l'API Geocoding introduit plusieurs nouvelles méthodes qui remplacent les fonctionnalités de la version 3 de l'API. Ce guide vous explique comment migrer votre application pour utiliser les nouvelles méthodes v4.

Vous pouvez utiliser vos clés API existantes avec les nouvelles méthodes de la version 4. Toutefois, si vous avez demandé une augmentation du quota pour la version 3 de l'API, vous devez demander une augmentation pour les nouvelles API version 4.

Migrer depuis le geocoding direct v3

Si vous utilisez v3 Geocoding pour géocoder des adresses, vous devez migrer vers la méthode v4 Géocoder une adresse, qui accepte une requête GET.

L'API v4 modifie les noms, la structure et la prise en charge de plusieurs paramètres. Nous vous recommandons vivement d'utiliser un masque de champ pour spécifier les champs que vous souhaitez renvoyer dans la réponse.

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

Reproduire les filtres de composants v3

Le géocodage direct dans Geocoding v3 incluait un paramètre components qui permettait de filtrer de manière stricte les résultats pour des composants spécifiques (par exemple, components=country:US). Le géocodage direct dans v4 n'accepte pas ce type de filtrage strict dans les paramètres de la requête. Dans la v4, vous pouvez fournir des informations d'adresse sous la forme d'une seule chaîne non structurée dans le chemin d'accès ou de paramètres de requête structurés tels que address.addressLines, address.locality, address.administrativeArea, address.postalCode et address.regionCode. Les paramètres structurés ne fonctionnent pas comme des filtres stricts. Au lieu de cela, tous les composants fournis sont combinés pour former l'adresse complète que l'API tentera de géocoder. L'API recherche la meilleure correspondance pour l'adresse complète spécifiée dans tous les composants. Fournir des composants de manière structurée peut aider l'API à mieux comprendre l'intention, en particulier lorsque les informations d'adresse sont collectées à partir de champs de formulaire distincts. Cela peut aider l'API à gérer les fautes de frappe mineures ou les ambiguïtés dans chaque composant, car le type d'informations dans chaque champ est clair.

Pour obtenir un comportement semblable aux filtres de composants stricts de la version 3, vous devez implémenter un filtrage côté client sur le tableau results renvoyé par l'API v4 en fonction des objets postalAddress et addressComponents dans la réponse.

Le tableau suivant présente la meilleure correspondance entre les filtres components de la v3 et les champs postalAddress de la v4 :

Exemples de filtrage côté client

Les exemples suivants montrent comment filtrer les résultats pour obtenir un comportement semblable au filtrage des composants de la v3 pour les champs acceptés : pays, région administrative et code postal. Il n'est pas recommandé de filtrer sur d'autres champs, car il n'existe pas de critères de filtrage fiables.

Filtrer par pays

Faites correspondre le address.regionCode de votre requête avec le postalAddress.regionCode de chaque résultat. Notez que même si l'API accepte les codes de région en minuscules dans la requête, elle les renvoie toujours en majuscules dans la réponse. Vous devez donc normaliser votre entrée en majuscules avant de la comparer.

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

Filtrer par région administrative

Faites correspondre le address.administrativeArea de votre requête avec le postalAddress.administrativeArea de chaque résultat. Comme pour les codes pays, vous devez normaliser votre entrée en majuscules avant la comparaison. Cette méthode n'est fiable que lorsque le paramètre administrativeArea de votre requête est fourni avec une abréviation standard à deux lettres. Il est possible que les postalAddress.administrativeArea de la réponse ne correspondent pas directement aux suffixes des codes ISO 3166-2 pour plusieurs raisons. Tout d'abord, dans certaines régions, la subdivision correspondant au code ISO 3166-2 ne fait pas partie de la représentation standard des adresses postales. Par exemple, en Espagne, la région administrative de niveau 1 (par exemple, "CN" pour Canarias) peut être présente dans addressComponents, mais postalAddress.administrativeArea peut contenir la région administrative de niveau 2 (par exemple, "Santa Cruz de Tenerife"). Deuxièmement, dans certaines régions, l'abréviation de la subdivision n'est pas couramment utilisée et est représentée dans postalAddress.administrativeArea avec un nom plus long (pour des raisons similaires, addressComponents.shortText pour le composant d'adresse correspondant à la subdivision peut ne pas correspondre au suffixe du code ISO 3166-2 de la subdivision). De plus, la subdivision peut parfois être représentée au niveau du composant d'adresse pour administrative_area_level_n avec n supérieur à 1. Pour obtenir les résultats les plus complets, vous devez rechercher une correspondance dans postalAddress.administrativeArea et dans tous les addressComponents de type administrative_area_level_n (par exemple, 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');

Filtrer par code postal

Faites correspondre le address.postalCode de votre requête avec le postalAddress.postalCode de chaque résultat. Vous devez normaliser les codes postaux d'entrée et de résultat avant de les comparer. La logique de normalisation dépend fortement de la région. Une approche de base consiste à supprimer les espaces et les traits d'union, et à utiliser une casse cohérente.

Une normalisation plus avancée peut être nécessaire pour gérer les préfixes (par exemple, "L2" au Royaume-Uni) ou les suffixes (par exemple, "+4" dans les codes postaux américains). La logique de normalisation spécifique requise varie en fonction du pays et des formats des codes postaux concernés. Vous devrez peut-être adapter les fonctions de normalisation fournies ou implémenter une logique plus sophistiquée pour les régions que vous ciblez.

L'exemple fourni gère les codes postaux américains et permet de faire correspondre la base à cinq chiffres, même si le code ZIP+4 est fourni ou renvoyé.

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

Migrer depuis le geocoding inversé v3

Si vous utilisez le geocoding inversé v3 pour convertir des coordonnées en adresses, vous devez migrer vers la méthode v4 Geocoding inversé d'un lieu, qui accepte une requête GET.

L'API v4 modifie les noms, la structure et la compatibilité de plusieurs paramètres. Nous vous recommandons vivement d'utiliser un masque de champ pour spécifier les champs que vous souhaitez renvoyer dans la réponse.

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

Migrer depuis les descripteurs d'adresse v3

Si vous utilisez address_descriptor pour obtenir des informations supplémentaires sur un lieu avec Geocoding v3, vous devez migrer vers le champ landmarks de SearchDestinationsResponse.

Migrer depuis le géocodage Places v3

Si vous utilisez place_id pour obtenir l'adresse d'un ID de lieu spécifique avec Geocoding v3, vous devez migrer vers la méthode Place Geocoding de la version 4, qui accepte une requête GET.

L'API v4 modifie les noms, la structure et la prise en charge de plusieurs paramètres. Nous vous recommandons vivement d'utiliser un masque de champ pour spécifier les champs que vous souhaitez voir renvoyés dans la réponse.

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

Migrer des données hyperlocales de géocodage vers Destinations

Les fonctionnalités suivantes de l'API Geocoding v3 sont remplacées par la méthode SearchDestinations de l'API Geocoding v4 :

• Entrées
• Points de navigation
• Contours des bâtiments
• Domaine

Si vous utilisiez l'API Geocoding v3 pour les fonctionnalités ci-dessus, utilisez ce document pour vous aider à utiliser la méthode SearchDestinations à la place pour obtenir ces fonctionnalités. Ce document explique où trouver ces fonctionnalités dans la réponse SearchDestinations et les différences dans la façon dont elles sont représentées dans les réponses de l'API entre l'API Geocoding v3 et la méthode SearchDestinations de l'API Geocoding v4.

Entrées

Pour obtenir les entrées associées à un destination, utilisez le champ destination.entrances.

Notez que le format d'un entrance est légèrement différent du format d'entrée dans l'API Geocoding v3. Chaque entrée de destination.entrances comporte les champs suivants :

• displayName : nouveau champ facultatif qui contiendra un nom lisible par l'humain pour l'entrée, par exemple "Porte B".
• location : il s'agit d'un emplacement de type LatLng, qui est différent du format utilisé dans l'API Geocoding v3.
• tags : identique au champ tags des entrées de l'API Geocoding v3.
• place : analogue au champ buildingPlaceId des entrées de l'API Geocoding v3. Toutefois, l'ID de lieu dans ce champ peut correspondre à un lieu de n'importe quel type, et pas nécessairement à un bâtiment.

Points de navigation

Pour obtenir les points de navigation associés à un destination, utilisez le champ destination.navigationPoints.

Notez que le format d'un navigationPoint est légèrement différent du format de point de navigation dans l'API Geocoding v3. Chaque point de navigation dans destination.navigationPoints comporte les champs suivants :

• displayName : il s'agit d'un nouveau champ facultatif qui contient un nom lisible pour le point de navigation, par exemple "5e Avenue".
• location : il s'agit d'un emplacement de type LatLng, qui est différent du format utilisé dans l'API Geocoding v3.
• travelModes : semblable au champ restrictedTravelModes des points de navigation de l'API Geocoding v3. Les valeurs d'énumération possibles sont les mêmes. La seule différence est que ce champ représente désormais les modes de transport acceptables pour le point de navigation, plutôt que les modes de transport limités.
• usage : nouveau champ contenant les cas d'utilisation compatibles avec le point de navigation.

Contour des bâtiments

Pour obtenir les contours des bâtiments associés à un destination, vous devez utiliser le champ displayPolygon des objets placeView du destination qui représentent des bâtiments. Pour chaque placeView, vous pouvez vérifier s'il s'agit d'un bâtiment à l'aide du champ placeView.structureType. Si le type de structure est BUILDING, vous pouvez obtenir le contour à partir du champ placeView.displayPolygon. Le placeView comportera également des champs supplémentaires pour le bâtiment qui n'étaient pas présents dans l'API Geocoding v3.

Un destination peut avoir un objet placeView qui représente un bâtiment dans les champs suivants :

• destination.primary : il s'agit de l'emplacement principal de la destination.
• destination.containingPlaces : il s'agit d'un champ répété pouvant contenir des lieux plus grands qui "contiennent" le lieu principal. Par exemple, si le lieu principal est un subpremise, containingPlaces contient généralement le placeView représentant le bâtiment.
• destination.subDestinations : il s'agit d'un champ répété pouvant contenir des sous-destinations du lieu principal. Par exemple, les appartements individuels d'un immeuble. Ce champ ne comporte généralement pas de placeView représentant un bâtiment.

Notez que le format de placeView.displayPolygon correspond au format de contour de bâtiment dans l'API Geocoding v3, qui est le format GeoJSON, en utilisant le format RFC 7946.

Domaine

Comme pour les contours de bâtiments, pour obtenir les terrains associés à un destination, vous devez utiliser le champ displayPolygon des objets placeView du destination qui représentent des terrains. Pour chaque placeView, vous pouvez vérifier s'il s'agit d'un motif avec le champ placeView.structureType. Si le type de structure est GROUNDS, vous pouvez obtenir le contour à partir du champ placeView.displayPolygon. L'placeView comportera également des champs supplémentaires pour les motifs qui ne figuraient pas dans l'API Geocoding v3.

Un destination peut avoir un objet placeView qui représente un motif dans les champs suivants :

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

Notez que le format de placeView.displayPolygon correspond au format de contour des terrains dans l'API Geocoding v3, qui est le format GeoJSON, en utilisant le format RFC 7946.

Précision des résultats

Dans l'API Geocoding v3, le champ location_type de la géométrie de réponse indiquait la précision des résultats, et certains clients classaient ou filtraient les résultats en fonction de ces valeurs (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER et APPROXIMATE). Dans les migrations standards vers l'API Geocoding v4, ce champ est renommé granularity.

Dans l'API Destinations (v4 SearchDestinations), il n'y a pas de champ location_type. Les informations spatiales sont traitées différemment :

• Aucun filtrage manuel côté client n'est nécessaire : alors que le geocoding standard fournit plusieurs résultats à différents niveaux de précision, la méthode SearchDestinations minimise l'ambiguïté en renvoyant une seule destination optimisée dans la mesure du possible. Les clients n'ont ainsi plus besoin de filtrer les résultats par type de lieu pour déterminer lequel est le plus adapté.
• Informations spatiales représentées par le type de structure et les polygones d'affichage : La géométrie et la structure spatiales sont indiquées par :
  • displayPolygon (pour une géométrie exacte).
  • Le champ structureType dans l'objet placeView.
• Mappage des types de structures :
  • Un structureType de POINT, BUILDING ou SECTION correspond généralement à ce qui était auparavant appelé ROOFTOP.
  • Un structureType de GROUNDS correspond généralement à GEOMETRIC_CENTER.

Utiliser un masque de champ pour demander ces fonctionnalités

La méthode SearchDestinations nécessite un masque de champ, comme expliqué dans Choisir les champs à renvoyer. Le masque de champ peut être défini sur * pour renvoyer tous les champs ou sur les champs spécifiques que vous souhaitez recevoir. Par exemple, la requête d'API suivante définit le masque de champ pour recevoir tous les champs nécessaires pour obtenir les entrées, les points de navigation, les plans des bâtiments et les terrains d'une destination :

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

Considérations de sécurité

L'API Geocoding v4 est conçue comme une API de serveur à serveur. Il n'existe pas de chemin de migration direct de la version 3 vers la version 4 pour les utilisateurs de JavaScript. L'appel des méthodes v4 directement à partir du code JavaScript côté client (par exemple, dans un navigateur) à l'aide d'une clé API expose votre clé API à un risque élevé de vol et d'utilisation abusive.

Bien qu'utiles, les restrictions de l'URL de provenance HTTP ne suffisent pas à protéger les points de terminaison des services Web, car les pirates informatiques peuvent facilement les contourner en falsifiant l'en-tête Referer dans leurs requêtes.

Approche recommandée

Nous vous recommandons d'utiliser l'API Geocoding v4 depuis votre propre serveur backend. Votre application cliente doit envoyer des requêtes à ce serveur intermédiaire, qui appelle ensuite l'API Google de manière sécurisée à l'aide d'une clé API protégée (par exemple, une clé stockée dans une variable d'environnement ou un gestionnaire de secrets). Cela permet de s'assurer que votre clé API n'est jamais exposée dans le code du frontend.

Alternatives pour les besoins côté client

Si vous avez des besoins côté client qui nécessitent un géocodage, envisagez d'utiliser l'une des solutions côté client existantes :

• Service Geocoding dans l'API Maps JavaScript : le service Geocoding continue d'utiliser le backend v3 et est conçu pour être utilisé dans un environnement de navigateur.
• Kit UI pour Places : utilisez le Kit UI pour Places, y compris les éléments Place Autocomplete, pour les éléments d'interface utilisateur liés aux adresses.