Guide de référence rapide de l'API Geocoding

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

API Geocoding : erreurs courantes

  • Problème : Les requêtes SearchDestinations sans masque de champ échouent et génèrent une erreur. Contrairement à GeocodeAddress, GeocodeLocation et GeocodePlace, le masque de champ est obligatoire. Correction : Définissez l'en-tête X-Goog-FieldMask ou le paramètre $fields sur chaque requête SearchDestinations. Consultez /maps/documentation/geocoding/choose-fields.
  • Problème : GeocodeAddress v4 n'a pas de filtre de composant strict (components=country:US v3). Les paramètres address.* structurés sont combinés en une seule adresse et ne filtrent pas les résultats. regionCode n'a pas non plus de valeur par défaut dans la v4 (la valeur par défaut de la v3 était us). Solution : Filtrez results côté client : faites correspondre regionCode en majuscules à postalAddress.regionCode ; faites correspondre les zones d'administration à deux lettres en majuscules à postalAddress.administrativeArea et administrative_area_level_n addressComponents (shortText) ; normalisez l'entrée et postalAddress.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 : SearchDestinations peut 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éfinissez placeFilter.addressability sur PRIMARY lorsque 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 non address_components), supprime status et error_message, et renvoie un seul objet racine à partir de GeocodePlace au lieu d'un tableau results. 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éponse buildings.entrances, navigation_points, buildings.building_outlines, grounds) : obsolètes depuis le 13 août 2025. Remplacement : méthode SearchDestinations de 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.