Google Maps Geocoding API

Ce service est également disponible au sein de Google Maps JavaScript API ou des bibliothèques clients Java et Python.

Qu'est-ce que le géocodage ?

Le géocodage est le processus qui permet de convertir des adresses (comme « 1600 Amphitheatre Parkway, Mountain View, CA ») en coordonnées géographiques (comme latitude 37.423021 et longitude -122.083739), que vous pouvez ensuite utiliser pour placer des marqueurs sur une carte, ou pour positionner la carte.

Le géocodage inversé est le processus de conversion de coordonnées géographiques en adresses lisibles. Le service de géocodage inversé de Google Maps Geocoding API vous permet également de retrouver l'adresse correspondant à un identifiant de lieu donné.

Google Maps Geocoding API permet d'accéder directement à ces services via une requête HTTP.

Avant de commencer

Ce document est destiné aux développeurs de sites Web et d'applications mobiles qui souhaitent utiliser des données géocodées dans les cartes fournies par l'une des Google Maps API.

Ce service est normalement conçu pour le géocodage d'adresses statiques (c'est-à-dire connues à l'avance) afin de placer du contenu d'application sur une carte ; il n'est pas conçu pour répondre en temps réel à la demande d'un utilisateur, par exemple. Pour le géocodage dynamique (par exemple, au sein d'un élément de l'interface utilisateur), consultez la documentation sur le Géocodeur clientGoogle Maps JavaScript API et/ou sur les API de géolocalisation des services Google Play.

Le géocodage est une tâche qui requiert beaucoup de temps et de ressources. Dans la mesure du possible, pré-géocodez les adresses connues (en utilisant Google Maps Geocoding API décrite ici ou un autre service de géocodage) et stockez vos résultats dans une mémoire cache temporaire de votre propre conception.

Pour utiliser Google Maps Geocoding API, vous devez disposer d'une clé d'API.

Obtenir une clé Limites d'utilisation

Format d'une requêteGoogle Maps Geocoding API

Une requête Google Maps Geocoding API doit respecter le format suivant :

https://maps.googleapis.com/maps/api/geocode/output?parameters

output peut prendre l'une des valeurs suivantes :

  • json (recommandé) indique que la réponse doit être au format JSON (JavaScript Object Notation).
  • xml indique que la réponse doit être au format XML.

Pour accéder à Google Maps Geocoding API via le protocole HTTP, utilisez le format suivant :

http://maps.googleapis.com/maps/api/geocode/output?parameters

Le protocole HTTP n'est pas recommandé pour les applications qui incluent des données utilisateurs sensibles (comme la position géographique de l'utilisateur) dans leurs requêtes.

Certains paramètres sont obligatoires, tandis que d'autres sont facultatifs. Comme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&).

Les utilisateurs de Google Maps API for Work doivent inclure des paramètres client et signature valides dans leurs requêtes de géocodage. Pour plus d'informations, reportez-vous au chapitre Google Maps API for Work Web Services.

Le reste de cette page décrit séparément le géocodage et le géocodage inversé, car les paramètres disponibles sont différents selon le type de requête.

Géocodage (recherche de latitude/longitude)

Paramètres obligatoires dans une requête de géocodage :

  • address — Adresse postale que vous souhaitez géocoder, au format utilisé par les services postaux nationaux du pays concerné. Les éléments d'adresse supplémentaires, comme la raison sociale et les numéros d'appartement, de bâtiment ou d'étage, sont à éviter. Pour davantage d'informations, reportez-vous à la section FAQ.
         ou
    components — Filtre de composant pour lequel vous souhaitez obtenir un géocode. Pour plus d'informations, voir Filtrer par composants. Le filtre par composants est également accepté en tant que paramètre facultatif si un paramètre address est fourni.
  • keyClé d'API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

