Migrer de Geocoding v3 vers v4

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

Si votre adresse de facturation se trouve dans l'Espace économique européen, les Conditions d'utilisation de Google Maps Platform pour l'EEE s'appliqueront à votre utilisation des Services à compter du 8 juillet 2025. La fonctionnalité varie selon la région. En savoir plus

L'API Geocoding v4 introduit plusieurs nouveaux points de terminaison qui remplacent les fonctionnalités de la version 3 de l'API. Ce guide vous explique comment migrer votre application pour utiliser les nouveaux points de terminaison v4.

Vous pouvez utiliser vos clés API existantes avec les nouveaux points de terminaison de la version 4. 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. Il n'existe aucun chemin de migration pour les utilisateurs JavaScript.

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

Migrer depuis le géocodage direct v3

Si vous utilisez Geocoding pour géocoder des adresses, vous devez migrer vers le point de terminaison v4 Géocoder une adresse, 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.

Avertissement : Dans tous les points de terminaison de la version 4, les noms de champs sont mis en forme en lower camel case (par exemple, addressComponents), contrairement aux points de terminaison de la version 3, qui utilisaient snake case (par exemple, address_components). Les réponses RPC continuent d'utiliser le snake case dans la version 4, comme dans la version 3.

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 filtres de composants (v3 components) sont désormais transmis en tant que paramètres de requête address.*.
bounds	locationBias.rectangle	Renommé ; la structure a été remplacée par un objet.
language	languageCode	Renommé.
region	regionCode	Renommé.
extra_computations	Supprimé

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é.

Migrer depuis le géocoding inversé v3

Si vous utilisez le geocoding inversé pour convertir des coordonnées en adresses, vous devez migrer vers le point de terminaison V4 Géocoder une position de manière inversée, 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.

Avertissement : Dans tous les points de terminaison de la version 4, les noms de champs sont mis en forme en lower camel case (par exemple, addressComponents), contrairement aux points de terminaison de la version 3, qui utilisaient snake case (par exemple, address_components). Les réponses RPC continuent d'utiliser le snake case dans la version 4, comme dans la version 3.

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é

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 Place Geocoding v3

Si vous utilisez place_id pour obtenir l'adresse d'un ID de lieu spécifique avec Geocoding v3, vous devez migrer vers le point de terminaison Place Geocoding 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.

Avertissement : Dans tous les points de terminaison de la version 4, les noms de champs sont mis en forme en lower camel case (par exemple, addressComponents), contrairement aux points de terminaison de la version 3, qui utilisaient snake case (par exemple, address_components). Les réponses RPC continuent d'utiliser le snake case dans la version 4, comme dans la version 3.

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/v4beta/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 le point de terminaison SearchDestinations de l'API Geocoding v4 :

• Entrées
• Points de navigation
• Plans de bâtiments
• Domaine

Si vous utilisiez l'API Geocoding v3 pour les fonctionnalités ci-dessus, consultez ce document pour savoir comment utiliser le point de terminaison SearchDestinations à la place. Ce document explique où trouver ces fonctionnalités dans la réponse de l'API 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 le point de terminaison 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 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 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 : 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.

Plans de 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 présents dans l'API Geocoding v3.

Remarque : Vous recherchez simplement le polygone d'un bâtiment à un certain emplacement ? Vous pouvez utiliser le paramètre placeFilter dans votre requête pour affiner les résultats. Pour ne renvoyer que les résultats de la construction, définissez structureType sur "BUILDING" dans placeFilter. Si votre priorité est d'obtenir un polygone (même pour les lieux sans adresse précise), définissez addressability sur "ANY" dans placeFilter pour renvoyer le polygone le plus précis disponible.

Exemple

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

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é qui peut 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 de bâtiments dans l'API Geocoding v3, qui est le format GeoJSON, 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 dans le destination qui représentent les terrains. Pour chaque placeView, vous pouvez vérifier s'il s'agit d'un motif à l'aide du 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.

Utiliser un masque de champ pour demander ces fonctionnalités

Le point de terminaison 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/v4alpha/geocode/destinations