Les méthodes de l'API Geocoding v4 sont limitées à 25 requêtes par seconde (RPS) par défaut. Pour savoir comment demander un quota plus élevé, consultez Afficher et gérer les quotas, puis sélectionnez API Geocoding comme service.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Migrer de Geocoding v3 vers v4

Développeurs de l'Espace économique européen (EEE)

L'API Geocoding v4 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 v4. Toutefois, si vous avez demandé une augmentation de quota pour la version 3 de l'API, vous devez demander une augmentation pour les nouvelles API v4.

Migrer depuis le géocodage direct v3

Si vous utilisez le géocodage v3 pour géocoder des adresses, vous devez migrer vers la méthode Géocoder une adresse de la version 4, 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 voir renvoyés dans la réponse.

Modifier les paramètres de requête

Paramètre v3	Paramètre v4	Remarques
`address`, `components`	`address`	L'adresse non structurée (v3 `address`) est désormais transmise dans le chemin d'URL. Les composants d'adresse structurée (v3 `components`) peuvent être transmis en tant que paramètres de requête `address.*`. Consultez Reproduire les filtres de composants v3.
`bounds`	`locationBias.rectangle`	Renommé ; la structure a été remplacée par un objet.
`language`	`languageCode`	Renommé.
`region`	`regionCode`	Renommé.
`extra_computations`	Supprimé	Remplacé par la méthode SearchDestinations.

Modifications apportées aux champs de réponse

Champ v3	Champ v4	Remarques
`status`, `error_message`	Supprimé	La version 4 utilise des codes d'état HTTP et des corps d'erreur.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Renommé.
`results.geometry.location_type`	`results.granularity`	Renommé.
`results.geometry.location`	`results.location`	Noms de champs : `lat`/`lng` → `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Noms de champs : `northeast`/`southwest` → `high`/`low`.
`results.postcode_localities`	`results.postalCodeLocalities`	Renommé. Désormais renvoyé pour une ou plusieurs localités (v3 requise > 1).
`results.partial_match`	Supprimé
Nouveauté	`results.addressComponents.languageCode`	Langue du composant d'adresse spécifique.
Nouveauté	`results.bounds`	Limites explicites à l'aide de `high`/`low`.
Nouveauté	`results.place`	Nom de ressource du lieu.
Nouveauté	`results.postalAddress`	Objet `PostalAddress` structuré.

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 la version 4 n'est pas compatible avec ce type de filtrage strict dans les paramètres de la requête. Dans la version 4, vous pouvez fournir des informations sur l'adresse sous la forme d'une seule chaîne non structurée dans le chemin d'accès ou sous la forme 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 petites fautes de frappe 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 version 3 et les champs postalAddress de la version 4 :

Filtre de composants v3	Champ de réponse v4
`country`	`postalAddress.regionCode`
`postal_code`	`postalAddress.postalCode`
`administrative_area`	`postalAddress.administrativeArea` ou `addressComponents`

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 version 3 pour les champs compatibles : 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 demande avec le postalAddress.regionCode de chaque résultat. Notez que, bien que l'API accepte les codes régionaux 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.

Exemple de code 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')

Exemple de code 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');

Filtrer par zone administrative

Faites correspondre le address.administrativeArea de votre demande avec le postalAddress.administrativeArea de chaque résultat. Comme pour les codes de pays, vous devez normaliser votre entrée en majuscules avant de la comparer. Cette méthode n'est fiable que si le administrativeArea de votre demande est fourni avec une abréviation standard de deux lettres. Il est possible que le postalAddress.administrativeArea de la réponse ne corresponde 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 zone administrative de niveau 1 (par exemple, "CN" pour les îles Canaries) peut être présente dans addressComponents, mais postalAddress.administrativeArea peut contenir la zone 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).

Exemple de code 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')

Exemple de code 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');

Filtrer par code postal

Faites correspondre le address.postalCode de votre demande 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 de code postal (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 de 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 de gestion 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é.

Exemple de code Python (axé sur les codes postaux américains)

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

Exemple de code Node.js (axé sur les codes postaux américains)

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 géocoding inversé v3

Si vous utilisez le geocoding inversé v3 pour convertir des coordonnées en adresses, vous devez migrer vers la méthode Geocoder une position de la version 4, qui accepte une requête GET.

Modifier les paramètres de requête

Paramètre v3	Paramètre v4	Remarques
`language`	`languageCode`	Renommé.
`region`	`regionCode`	Renommé.
`result_type`	`types`	Renommée ; utilise des paramètres de requête répétés.
`location_type`	`granularity`	Renommée ; utilise des paramètres de requête répétés.
`extra_computations`	Supprimé	Remplacé par la méthode SearchDestinations.

Modifications apportées aux champs de réponse

Champ v3	Champ v4	Remarques
`status`, `error_message`	Supprimé	La version 4 utilise des codes d'état HTTP et des corps d'erreur.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Renommé.
`results.geometry.location_type`	`results.granularity`	Renommé.
`results.geometry.location`	`results.location`	Noms de champs : `lat`/`lng` → `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Noms de champs : `northeast`/`southwest` → `high`/`low`.
Nouveauté	`results.addressComponents.languageCode`	Langue du composant d'adresse spécifique.
Nouveauté	`results.bounds`	Limites explicites à l'aide de `high`/`low`.
Nouveauté	`results.place`	Nom de ressource du lieu.
Nouveauté	`results.postalAddress`	Objet `PostalAddress` structuré.

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 l'utilisation du champ landmarks de SearchDestinationsResponse.