Paramètres facultatifs dans une requête de géocodage :

  • bounds — Zone de délimitation de la fenêtre d'affichage dans laquelle les résultats de géocodage sont affinés de manière plus importante. Ce paramètre ne fera qu'influer sur les résultats du géocodeur, sans les limiter totalement. (Pour plus d'informations, voir Limiter les résultats à une fenêtre d'affichage ci-dessous.)
  • language — Langue dans laquelle les résultats sont renvoyés. Voir la liste des langues prises en charge. Notez que cette liste peut ne pas être exhaustive, car nous mettons régulièrement à jour les langues prises en charge. Si le paramètre language n'est pas fourni, le géocodeur tente si possible d'utiliser la langue native du domaine à partir duquel la requête est envoyée.
  • region — Code de région, indiqué sous forme de valeur ccTLD (« domaine de premier niveau ») à deux caractères. Ce paramètre ne fera qu'influer sur les résultats du géocodeur, sans les limiter totalement. (Pour plus d'informations, voir Limiter les résultats à une région ci-dessous).
  • components — Filtres de composants, séparés par une barre verticale (|). Chaque filtre de composant est constitué d'une paire component:value et limite totalement les résultats du géocodeur. Pour plus d'informations, voir Filtrer par composants ci-dessous.

Réponses aux requêtes de géocodage

Les réponses aux requêtes de géocodage sont renvoyées au format défini par l'indicateur output dans le chemin de la requête URL.

Dans cet exemple, Google Maps Geocoding API demande une réponse au format json pour une requête portant sur l'adresse « 1600 Amphitheatre Parkway, Mountain View, CA ».

Cette requête illustre l'utilisation de l'indicateur output au format JSON :

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Cette requête illustre l'utilisation de l'indicateur output au format XML :

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Cliquez sur les onglets ci-dessous pour voir les exemples de réponses aux formats JSON et XML.

JSON
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Pkwy",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Notez que la réponse au format JSON contient deux éléments racine :

  • "status" contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • "results" contient un tableau avec des informations sur les adresses géocodées et des informations géométriques.

En général, une seule entrée du tableau "results" est renvoyée pour les recherches d'adresse, mais il se peut que le géocodeur renvoie plusieurs résultats si les requêtes d'adresse sont ambiguës.

Notez qu'il faut généralement analyser ces résultats pour pouvoir en extraire des valeurs. Les données JSON sont relativement faciles à analyser. Des modèles de conception recommandés sont disponibles dans la section Analyse JSON.

XML
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Pkwy</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
    <lat>37.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

Notez que la réponse XML est constituée d'un seul élément <GeocodeResponse> et de deux éléments de niveau supérieur :

  • <status> contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • Zéro, un ou plusieurs éléments <result>, chacun contenant un ensemble unique d'informations sur les adresses géocodées et d'informations géométriques.

Notez que cette réponse est beaucoup plus longue que la réponse JSON. C'est pourquoi nous vous recommandons d'utiliser json comme indicateur de sortie privilégié, sauf si le service requiert xml pour une raison spécifique. En outre, il peut s'avérer délicat de traiter les arborescences XML de manière à faire référence aux nœuds et aux éléments adéquats. Des modèles de conception recommandés pour le traitement des résultats sont disponibles dans la section Analyse XML avec XPath.

Dans la suite de la présente documentation, nous utiliserons la syntaxe JSON. Dans la plupart des cas, le format de sortie n'a pas d'importance lorsqu'il s'agit d'illustrer des concepts ou des noms de champs dans la documentation. Notez cependant les légères différences suivantes :

  • Les résultats XML sont incorporés dans un élément racine <GeocodeResponse>.
  • JSON représente les entrées avec plusieurs éléments par plusieurs tableaux (types), tandis que XML les représente à l'aide de plusieurs éléments distincts (<type>).
  • Les éléments vides sont indiqués sous forme de tableaux vides en JSON, mais par l'absence de ces éléments en XML. Par exemple, une réponse qui ne génère aucun résultat renvoie un tableau results vide en JSON, mais aucun élément <result> en XML.

