L'API Geocoding est un service Web qui convertit les adresses en coordonnées et en ID de lieu, et inversement. Sa méthode v4 SearchDestinations renvoie également des informations sur la destination, telles que les entrées de bâtiments, les points de navigation, les contours des bâtiments et des terrains, ainsi que les points de repère à proximité.
API Geocoding : informations clés
- Produit : API Geocoding
- Catégorie : Lieux
- Plate-forme : service Web (REST)
- S'exécute sur : le serveur (code backend)
- Étape de lancement : GA
- Cycle de vie : Actif
- Présentation : Présentation de l'API Geocoding
API Geocoding : quand l'utiliser ?
Utilisez l'API Geocoding dans les cas suivants :
- Vous devez convertir une adresse postale en coordonnées de latitude/longitude et en ID de lieu sur votre serveur backend.
- Vous avez besoin d'une adresse à afficher ou d'une région administrative (ville, code postal) pour les coordonnées GPS ou un ID de lieu connu.
- Vous avez besoin d'entrées de bâtiment, de points de navigation routables ou de contours de bâtiment/terrain pour guider les conducteurs ou les livreurs vers une destination.
- Vous devez résoudre une destination située dans un grand complexe (aéroport, centre commercial, campus) en sous-destinations ou en points de repère à proximité.
N'utilisez pas l'API Geocoding dans les cas suivants :
- Vous avez besoin du géocodage à partir du code JavaScript du navigateur côté client. Appeler la v4 avec une clé API exposée présente un risque de sécurité. Utilisez plutôt l'API Maps JavaScript.
- Vous devez calculer un itinéraire ou une heure d'arrivée prévue vers la destination géocodée. Utilisez plutôt l'API Routes.
- Vous avez besoin d'un guidage détaillé vers un jeton de point de navigation dans une application Android. Utilisez plutôt le SDK Navigation pour Android.
- Vous avez besoin d'un guidage détaillé vers un jeton de point de navigation dans une application iOS. Utilisez plutôt le SDK Navigation pour iOS.
API Geocoding : configuration
- Service à activer :
geocoding-backend.googleapis.com - Authentification : clé API, OAuth 2.0, compte de service
- Premiers pas : Configurer l'API Geocoding
- Référence : Documentation de référence de l'API Geocoding
- Tarifs : Utilisation et facturation de l'API Geocoding
- Règles : Règles de l'API Geocoding
- Notes de version : Notes de version de l'API Geocoding
API Geocoding : produits associés
- Souvent utilisé avec : l'API Routes, le SDK Navigation pour Android, le SDK Navigation pour iOS
API Geocoding : erreurs courantes
- Problème : Les requêtes
SearchDestinationssans masque de champ échouent et génèrent une erreur. Contrairement àGeocodeAddress,GeocodeLocationetGeocodePlace, le masque de champ est obligatoire. Correction : Définissez l'en-têteX-Goog-FieldMaskou le paramètre$fieldssur chaque requêteSearchDestinations. Consultez /maps/documentation/geocoding/choose-fields. - Problème :
GeocodeAddressv4 n'a pas de filtre de composant strict (components=country:USv3). Les paramètresaddress.*structurés sont combinés en une seule adresse et ne filtrent pas les résultats.regionCoden'a pas non plus de valeur par défaut dans la v4 (la valeur par défaut de la v3 étaitus). Solution : Filtrezresultscôté client : faites correspondreregionCodeen majuscules àpostalAddress.regionCode; faites correspondre les zones d'administration à deux lettres en majuscules àpostalAddress.administrativeAreaetadministrative_area_level_naddressComponents(shortText) ; normalisez l'entrée etpostalAddress.postalCode(supprimez les espaces/tirets et appliquez les règles de région). Consultez /maps/documentation/geocoding/geocoding-v4-migrate. - Problème : Appeler l'API Geocoding v4 directement depuis le code JavaScript du navigateur expose la clé API. Les restrictions d'URL de provenance HTTP peuvent être contournées en falsifiant l'en-tête
Referer. Solution : Appelez la v4 depuis votre propre backend avec une clé protégée, ou utilisez le service Geocoding de l'API Maps JavaScript (backend v3) pour les besoins côté client. Consultez /maps/documentation/geocoding/geocoding-v4-migrate. - Problème :
SearchDestinationspeut renvoyer des résultats qui n'ont pas d'adresse principale précise, contrairement à la v3 et aux autres méthodes de la v4. Solution : définissezplaceFilter.addressabilitysurPRIMARYlorsque vous n'avez besoin que de résultats avec des adresses principales précises. Consultez /maps/documentation/geocoding/geocoding-v4-migrate. - Problème : Le code écrit pour l'API Geocoding v3 ne fonctionne pas avec les réponses REST de la v4. En effet, la v4 utilise des noms de champs en lowerCamelCase (
addressComponents, et nonaddress_components), supprimestatuseterror_message, et renvoie un seul objet racine à partir deGeocodePlaceau lieu d'un tableauresults. Correction : Vérifiez les codes d'état HTTP et les corps d'erreur sur les appels REST v4, lisez les champs lowerCamelCase (addressComponents,postalAddress) et notez que les réponses gRPC utilisent toujours snake_case. Consultez /maps/documentation/geocoding/geocoding-v4-migrate.
API Geocoding : fonctionnalités anciennes et obsolètes
- Données hyperlocales de l'API Geocoding v3 (
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS; champs de réponsebuildings.entrances,navigation_points,buildings.building_outlines,grounds) : obsolètes depuis le 13 août 2025. Remplacement : méthodeSearchDestinationsde l'API Geocoding v4 (POST /v4/geocode/destinations). Consultez le guide de migration.
Ce que vous pouvez faire avec l'API Geocoding
Consultez les guides associés ci-dessous pour chaque tâche ou comparez les produits dans l'explorateur de fonctionnalités.
- Renvoyer les coordonnées de latitude/longitude d'une adresse (geocoding)
- Renvoyer l'adresse d'un ensemble de coordonnées de latitude/longitude (geocoding inversé)
- Limitez une requête de géocodage pour renvoyer des résultats dans une fenêtre d'affichage spécifique. Remarque : Dans l'API Geocoding v4, locationBias pondère les résultats en fonction de la fenêtre d'affichage spécifiée plutôt que de les restreindre strictement.
- Limitez une requête de géocodage ou de géocodage inversé pour ne renvoyer que les résultats d'une région, d'un pays ou d'un code postal spécifiques. Remarque : Dans l'API Geocoding v4, regionCode oriente les résultats vers une région CLDR spécifiée plutôt que de les restreindre strictement. Pour en savoir plus sur l'ancien filtrage des composants v3 par pays ou code postal, consultez https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Limitez une requête de geocoding inversé pour ne renvoyer que les résultats correspondant aux types d'adresses spécifiés. Remarque : Dans l'API Geocoding v4, le paramètre "types" filtre les résultats de géocodage inversé renvoyés par type d'adresse après la recherche, plutôt que de restreindre la recherche sous-jacente.
- Renvoyer des informations sur la proximité d'une adresse par rapport à des points de repère ou des zones.
- Renvoie des informations sur la proximité de points de repère ou de zones pour un ensemble de coordonnées de latitude/longitude.
- Renvoie des informations sur la proximité de points de repère ou de zones pour un identifiant de lieu Google.
- Renvoie l'adresse d'un identifiant de lieu Google.
- Renvoyez les coordonnées de latitude/longitude du contour d'un bâtiment pour une adresse.
- Renvoie les coordonnées de latitude/longitude du contour d'un bâtiment pour un ensemble de coordonnées de latitude/longitude.
- Renvoyez les coordonnées de latitude/longitude du contour d'un bâtiment pour un identifiant de lieu Google.
- Renvoyer les coordonnées de latitude/longitude de l'entrée d'un bâtiment pour une adresse
- Renvoyer les coordonnées de latitude/longitude de l'entrée d'un bâtiment pour un ensemble de coordonnées de latitude/longitude.
- Renvoyer les coordonnées de latitude/longitude de l'entrée d'un bâtiment pour un identifiant de lieu Google