Migrer depuis le géocodage de lieux 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.

Modifier les paramètres de requête

Paramètre v3	Paramètre v4	Remarques
`place_id`	Champ `place` dans le fichier proto de la requête	L'ID de lieu est désormais fourni en tant que paramètre de chemin d'accès `places/{place}`, par exemple : `https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw`. Il correspond au champ "place" de la requête sous-jacente.
`language`	`languageCode`	Renommé.
`region`	`regionCode`	Renommé.

Modifications apportées aux champs de réponse

Champ v3	Champ v4	Remarques
`status`, `error_message`	Supprimé	La version 4 utilise des codes d'état HTTP et des corps d'erreur.
`results`	(racine)	La version 4 renvoie un seul objet de résultat, et non un tableau `results`.
`results.address_components.long_name`/`results.address_components.short_name`	`addressComponents.longText`/`addressComponents.shortText`	Renommé.
`results.geometry.location_type`	`granularity`	Renommé.
`results.geometry.location`	`location`	Noms de champs : `lat`/`lng` → `latitude`/`longitude`.
`results.geometry.viewport`	`viewport`	Noms de champs : `northeast`/`southwest` → `high`/`low`.
`results.postcode_localities`	`postalCodeLocalities`	Renommé. Désormais renvoyé pour une ou plusieurs localités (v3 requise > 1).
Nouveauté	`addressComponents.languageCode`	Langue du composant d'adresse spécifique.
Nouveauté	`bounds`	Limites explicites à l'aide de `high`/`low`.
Nouveauté	`place`	Nom de ressource du lieu.
Nouveauté	`postalAddress`	Objet `PostalAddress` structuré.

Migrer des données hyperlocales de géocodage vers des 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
Contour des bâtiments
Domaine

Si vous utilisiez l'API Geocoding v3 pour les fonctionnalités ci-dessus, consultez ce document pour savoir comment utiliser la méthode SearchDestinations à la place. Ce document explique où trouver ces fonctionnalités dans la réponse SearchDestinations, et les différences dans la façon dont ces fonctionnalités 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 : il s'agit d'un nouveau champ facultatif qui contient un nom lisible pour l'entrée, par exemple "Portail 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 concerner 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 : nouveau champ facultatif qui aura 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 : ce champ est semblable au champ restrictedTravelModes des points de navigation de l'API Geocoding v3. Les valeurs enum possibles sont les mêmes. La seule différence est que ce champ représente désormais les modes de déplacement acceptables pour le point de navigation, plutôt que les modes de déplacement restreints.
usage : nouveau champ contenant les cas d'utilisation compatibles avec le point de navigation. Notez que la plupart des points de navigation auront une utilisation UNKNOWN, mais cela ne signifie pas nécessairement que l'utilisation du point de navigation est limitée de quelque manière que ce soit.

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 plan à partir du champ placeView.displayPolygon. L'placeView comportera également des champs supplémentaires pour le bâtiment qui n'étaient pas inclus 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 des contours des bâtiments dans l'API Geocoding v3, qui est le format GeoJSON, à l'aide du 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 dans le destination qui représentent les terrains. Pour chaque placeView, vous pouvez vérifier s'il s'agit d'un motif grâce au champ placeView.structureType. Si le type de structure est GROUNDS, vous pouvez obtenir le plan à partir du champ placeView.displayPolygon. Le 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 des contours des terrains dans l'API Geocoding v3, qui est le format GeoJSON, 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 la réponse indiquait la précision des résultats. Certains clients classaient ou filtraient les résultats en fonction de ces valeurs (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER et APPROXIMATE). Dans les migrations standard de l'API Geocoding v4, ce champ est renommé granularity.

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

Aucun filtrage manuel côté client n'est nécessaire : alors que le géocodage standard fournit plusieurs résultats à différents niveaux de précision, la méthode SearchDestinations minimise l'ambiguïté en résolvant, dans la mesure du possible, une seule destination optimisée. Les clients n'ont ainsi plus besoin de filtrer par type de lieu pour déterminer quel résultat 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 structure :
- 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 vous pouvez le définir sur les champs spécifiques que vous souhaitez recevoir. Par exemple, la requête API suivante définit le masque de champ pour recevoir tous les champs requis 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 JavaScript. L'appel des méthodes v4 directement à partir de 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 à partir de 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 du 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.
Places UI Kit : utilisez le Places UI Kit, y compris les éléments Place Autocomplete, pour les éléments d'interface utilisateur liés aux adresses.

Migrer de Geocoding v3 vers v4 Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Migrer depuis le géocodage direct v3

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

Reproduire les filtres de composants v3

Exemples de filtrage côté client

Filtrer par pays

Filtrer par zone administrative

Filtrer par code postal

Migrer depuis le géocoding inversé v3

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

Migrer depuis les descripteurs d'adresse v3

Migrer depuis le géocodage de lieux v3

Modifier les paramètres de requête

Modifications apportées aux champs de réponse

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

Entrées

Points de navigation

Contour des bâtiments

Domaine

Précision des résultats

Utiliser un masque de champ pour demander ces fonctionnalités

Considérations de sécurité

Approche recommandée

Alternatives pour les besoins côté client

Migrer de Geocoding v3 vers v4