Codes de statut

Le champ "status" de l'objet de la réponse de Geocoding contient le statut de la requête et peut contenir des informations de débogage qui vous aident à savoir pourquoi le géocodage ne fonctionne pas. Le champ "status" peut contenir les valeurs suivantes :

  • "OK" indique qu'aucune erreur n'est survenue, que l'adresse a été analysée et qu'au moins un géocode a été trouvé.
  • "ZERO_RESULTS" indique que le géocode a réussi mais n'a renvoyé aucun résultat. Cela peut se produire si le géocodeur a reçu un paramètre address inexistant.
  • "OVER_QUERY_LIMIT" indique que vous avez dépassé votre quota.
  • "REQUEST_DENIED" indique que votre requête a été rejetée.
  • "INVALID_REQUEST" indique généralement qu'il manque un élément (address, components ou latlng) de la requête.
  • "UNKNOWN_ERROR" indique que la requête n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Messages d'erreur

Lorsque le géocodeur renvoie un code de statut autre que OK, l'objet de la réponse de Geocoding peut comporter un champ supplémentaire error_message. Ce champ contient des informations plus détaillées sur les causes de ce code de statut.

Remarque : La présence de ce champ n'est pas garantie et son contenu est susceptible de varier.

Résultats

Le géocodeur renvoie les résultats sous forme de tableau d'éléments results (JSON). Même si le géocodeur ne renvoie aucun résultat (si l'adresse n'existe pas, par exemple), il renvoie malgré tout un tableau results vide. (Les réponses XML sont composées de zéro, un ou plusieurs éléments <result>.)

