Requête
Une requête API Geocoding se présente sous la forme suivante :
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
où outputFormat peut avoir l'une des valeurs suivantes :
json(recommandé) indique la sortie au format JSON (JavaScript Object Notation) ; ouxmlindique une sortie au format XML.
HTTPS est obligatoire.
Certains paramètres sont obligatoires, tandis que d'autres sont facultatifs. Comme c'est la norme pour les URL, les différents paramètres sont séparés par une esperluette (&).
Le reste de cette page décrit le geocoding et le geocoding inversé séparément, car différents paramètres sont disponibles pour chaque type de requête.
Paramètres de géocodage (recherche de latitude/longitude)
Paramètres requis dans une requête de géocodage :
key: clé API de votre application. Cette clé permet d'identifier votre application pour la gestion des quotas. Découvrez comment obtenir une clé.Vous devez spécifier
address,componentsou les deux dans une requête :address: adresse ou plus code que vous souhaitez géocoder. Indiquez les adresses au format utilisé par le service postal du pays concerné. Évitez d'ajouter des éléments d'adresse supplémentaires, comme le nom de l'entreprise, ou les numéros d'unité, de bureau ou d'étage. Les éléments d'adresse postale doivent être délimités par des espaces (ici, ils sont échappés en URL pour donner%20) :address=24%20Sussex%20Drive%20Ottawa%20ON
%2B, et les espaces avec une URL en%20) :- Le code global est un indicatif de zone de 4 caractères et un code local à 6 caractères ou plus (849VCWC8+R9 correspond à
849VCWC8%2BR9). - Le code composé est un code local à six caractères ou plus associé à un emplacement explicite (CWC8+R9 Mountain View, CA, États-Unis correspond à
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- Le code global est un indicatif de zone de 4 caractères et un code local à 6 caractères ou plus (849VCWC8+R9 correspond à
components: filtre de composants dont les éléments sont séparés par une barre verticale (|). Le filtre de composants est également accepté en tant que paramètre facultatif si unaddressest fourni. Chaque élément du filtre de composants se compose d'une pairecomponent:valueet limite totalement les résultats du geocoder. Pour en savoir plus sur le filtrage des composants, consultez la section ci-dessous.
Pour en savoir plus, consultez les questions fréquentes.
Paramètres facultatifs dans une requête de géocodage :
bounds: cadre de délimitation de la fenêtre d'affichage dans lequel pondérer les résultats du geocoding de manière plus proéminente. Ce paramètre ne fera qu'influer sur les résultats du geocoder, sans les limiter totalement. (Pour en savoir plus, consultez Pondération de la fenêtre d'affichage ci-dessous.)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
languagen'est pas fourni, le géocodeur tente d'utiliser la langue préférée spécifiée dans l'en-têteAccept-Languageou 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.
- La langue préférée a une faible influence sur l'ensemble des résultats que l'API choisit de renvoyer, ainsi que sur l'ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, comme les abréviations des types de rues ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre. Par exemple, utca et tér sont des synonymes de "rue" et "place", respectivement, en hongrois.
region: code régional, spécifié sous la forme d'une valeur ccTLD (domaine de premier niveau) à deux caractères. Ce paramètre ne fera qu'influer sur les résultats du geocoder, sans les limiter totalement. (Pour en savoir plus, consultez Ajuster l'itinéraire en fonction de la région ci-dessous.) Le paramètre peut également affecter les résultats en fonction de la loi applicable.components: filtre de composants dont les éléments sont séparés par une barre verticale (|). Le filtre de composants est obligatoire si la requête n'inclut pas deaddress. Chaque élément du filtre de composants se compose d'une pairecomponent:valueet limite totalement les résultats du geocoder. Pour en savoir plus sur le filtrage des composants, consultez la section ci-dessous.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_computationsdans la requête pour chaque fonctionnalité, par exemple :extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Réponses
Les réponses de géocodage sont renvoyées dans le format indiqué par l'indicateur output dans la requête d'URL ou au format JSON par défaut.
Dans cet exemple, l'API Geocoding demande une réponse json pour une requête sur l'adresse "1600 Amphitheatre Parkway, Mountain View, CA".
Cette requête montre comment utiliser l'indicateur JSON output :
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Cette requête montre comment utiliser l'option XML output :
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Sélectionnez les onglets ci-dessous pour afficher les exemples de réponses JSON et XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "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. Consultez les codes d'état ci-dessous."results"contient un tableau d'informations sur les adresses géocodées et des informations sur la géométrie.
En règle générale, une seule entrée du tableau "results" est renvoyée pour les recherches d'adresses. Toutefois, le géocodeur peut renvoyer plusieurs résultats lorsque les requêtes d'adresses sont ambiguës.
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 Parkway</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>Santa Clara County</long_name> <short_name>Santa Clara County</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.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Notez que la réponse XML se compose d'un seul <GeocodeResponse> et de deux éléments de premier niveau :
<status>contient des métadonnées sur la requête. Consultez la section Codes d'état ci-dessous.- Zéro ou plusieurs éléments
<result>, chacun contenant un seul ensemble d'informations d'adresse géocodées et d'informations de géométrie.
La réponse XML est beaucoup plus longue que la réponse JSON. C'est pourquoi nous vous recommandons d'utiliser json comme indicateur de sortie préféré, sauf si votre service nécessite xml pour une raison quelconque.
De plus, le traitement des arborescences XML nécessite une certaine attention pour que vous fassiez référence aux nœuds et éléments appropriés. Consultez
Analyser du code XML avec XPath pour découvrir des modèles de conception recommandés pour le traitement des résultats.
- Les résultats XML sont encapsulés dans un élément racine
<GeocodeResponse>. - JSON indique les entrées comportant plusieurs éléments par des tableaux au pluriel (
types), tandis que XML les indique à l'aide de plusieurs éléments au singulier (<type>). - Les éléments vides sont indiqués par des tableaux vides en JSON, mais par l'absence de tout élément de ce type en XML. Une réponse qui ne génère aucun résultat renverra un tableau
resultsvide au format JSON, mais aucun élément<result>au format XML, par exemple.
Codes d'état
Le champ "status" de l'objet de réponse Geocoding contient l'état de la requête et peut contenir des informations de débogage pour vous aider à comprendre pourquoi le géocodage ne fonctionne pas. Le champ "status" peut contenir les valeurs suivantes :
"OK"indique qu'aucune erreur ne s'est produite, que l'adresse a bien été analysée et qu'au moins un geocode a été renvoyé."ZERO_RESULTS"indique que le géocode a abouti, mais n'a renvoyé aucun résultat. Cela peut se produire si le geocoder a reçu unaddressinexistant.OVER_DAILY_LIMITindique l'un des éléments suivants :- La clé API est manquante ou non valide.
- La facturation n'a pas été activée sur votre compte.
- La limite d'utilisation que vous avez définie vous-même a été dépassée.
- Le mode de facturation fourni n'est plus valide (une carte de crédit est arrivée à expiration, par exemple).
Consultez les questions fréquentes sur Maps pour savoir comment résoudre ce problème.
"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 que la requête (address,componentsoulatlng) est manquante."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 geocoder renvoie un code d'état autre que OK, un champ error_message supplémentaire peut figurer dans l'objet de réponse Geocoding. Ce champ contient des informations plus détaillées sur les raisons du code d'état donné.
Résultats
Lorsque le géocodeur renvoie des résultats, il les place dans un tableau results (JSON). Même si le géocodeur ne renvoie aucun résultat (par exemple, si l'adresse n'existe pas), il renvoie toujours un tableau results vide. (Les réponses XML se composent d'un ou plusieurs éléments <result>.)
Un résultat type contient 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 signifie que "Chicago" est une ville, et "political", qui indique qu'il s'agit d'une entité politique. Les composants peuvent avoir un tableau de types vide lorsqu'il n'y a aucun type connu pour ce composant d'adresse. L'API peut ajouter de nouvelles valeurs de type si nécessaire. Pour en savoir plus, consultez Types d'adresses et composants d'adresse. formatted_addressest une chaîne contenant l'adresse lisible de ce lieu.Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.
L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).
N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.
address_components[]est un tableau contenant les composants distincts applicables à cette adresse.Chaque composant d'adresse contient généralement les champs suivants :
types[]est un tableau indiquant le type du composant d'adresse. Consultez la liste des types compatibles.long_nameest la description complète ou le nom du composant d'adresse renvoyé par le geocoder.short_nameest un nom textuel abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'Alaska peut avoir "Alaska" commelong_nameet "AK" commeshort_name, correspondant à l'abréviation postale de deux lettres.
Notez les informations suivantes concernant le tableau
address_components[]:- Le tableau de composants d'adresse peut contenir
formatted_addresset des composants supplémentaires. - Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans
formatted_address. Pour récupérer toutes les entités politiques contenant une adresse spécifique, vous devez utiliser le geocoding inversé, en transmettant à la requête la latitude/longitude de l'adresse en tant que paramètre. - Le format de la réponse ne sera peut-être pas le même d'une requête à l'autre. En particulier, le nombre d'
address_componentsvarie selon l'adresse demandée et peut changer au fil du temps pour la même adresse. Un composant peut changer de position dans le tableau. Le type du composant peut changer. Un composant particulier peut être manquant dans une réponse ultérieure.
Pour gérer le tableau de composants, vous devez analyser la réponse et sélectionner les valeurs appropriées à l'aide d'expressions. Consultez le guide sur l' analyse d'une réponse.
postcode_localities[]est un tableau indiquant jusqu'à 100 localités contenues dans un code postal. Il ne s'affiche que lorsque le résultat est un code postal contenant plusieurs localités.geometrycontient les informations suivantes :locationcontient la valeur latitude, longitude géocodée. Pour les recherches d'adresses normales, ce champ est généralement le plus important.location_typestocke des données supplémentaires sur l'emplacement spécifié. Les valeurs suivantes sont actuellement acceptées :"ROOFTOP"indique que le résultat renvoyé est un geocode précis pour lequel nous disposons d'informations de localisation précises au niveau de l'adresse postale."RANGE_INTERPOLATED"indique que le résultat renvoyé reflète une approximation (généralement sur une route) interpolée entre deux points précis (des intersections, par exemple). Les résultats interpolés sont généralement renvoyés lorsque le geocoding 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 un polygone (une région)."APPROXIMATE"indique que le résultat renvoyé est approximatif.
viewportcontient la fenêtre d'affichage recommandée pour afficher le résultat renvoyé, spécifiée sous la forme de deux valeurs de latitude et de longitude définissant les coinssouthwestetnortheastdu cadre de délimitation de la fenêtre d'affichage. En général, la fenêtre d'affichage est utilisée pour encadrer un résultat lorsqu'il est présenté à un utilisateur.bounds(facultatif) stocke le cadre englobant qui peut contenir le résultat renvoyé dans son ensemble. Notez que ces limites peuvent ne pas correspondre à la fenêtre d'affichage recommandée. (Par exemple, San Francisco inclut les îles Farallon, qui font techniquement partie de la ville, mais ne devraient probablement pas être renvoyées dans la fenêtre d'affichage.)
-
plus_code: (voir Open Location Code et Plus Codes) référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. 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). L'API ne renvoie pas toujours de codes Plus.Lorsque le service renvoie un Plus Code, il est mis en forme comme un code global et un code composé :
global_codeest un indicatif de zone à 4 caractères et un code local à 6 caractères ou plus (849VCWC8+R9).compound_codeest un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
-
partial_matchindique que le geocoder n'a pas renvoyé de correspondance exacte pour la requête d'origine, bien qu'il ait 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, "Hillpar St, Bristol, UK" renvoie une correspondance partielle pour Henry Street et Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de geocoding peut suggérer une autre adresse. Les suggestions déclenchées de cette façon sont également signalées comme des correspondances partielles.
place_idest un identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliserplace_iddans une requête Places API pour obtenir des informations sur un établissement local, comme son numéro de téléphone, ses horaires d'ouverture, les avis des utilisateurs, etc. Consultez la présentation des ID de lieu.
Types d'adresses et de composants d'adresse
Le tableau types de la réponse indique le type d'adresse. Les types d'adresses incluent une adresse postale, un pays ou une entité politique. Le tableau types dans le champ address_component 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 et locality.
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).
En plus des types énumérés ci-dessus, les composants d'adresse peuvent contenir les types suivants.
| Type de composant d'adresse | Description |
|---|---|
floor |
Étage d'une adresse d'immeuble. |
establishment |
Il s'agit généralement d'un lieu qui n'a pas encore été classé. |
landmark |
Un lieu à proximité qui sert de référence pour faciliter la navigation. |
point_of_interest |
Point d'intérêt nommé. |
parking |
Un parking ou un espace de stationnement. |
post_box |
Une boîte postale spécifique. |
postal_town |
Groupe de zones géographiques, comme locality et sublocality, utilisé pour les adresses postales dans certains pays. |
room |
Salle associée à l'adresse d'un bâtiment. |
street_number |
Numéro de rue précis. |
bus_station, train_station et transit_station |
Emplacement d'un arrêt de bus, de train ou de transports 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 de délimitation). Pour ce faire, définissez le paramètre bounds dans l'URL de la requête.
Le paramètre bounds définit les coordonnées de latitude/longitude des angles sud-ouest et nord-est de ce cadre de sélection à l'aide d'un caractère pipe (|) pour séparer les coordonnées.
Par exemple, un geocode pour "Washington" renvoie généralement l'État américain de Washington :
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Toutefois, si vous ajoutez un argument bounds définissant un cadre de délimitation autour de la partie nord-est des États-Unis, le geocoding renvoie la ville de Washington, D.C. :
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Pondération de la région
Dans une requête Geocoding, vous pouvez demander au service Geocoding de renvoyer des résultats pondérés en faveur d'une région en particulier à l'aide du paramètre region. Ce paramètre accepte un argument ccTLD (domaine national de premier niveau) qui spécifie le biais régional. 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" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord").
Les résultats du geocoding peuvent être biaisés pour chaque domaine dans lequel l'application Google Maps principale est officiellement lancée. Notez que la pondération ne fait que privilégier les résultats d'un domaine spécifique. Si des résultats plus pertinents existent en dehors de ce domaine, ils peuvent être inclus.
Par exemple, un geocode pour "Toledo" renvoie le résultat suivant, car le domaine par défaut de l'API Geocoding est défini sur les États-Unis. Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Response:
{
"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.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Une requête de géocodage pour "Toledo" avec region=es (Espagne) renverra la ville espagnole.
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "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, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtrage des composants
Dans une réponse de géocodage, l'API Geocoding peut renvoyer des résultats d'adresse limités à une zone spécifique. Vous pouvez spécifier la restriction à l'aide du filtre components. Un filtre se compose d'une liste de paires component:value séparées par une barre verticale (|). Les valeurs de filtre sont compatibles avec les mêmes méthodes de correction orthographique et de correspondance partielle que les autres requêtes de géocodage. Si le géocodeur trouve une correspondance partielle pour un filtre de composant, la réponse contiendra un champ partial_match.
Voici les components que vous pouvez filtrer :
postal_codecorrespond àpostal_codeetpostal_code_prefix.country, qui correspond à un nom de pays ou à un code pays ISO 3166-1 à deux lettres. L'API respecte la norme ISO pour la définition des pays. Le filtrage fonctionne mieux lorsque vous utilisez le code ISO correspondant du pays.
Les components suivants peuvent être utilisés pour influencer les résultats, mais ne seront pas appliqués :
route, qui correspond au nom long ou court d'une route.localitycorrespond aux typeslocalityetsublocality.administrative_area, qui correspond à tous les niveauxadministrative_area.
Remarques sur le filtrage des composants :
- Ne répétez pas ces filtres de composants dans les requêtes, sinon l'API renverra
Invalid_request:country,postal_code,route. - Si la requête contient des filtres de composants répétés, l'API évalue ces filtres comme un opérateur AND, et non OR.
- Les résultats sont cohérents avec Google Maps, qui fournit parfois des réponses
ZERO_RESULTSinattendues. L'utilisation de Place Autocomplete peut fournir de meilleurs résultats dans certains cas d'utilisation. Pour en savoir plus, consultez ces questions fréquentes. - Pour chaque composant d'adresse, spécifiez-le dans le paramètre
addressou dans un filtrecomponents, mais pas les deux. Si vous spécifiez les mêmes valeurs dans les deux, cela peut entraînerZERO_RESULTS.
Un geocode pour "High St, Hastings" avec components=country:GB renvoie un résultat à Hastings, en Angleterre, plutôt qu'à Hastings-On-Hudson, aux États-Unis.
Requête :
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Une requête de geocoding pour la localité "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?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Response:
{
"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" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "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"
}
Le filtrage des composants ne renvoie une réponse ZERO_RESULTS que si vous fournissez 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
Response:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Vous pouvez créer des requêtes valides sans le paramètre d'adresse, en utilisant le filtre components. (Lorsque vous géocodez une adresse complète, le paramètre address est obligatoire si la requête contient les noms et les numéros des bâtiments.)
Requête :
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Response:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}