Le terme geocoding désigne généralement la traduction d'une adresse lisible en un emplacement sur une carte. Le processus inverse, c'est-à-dire la conversion d'un emplacement sur la carte en une adresse lisible, est appelé geocoding inversé.
Requêtes de geocoding inversé
Paramètres obligatoires
latlng
: coordonnées de latitude et de longitude spécifiant l'emplacement pour lequel vous souhaitez obtenir l'adresse lisible la plus proche.key
: clé API de votre application. Cette clé permet d'identifier votre application pour la gestion des quotas. Découvrez comment obtenir une clé.
Paramètres facultatifs
Voici les paramètres facultatifs que vous pouvez inclure dans une demande de géocodage inversé :
language
: langue dans laquelle renvoyer les résultats.- Consultez la liste des langues disponibles. Google met souvent à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
- Si
language
n'est pas fourni, le géocodeur tente d'utiliser la langue préférée spécifiée dans l'en-têteAccept-Language
ou la langue maternelle du domaine à partir duquel la requête est envoyée. - Le géocodeur fait de son mieux pour fournir une adresse postale lisible pour l'utilisateur et les habitants. Pour ce faire, il renvoie les adresses postales dans la langue locale, translittérées dans un script lisible par l'utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue préférée. Tous les composants d'adresse sont renvoyés dans la même langue, qui est choisie à partir du premier composant.
- Si un nom n'est pas disponible dans la langue de votre choix, le géocodeur utilise la correspondance la plus proche.
region
: code régional, spécifié sous la forme d'une valeur ccTLD (domaine de premier niveau) à deux caractères. Le paramètre peut également affecter les résultats en fonction de la loi applicable.result_type
: filtre d'un ou plusieurs types d'adresses, séparés par une barre verticale (|
). Si le paramètre contient plusieurs types d'adresses, l'API renvoie toutes les adresses correspondant à l'un des types. Remarque sur le traitement : Le paramètreresult_type
ne limite pas la recherche au(x) type(s) d'adresse spécifié(s). Au lieu de cela,result_type
agit comme un filtre post-recherche : l'API récupère tous les résultats pour lelatlng
spécifié, puis supprime ceux qui ne correspondent pas au ou aux types d'adresse spécifiés. Les valeurs suivantes sont acceptées :Types d'adresses et de composants d'adresse
Le tableau
types
dans le corpsGeocodeResult
de la réponse indique le type d'adresse. Les types d'adresses incluent une adresse postale, un pays ou une entité politique. Le tableautypes
dans le champAddressComponents
du corpsGeocodeResult
indique le type de chaque partie de l'adresse. (un numéro de rue ou un pays, par exemple).Les adresses peuvent avoir plusieurs types. Les types peuvent être considérés comme des "tags". Par exemple, de nombreuses villes sont taguées avec les types
political
etlocality
.Les types suivants sont acceptés et renvoyés dans les tableaux de types d'adresse et de composant d'adresse :
Type d'adresse Description street_address
Adresse postale précise. route
Route nommée (par exemple, "US 101"). intersection
Intersection majeure, généralement sur deux routes principales. political
Entité politique. Habituellement, ce type indique un polygone de certaines administrations civiles. country
Entité politique nationale, généralement le type de premier ordre renvoyé par le Geocoder. administrative_area_level_1
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. Dans la plupart des cas, les noms courts administrative_area_level_1
correspondront fidèlement aux subdivisions ISO 3166-2 et aux autres listes largement diffusées. Cependant, cela n'est pas systématique, car nos résultats de géocodage se basent sur divers signaux et données de localisation.administrative_area_level_2
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
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
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
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. administrative_area_level_6
Entité civile de sixiè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_7
Entité civile de septiè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
Autre nom couramment utilisé pour l'entité. locality
Entité politique de ville ou de municipalité incorporée. sublocality
Entité civile de premier ordre située en dessous d'une localité. Pour certains établissements, vous pouvez 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
Quartier nommé. premise
Lieu nommé, généralement un bâtiment ou un ensemble de bâtiments ayant un nom commun. subpremise
Entité adressable en dessous du niveau de l'établissement, comme un appartement, un logement ou une suite. plus_code
Référence de lieu encodée, déterminée par la latitude et la longitude. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés). Pour en savoir plus, consultez https://plus.codes. postal_code
Code postal, utilisé pour adresser le courrier postal dans le pays. natural_feature
Un élément naturel important. airport
Un aéroport. park
Parc nommé. point_of_interest
Point d'intérêt nommé. En général, ces "POI" sont des entités locales importantes qui ne correspondent à aucune autre catégorie, comme "Empire State Building" ou "Tour Eiffel". 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).
location_type
: filtre d'un ou plusieurs types de lieux, séparés par une barre verticale (|
). Si le paramètre contient plusieurs types de lieux, l'API renvoie toutes les adresses correspondant à l'un des types. Remarque concernant le traitement : Le paramètrelocation_type
ne limite pas la recherche aux types de lieux spécifiés. Au contraire,location_type
agit comme un filtre post-recherche : l'API récupère tous les résultats pour lelatlng
spécifié, puis supprime ceux qui ne correspondent pas aux types de lieux spécifiés. Les valeurs suivantes sont acceptées :"ROOFTOP"
ne renvoie que les adresses pour lesquelles Google dispose d'informations de localisation précises au niveau de l'adresse postale."RANGE_INTERPOLATED"
ne renvoie que les adresses qui reflètent une approximation (généralement sur une route) interpolée entre deux points précis (des intersections, par exemple). Une plage interpolée indique généralement que le geocoding rooftop n'est pas disponible pour une adresse postale."GEOMETRIC_CENTER"
ne renvoie que les centres géométriques d'un lieu, comme une polyligne (par exemple, une rue) ou un polygone (une région)."APPROXIMATE"
ne renvoie que les adresses caractérisées comme approximatives.
extra_computations
: utilisez ce paramètre pour spécifier les fonctionnalités supplémentaires suivantes dans la réponse :ADDRESS_DESCRIPTORS
: pour en savoir plus, consultez Descripteurs d'adresses.BUILDING_AND_ENTRANCES
: pour en savoir plus, consultez Entrées et contours de bâtiments.
extra_computations
dans la requête pour chaque fonctionnalité, par exemple :extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Si les filtres result_type
et location_type
sont tous les deux présents, l'API ne renvoie que les résultats qui correspondent aux valeurs result_type
et location_type
. Si aucune des valeurs de filtre n'est acceptable, l'API renvoie ZERO_RESULTS
.
Exemple de geocoding inversé
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
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 <code>results[]</code> ...
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 geocoding 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 geocoder. Le geocoder inversé renvoie l'un de ces types comme résultat valide.
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 présentée ci-dessous.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
Cette API renvoie différents types d'adresses, de l'adresse postale la plus précise aux entités politiques les moins précises comme les quartiers, les villes, les départements et les États. L'adresse la plus précise est généralement le résultat le plus mis en avant, comme le montre notre exemple. Si vous souhaitez trouver un type d'adresse spécifique, consultez la section ci-dessous sur la limitation des résultats par type. Par conséquent, l'emplacement des résultats les uns par rapport aux autres peut varier.
Geocoding inversé filtré par type
L'exemple suivant filtre les adresses renvoyées pour n'inclure que celles dont le type de lieu est ROOFTOP
et le type d'adresse est 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 filtres ne sont valides que pour le geocoding inversé.
Réponses de geocoding inversé
Le format de la réponse de géocodage inversé est le même que celui de la réponse de géocodage. Consultez Réponses aux requêtes de geocoding. Vous trouverez ci-dessous les codes de statut possibles dans une réponse de géocodage inversé.
Codes d'état du géocodage inversé
Le champ "status"
de l'objet de réponse du géocodage contient l'état de la requête et peut contenir des informations de débogage pour vous aider à comprendre pourquoi le géocodage inversé ne fonctionne pas. Le champ "status"
peut contenir les valeurs suivantes :
"OK"
indique qu'aucune erreur ne s'est produite et qu'au moins une adresse a été renvoyée."ZERO_RESULTS"
indique que le géocodage inversé a abouti, mais n'a renvoyé aucun résultat. Cela peut se produire si le geocoder a reçu unlatlng
dans un emplacement distant."OVER_QUERY_LIMIT"
indique que vous avez dépassé votre quota."REQUEST_DENIED"
indique que la demande a été refusée. Cela peut être dû au fait que la requête inclut un paramètreresult_type
oulocation_type
, mais pas de clé API."INVALID_REQUEST"
indique généralement l'un des éléments suivants :- La requête (
address
,components
oulatlng
) est manquante. - Une valeur
result_type
oulocation_type
non valide a été fournie.
- 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.
Geocoding inversé des Plus Codes
Le champ plus_code
de la réponse de géocodage contient un plus code qui correspond le mieux à la latitude et à la longitude demandées.
De plus, le tableau de résultats JSON contient dans la plupart des cas un résultat de géocodage complet avec un type plus_code
et une adresse contenant un code Plus. La distance entre le code Plus décodé et le point de requête est garantie inférieure à 10 mètres.