Un résultat contient généralement les champs suivants :

  • Le tableau types[] indique le type du résultat renvoyé. Ce tableau contient un ensemble de zéro, une ou plusieurs balises identifiant le type de caractéristique renvoyé dans le résultat. Par exemple, le géocode de Chicago renvoie « locality » qui indique que Chicago est une ville, et renvoie également « political » qui indique qu'il s'agit d'une entité politique.

  • formatted_address est une chaîne contenant une adresse lisible de ce lieu. Bien souvent, cette adresse équivaut à l'« adresse postale », laquelle diffère parfois d'un pays à l'autre. (Notez que certains pays, tels que le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.) Cette adresse est généralement composée d'un ou plusieurs composants d'adresse. Par exemple, l'adresse « 111 8e Avenue, New York, NY » contient des composants d'adresse distincts pour « 111 » (le numéro de rue), « 8e Avenue » (la voie), « New York » (la ville) et « NY » (l'État). Ces composants d'adresse contiennent des informations supplémentaires, comme indiqué ci-dessous.

  • address_components[] est un tableau contenant les différents composants d'adresse, comme expliqué ci-dessus. Chaque composant address_component contient généralement :

    • types[] est un tableau indiquant le type du composant d'adresse.
    • long_name, la description complète ou le nom du composant d'adresse, tels que renvoyés par le géocodeur.
    • short_name est le nom abrégé du composant d'adresse, le cas échéant. Par exemple, un composant d'adresse pour l'État de l'Alaska peut avoir un nom long (long_name) correspondant à « Alaska » et un nom court (short_name) « AK » utilisant l'abréviation postale à 2 lettres.

    Notez que le tableau address_components[] peut contenir plus de composants d'adresse que ceux indiqués dans formatted_address.

  • postcode_localities[] est un tableau représentant toutes les localités contenues dans un code postal. Ce composant est présent uniquement lorsque le résultat correspond à un code postal regroupant plusieurs localités.
  • geometry contient les informations suivantes :

    • location qui contient la valeur latitude,longitude géocodée. Pour les recherches d'adresse normales, ce champ est généralement le plus important.
    • location_type qui stocke des données supplémentaires sur le lieu spécifié. Les valeurs suivantes sont actuellement prises en charge :

      • "ROOFTOP" indique que le résultat renvoyé est un géocode précis pour lequel nous disposons d'informations sur le lieu avec une précision jusqu'au niveau de l'adresse postale.
      • "RANGE_INTERPOLATED" indique que le résultat renvoyé correspond à une approximation (généralement sur une route) interpolée entre deux points précis (tels que des intersections). Les résultats interpolés sont généralement renvoyés lorsque le géocodage rooftop est indisponible pour une adresse postale.
      • "GEOMETRIC_CENTER" indique que le résultat renvoyé est le centre géométrique d'un résultat comme une polyligne (par exemple, une rue) ou d'un polygone (région).
      • "APPROXIMATE" indique que le résultat renvoyé est approximatif.
    • viewport contient la fenêtre d'affichage recommandée pour l'affichage du résultat renvoyé, spécifié sous la forme de deux valeurs latitude,longitude définissant les angles southwest et northeast de la zone de délimitation de la fenêtre d'affichage. La fenêtre d'affichage est généralement utilisée pour encadrer un résultat présenté à l'utilisateur.
    • bounds (éventuellement renvoyé) stocke la zone de délimitation pouvant contenir la totalité du résultat renvoyé. Notez que ces limites peuvent ne pas correspondre à la fenêtre d'affichage recommandée. (Par exemple, San Francisco inclut les îles Farallon, qui techniquement font partie de la ville, mais ne devraient vraisemblablement pas apparaître dans les résultats de la fenêtre d'affichage.)
  • partial_match indique que le géocodeur n'a pas renvoyé de correspondance exacte pour la requête d'origine, mais qu'il a pu trouver une partie de l'adresse demandée. Nous vous recommandons d'examiner la requête d'origine pour vérifier qu'elle ne contient pas d'erreur de syntaxe et/ou que l'adresse est bien complète.

    Les correspondances partielles sont souvent renvoyées lorsque l'adresse postale n'existe pas dans la localité que vous avez indiquée dans la requête. Les correspondances partielles peuvent aussi être renvoyées lorsqu'une requête correspond à plusieurs lieux au sein de la même localité. Par exemple, « 21 Henr St, Bristol, UK » renvoie une correspondance partielle à la fois pour Henry Street et pour Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de géocodage peut suggérer une autre adresse. Les suggestions déclenchées de cette façon sont également signalées comme des correspondances partielles.

  • place_id est un identifiant unique qui peut être utilisé avec d'autres API Google. Vous pouvez par exemple utiliser place_id dans une requête Google Places API pour obtenir des informations sur une entreprise locale, comme son numéro de téléphone, ses horaires d'ouverture, les avis des utilisateurs, etc. Voir la présentation des identifiants de lieu.

Comme le format exact d'une réponse individuelle à une requête Google Maps Geocoding API n'est pas garanti, vous ne devez jamais considérer que les éléments sont dans des positions absolues. (En particulier, le nombre de composants d'adresse address_components au sein d'une réponse Geocoding API varie en fonction de l'adresse demandée et peut changer avec le temps.) Vous devez donc analyser la réponse et sélectionner les réponses appropriées via des expressions. Pour plus d'informations, voir Analyser les réponses du service Web.

Types d'adresse et types de composant d'adresse

Le tableau types[] dans le résultat indique le type d'adresse. Une adresse postale, un pays ou une entité politique sont des exemples de types d'adresse. Un tableau types[] figure également dans les tableaux address_components[], pour indiquer le type de chaque partie de l'adresse (un numéro de rue ou un pays, par exemple). (Vous trouverez ci-dessous la liste complète des types.) Les adresses peuvent avoir plusieurs types. Les types peuvent être considérés comme des balises. Par exemple, de nombreuses villes sont balisées avec les types political et locality.

Les types suivants sont pris en charge et renvoyés par le géocodeur dans les tableaux de types d'adresse et de types de composant d'adresse :

  • street_address indique une adresse de rue précise.
  • route indique une route nommée (comme « US 101 »).
  • intersection indique une intersection majeure, généralement de deux routes principales.
  • political indique une entité politique. Habituellement, ce type indique un polygone de certaines administrations civiles.
  • country indique l'entité politique nationale et correspond généralement au type de premier ordre renvoyé par le géocodeur.
  • administrative_area_level_1 indique une entité civile de premier ordre en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs correspondent aux États. Toutes les nations ne possèdent pas ces niveaux administratifs.
  • administrative_area_level_2 indique une entité civile de deuxième ordre en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs correspondent aux comtés. Toutes les nations ne possèdent pas ces niveaux administratifs.
  • administrative_area_level_3 indique une entité civile de troisième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
  • administrative_area_level_4 indique une entité civile de quatrième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
  • administrative_area_level_5 indique une entité civile de cinquième ordre en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne possèdent pas ces niveaux administratifs.
  • colloquial_area indique un autre nom couramment utilisé pour l'entité.
  • locality indique une entité politique de ville ou de municipalité incorporée.
  • ward indique un type spécifique de localité japonaise afin de faciliter la distinction entre plusieurs composants de localité au sein d'une adresse japonaise.
  • sublocality indique une entité civile de premier ordre en dessous de la localité. Certains points géographiques peuvent recevoir l'un des types supplémentaires suivants : de sublocality_level_1 à sublocality_level_5. Chaque niveau de sous-localité correspond à une entité civile. Plus le nombre est élevé, plus la zone géographique est petite.
  • neighborhood indique un quartier nommé.
  • premise indique un lieu nommé, généralement un bâtiment ou un ensemble de bâtiments ayant un nom commun.
  • subpremise indique une entité de premier ordre située en dessous d'un lieu nommé, généralement un bâtiment particulier au sein d'un ensemble de bâtiments ayant un nom commun.
  • postal_code indique un code postal tel qu'utilisé dans les adresses de courrier postal du pays.
  • natural_feature indique une caractéristique naturelle importante.
  • airport indique un aéroport.
  • park indique un parc nommé.
  • point_of_interest indique un point d'intérêt nommé. Généralement, ces « POI » sont des entités locales importantes qui ne s'intègrent pas facilement à une autre catégorie, comme l'« Empire State Building » ou la « Statue de la Liberté ».

Une liste de types vide indique qu'il n'y a aucun type connu pour un composant d'adresse particulier, par exemple un Lieu-dit en France.

En plus des types énumérés ci-dessus, les composants d'adresse peuvent contenir les types suivants.

Remarque : Cette liste n'est pas exhaustive et est sujette à modification.

  • floor indique l'étage, pour une adresse d'immeuble.
  • establishment indique généralement un lieu qui n'a pas encore été classé.
  • point_of_interest indique un point d'intérêt nommé.
  • parking indique un parking ou une structure de stationnement.
  • post_box indique une boîte postale spécifique.
  • postal_town indique un groupement de zones géographiques, telles que la localité locality et la sous-localité sublocality, utilisé pour les adresses postales dans certains pays.
  • room indique l'appartement, pour une adresse d'immeuble.
  • street_number indique le numéro de rue précis.
  • bus_station, train_station et transit_station indiquent l'emplacement d'un arrêt de bus, de train ou d'un transport en commun.

Limiter les résultats à une fenêtre d'affichage

Dans une requête de géocodage, vous pouvez demander au service Geocoding de privilégier les résultats à l'intérieur d'une fenêtre d'affichage donnée (exprimée sous la forme d'un cadre). Pour ce faire, vous devez définir le paramètre bounds au sein de l'URL de la requête. Notez que ce paramètre ne fait que privilégier les résultats dans les limites ; s'il existe des résultats plus pertinents en dehors de ces limites, ils peuvent être inclus.

Le paramètre bounds définit les coordonnées latitude/longitude des angles sud-ouest et nord-est de ce cadre en utilisant le caractère barre verticale (|) pour séparer les coordonnées.

Par exemple, le géocode de « Winnetka » renvoie généralement cette banlieue de Chicago :

Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Toutefois, avec l'ajout d'un argument bounds définissant une zone de délimitation pour la Vallée de San Fernando à Los Angeles, ce géocode renvoie le quartier nommé « Winnetka » situé dans ce lieu :

Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Limiter les résultats à une région

Dans une réponse à une requête de géocodage, Google Maps Geocoding API renvoie les résultats d'adresse influencés par la région (généralement le pays) depuis laquelle la requête est envoyée. Par exemple, les recherches pour « San Francisco » peuvent renvoyer des résultats différents selon qu'elles sont effectuées depuis un domaine aux États-Unis ou en Espagne.

Vous pouvez définir Google Maps Geocoding API pour renvoyer des résultats orientés vers une région en particulier, en utilisant le paramètre region. Ce paramètre peut prendre un argument ccTLD (domaine de premier niveau correspondant au code pays) qui spécifie la région à privilégier. La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est « uk » (.co.uk) tandis que son code ISO 3166-1 est « gb » (ce qui correspond techniquement à l'entité « Royaume-Uni de Grande Bretagne et d'Irlande du Nord »).

Les résultats du géocodage peuvent être influencés pour chaque domaine dans lequel l'application Google Maps principale est officiellement lancée. Notez que ce procédé ne fait que privilégier les résultats propres à un domaine particulier ; s'il existe des résultats plus pertinents en dehors de ce domaine, ils peuvent être inclus.

Par exemple, un géocode pour la ville de « Tolède » renvoie le résultat suivant, car le domaine par défaut de Google Maps Geocoding API est défini sur les États-Unis. Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Une requête de géocodage pour « Tolède » avec le paramètre region=es (Espagne) renvoie les coordonnées de la ville espagnole. Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Filtrer par composants

Dans une réponse de géocodage, Google Maps Geocoding API peut renvoyer des résultats d'adresse limités à une zone spécifique. Cette restriction est spécifiée à l'aide du filtre components. Un filtre est constitué d'une liste de paires component:value séparées par une barre verticale (|). Seuls les résultats correspondant à tous les filtres sont renvoyés. Les valeurs de filtre prennent en charge les mêmes méthodes de correction orthographique et de correspondance partielle que les autres requêtes de géocodage. Si un résultat de géocodage est une correspondance partielle pour un filtre de composant, il contient un champ partial_match dans la réponse.

Les components pouvant être filtrés incluent :

  • route, qui correspond au nom long ou court d'une route.
  • locality, qui correspond à la fois au type locality et sublocality.
  • administrative_area, qui correspond à tous les niveaux de la région administrative administrative_area.
  • postal_code correspond au code postal postal_code et au préfixe postal_code_prefix.
  • country correspond au nom du pays ou à un code pays ISO 3166-1 à deux lettres.

Remarque : Chaque composant d'adresse peut être spécifié soit dans le paramètre d'adresse, soit dans un filtre de composant, mais pas dans les deux. En pareil cas, le résultat renvoyé est ZERO_RESULTS.

Un géocode pour « Santa Cruz » avec components=country:ES renvoie Santa Cruz de Tenerife dans les îles Canaries, en Espagne. Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Une requête contenant un filtre de composant renvoie uniquement les résultats correspondant à ce filtre. Si aucune correspondance n'est trouvée, le géocodeur renvoie un résultat qui correspond au filtre lui-même. Requête :

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Le filtrage par composants renvoie une réponse ZERO_RESULTS uniquement si vous spécifiez des filtres qui s'excluent mutuellement. Requête :

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Réponse :

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

En utilisant le filtre components, il est possible de faire une requête sans indiquer de paramètre d'adresse, mais vous ne pouvez pas spécifier de composant sans valeur. Requête :

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Réponse :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Géocodage inversé (recherche d'adresse)

Le terme géocodage fait généralement référence à la conversion d'une adresse lisible en un point géographique sur une carte. Le processus inverse, c'est-à-dire la conversion d'un point géographique sur une carte en adresse lisible par l'homme, est appelé géocodage inversé.

Paramètres obligatoires : Vous devez fournir un, et un seul, des paramètres suivants dans une requête de géocodage inversé :

  • Soit : latlng — Valeurs de latitude et de longitude désignant le point géographique pour lequel vous souhaitez obtenir l'adresse lisible la plus proche.
  • Soit : place_id — Identifiant du lieu pour lequel vous souhaitez obtenir l'adresse lisible correspondante. L'identifiant de lieu est un identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser l'identifiant placeID renvoyé par Google Maps Roads API pour obtenir l'adresse d'un point affiché. Pour plus d'informations sur les identifiants de lieu, voir la présentation des identifiants de lieu. L'identifiant de lieu ne peut être spécifié que si la requête inclut une clé d'API ou un ID client Google Maps API for Work.

Paramètres facultatifs dans une requête de géocodage inversé :

Voici les paramètres facultatifs que vous pouvez inclure dans une requête de géocodage inversé :

  • keyClé d'API de votre application, obtenue à partir de Google Developers Console. Cette clé identifie votre application à des fins de gestion des quotas.
  • language — Langue dans laquelle les résultats sont renvoyés. Voir la liste des langues prises en charge. Notez que cette liste peut ne pas être exhaustive, car nous mettons régulièrement à jour les langues prises en charge. Si le paramètre language n'est pas fourni, le géocodeur tente si possible d'utiliser la langue native du domaine à partir duquel la requête est envoyée.
  • result_type — Un ou plusieurs types d'adresse, séparés par une barre verticale (|). Exemples de types d'adresse : country, street_address, postal_code. Pour la liste complète des valeurs autorisées, voir les types d'adresse sur cette page. Le fait d'indiquer un type permet de limiter les résultats à ce type. Si plusieurs types sont indiqués, l'API renvoie toutes les adresses qui correspondent à n'importe lequel des types. Remarque : Ce paramètre est disponible uniquement pour les requêtes qui incluent une clé d'API ou un ID client.
  • location_type — Un ou plusieurs types de lieu, séparés par une barre verticale (|). Le fait d'indiquer un type permet de limiter les résultats à ce type. Si plusieurs types sont indiqués, l'API renvoie toutes les adresses qui correspondent à n'importe lequel des types. Remarque : Ce paramètre est disponible uniquement pour les requêtes qui incluent une clé d'API ou un ID client. Les valeurs suivantes sont prises en charge :
    • "ROOFTOP" limite les résultats aux adresses pour lesquelles nous disposons d'informations sur le lieu avec une précision jusqu'au niveau de l'adresse postale.
    • "RANGE_INTERPOLATED" limite les résultats à ceux qui correspondent à une approximation (généralement sur une route) interpolée entre deux points précis (tels que des intersections). Une fourchette de valeurs interpolées indique généralement que les géocodes rooftop ne sont pas disponibles pour une adresse postale.
    • "GEOMETRIC_CENTER" limite les résultats aux centres géométriques d'un point géographique comme une polyligne (par exemple, une rue) ou un polygone (région).
    • "APPROXIMATE" limite les résultats à ceux qui sont caractérisés comme approximatifs.

Si les deux restrictions result_type et location_type sont présentes, l'API renvoie uniquement les résultats qui correspondent à la fois à la restriction result_type et à la restriction location_type.

Géocodage inversé pour une latitude/longitude

La requête suivante contient la valeur latitude/longitude pour un lieu à Brooklyn :

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Remarque : Assurez-vous que les valeurs de latitude et de longitude ne sont séparées par aucun espace lors de leur insertion dans le paramètre latlng.

La requête ci-dessus renvoie le résultat suivant :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

Notez que le géocodeur inversé a renvoyé plusieurs résultats. Les résultats "formatted_address" ne correspondent pas uniquement à des adresses postales, mais également à toutes les possibilités de nommer géographiquement un lieu. Par exemple, lors du géocodage d'un point dans la ville de Chicago, le point géocodé peut être indiqué sous la forme d'une adresse postale, d'une ville (Chicago), d'un État (Illinois) ou d'un pays (États-Unis). Toutes ces désignations sont des « adresses » pour le géocodeur. Le géocodeur inversé renvoie n'importe lequel de ces types comme des résultats valides.

Le géocodeur inversé fait correspondre les entités politiques (pays, provinces, villes et quartiers), les adresses postales et les codes postaux.

La liste complète des valeurs formatted_address renvoyées par la requête précédente est affichée ci-dessous.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

Les adresses sont généralement renvoyées de la plus précise à la moins précise ; l'adresse la plus précise est le résultat le plus mis en avant, comme le montre notre exemple. Notez que nous renvoyons différents types d'adresse, de l'adresse postale la plus précise, aux entités politiques les moins précises comme les quartiers, les villes, les départements, etc. Pour obtenir un type d'adresse spécifique, voir la restriction des résultats par type.

Remarque : Le géocodage inversé fournit une estimation. Le géocodeur tente de trouver l'adresse la plus proche avec une certaine tolérance. Si aucune correspondance n'est trouvée, le géocodeur ne renvoie aucun résultat.

Géocodage inversé pour un identifiant de lieu

La requête suivante contient l'identifiant de lieu pour un lieu à Brooklyn :

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

La requête ci-dessus renvoie le résultat suivant :

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Géocodage inversé limité par type

L'exemple suivant montre comment les adresses renvoyées sont limitées à celles contenant un type de lieu ROOFTOP et un type d'adresse street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Remarque : Ces restrictions ne sont valables que pour le géocodage inversé.

Réponses aux requêtes de géocodage inversé

Le format de la réponse de géocodage inversé est le même que celui d'une réponse de géocodage. Voir Réponses aux requêtes de géocodage. Vous trouverez ci-dessous les codes de statut possibles dans une réponse de géocodage inversé.

Codes de statut du géocodage inversé

Le champ "status" de l'objet de la réponse Geocoding contient le statut de la requête et peut contenir des informations de débogage qui vous aident à savoir pourquoi le géocodage inversé ne fonctionne pas. Le champ "status" peut contenir les valeurs suivantes :

  • "OK" indique qu'aucune erreur n'est survenue et qu'au moins une adresse a été trouvée.
  • "ZERO_RESULTS" indique que le géocodage inversé a réussi mais n'a renvoyé aucun résultat. Cela peut se produire si le géocodeur a reçu un paramètre latlng dans un lieu distant.
  • "OVER_QUERY_LIMIT" indique que vous avez dépassé votre quota.
  • "REQUEST_DENIED" indique que la requête a été refusée. Cela est possible si la requête inclut un paramètre result_type ou location_type mais ne contient pas de clé d'API ni d'ID client.
  • "INVALID_REQUEST" indique généralement l'un des motifs suivants :
    • Il manque un élément de la requête (address, components ou latlng).
    • Un paramètre result_type ou location_type invalide a été fourni.
  • "UNKNOWN_ERROR" indique que la requête n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Paramètre sensor

Google Maps API exigeait auparavant l'insertion du paramètre sensor pour savoir si votre application utilisait un capteur afin de déterminer la position géographique de l'utilisateur. Désormais, ce paramètre n'est plus obligatoire.

Envoyer des commentaires concernant…

Google Maps Geocoding API
Google Maps Geocoding API
Besoin d'aide ? Consultez notre page d'assistance.