Les réponses issues d'une requête de géocodage sont retournées dans le format indiqué par la valeur du paramètre output placé dans l'URL de la requête.
Réponse au format JSON
Dans cet exemple, on souhaite que la requête pour géocoder l'adresse 'rue Bretonneau, 37000, Tours, FR' fournisse une réponse au format json :
http://maps.googleapis.com/maps/api/geocode/json?address=rue+bretonneau,+37000,+tours,+FR&sensor=true_OU_false
Important : dans la requête ci-dessus Le paramètre sensor a été laissé volontairement avec la variable true_OU_false afin de souligner que vous devez définir impérativement cette valeur de façon explicite sur true ou sur false.
Le json retourné par cette requête est affiché ci-dessous. Notez
que le json réel peut contenir plus ou moins de caractères espace.
Vous ne devez pas faire de suppositions sur la quantité ou le format des espaces
entre les requêtes.
/**
* Requête envoyée aux serveurs de Google :
*
* http://maps.googleapis.com/maps/api/geocode/json?address=rue+bretonneau,+37000,+tours,+FR&sensor=false
*
* Ci-dessous la réponse retournée au format json :
*
*/
{
"results" : [
{
"address_components" : [
{
"long_name" : "Rue du Docteur Bretonneau",
"short_name" : "Rue du Docteur Bretonneau",
"types" : [ "route" ]
},
{
"long_name" : "Tours",
"short_name" : "Tours",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Indre-et-Loire",
"short_name" : "37",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Centre",
"short_name" : "Centre",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "France",
"short_name" : "FR",
"types" : [ "country", "political" ]
},
{
"long_name" : "37000",
"short_name" : "37000",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Rue du Docteur Bretonneau, 37000 Tours, France",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 47.3958540,
"lng" : 0.68046010
},
"southwest" : {
"lat" : 47.39427310,
"lng" : 0.6802389999999999
}
},
"location" : {
"lat" : 47.39503870,
"lng" : 0.6803620
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 47.39821117068017,
"lng" : 0.6834971706801714
},
"southwest" : {
"lat" : 47.39191592931983,
"lng" : 0.6772019293198285
}
}
},
"partial_match" : true,
"types" : [ "route" ]
},
{
"address_components" : [
{
"long_name" : "Rue Bretonneau",
"short_name" : "Rue Bretonneau",
"types" : [ "route" ]
},
{
"long_name" : "Saint-Cyr-sur-Loire",
"short_name" : "Saint-Cyr-sur-Loire",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Indre-et-Loire",
"short_name" : "37",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Centre",
"short_name" : "Centre",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "France",
"short_name" : "FR",
"types" : [ "country", "political" ]
},
{
"long_name" : "37540",
"short_name" : "37540",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Rue Bretonneau, 37540 Saint-Cyr-sur-Loire, France",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 47.40127070,
"lng" : 0.65740570
},
"southwest" : {
"lat" : 47.3954730,
"lng" : 0.65596190
}
},
"location" : {
"lat" : 47.39822119999999,
"lng" : 0.65601820
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 47.40151947068016,
"lng" : 0.6598314206801714
},
"southwest" : {
"lat" : 47.39522422931982,
"lng" : 0.6535361793198285
}
}
},
"partial_match" : true,
"types" : [ "route" ]
}
],
"status" : "OK"
}
Notez que la réponse au format json contient deux éléments root :
"status": contient des métadonnées sur la requête. Voir : Codes d'état ci-dessous."results": contient un tableau contenant des informations sur les adresse géocodées et des informations de type géométrique.
En général, une seule entrée dans le tableau "results" est retournée
pour des recherches d'adresse, cependant le géocodeur peut retourner plusieurs
résultats lorsque les requêtes d'adresse sont ambigües.
Notez que généralement ces résultats doivent être analysés si vous souhaitez
extraire des valeurs du résultat. Analyser des données au format json
est relativement facile. Voir : Parsing
JSON.
Réponse au format XML
Dans cet exemple, on souhaite que la requête pour géocoder l'adresse 'rue Bretonneau,
37000, Tours, FR' fournisse une réponse au format xml :
http://maps.googleapis.com/maps/api/geocode/xml?address=rue+bretonneau,+37000,+tours,+FR&sensor=true_OU_false
Important : dans la requête ci-dessus Le paramètre sensor a été laissé volontairement avec la variable true_OU_false afin de souligner que vous devez définir impérativement cette valeur de façon explicite sur true ou sur false.
Le xml retourné par cette requête est affiché ci-dessous.
/** * Requête envoyée aux serveurs de Google : * * http://maps.googleapis.com/maps/api/geocode/xml?address=rue+bretonneau,+37000,+tours,+FR&sensor=false * * Ci-dessous la réponse retournée au format xml : * */ <?xml version="1.0" encoding="UTF-8"?> <GeocodeResponse> <status>OK</status> <result> <type>route</type> <formatted_address>Rue du Docteur Bretonneau, 37000 Tours, France</formatted_address> <address_component> <long_name>Rue du Docteur Bretonneau</long_name> <short_name>Rue du Docteur Bretonneau</short_name> <type>route</type> </address_component> <address_component> <long_name>Tours</long_name> <short_name>Tours</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Indre-et-Loire</long_name> <short_name>37</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>Centre</long_name> <short_name>Centre</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>France</long_name> <short_name>FR</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>37000</long_name> <short_name>37000</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>47.3950387</lat> <lng>0.6803620</lng> </location> <location_type>GEOMETRIC_CENTER</location_type> <viewport> <southwest> <lat>47.3919159</lat> <lng>0.6772019</lng> </southwest> <northeast> <lat>47.3982112</lat> <lng>0.6834972</lng> </northeast> </viewport> <bounds> <southwest> <lat>47.3942731</lat> <lng>0.6802390</lng> </southwest> <northeast> <lat>47.3958540</lat> <lng>0.6804601</lng> </northeast> </bounds> </geometry> <partial_match>true</partial_match> </result> <result> <type>route</type> <formatted_address>Rue Bretonneau, 37540 Saint-Cyr-sur-Loire, France</formatted_address> <address_component> <long_name>Rue Bretonneau</long_name> <short_name>Rue Bretonneau</short_name> <type>route</type> </address_component> <address_component> <long_name>Saint-Cyr-sur-Loire</long_name> <short_name>Saint-Cyr-sur-Loire</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Indre-et-Loire</long_name> <short_name>37</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>Centre</long_name> <short_name>Centre</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>France</long_name> <short_name>FR</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>37540</long_name> <short_name>37540</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>47.3982212</lat> <lng>0.6560182</lng> </location> <location_type>GEOMETRIC_CENTER</location_type> <viewport> <southwest> <lat>47.3952242</lat> <lng>0.6535362</lng> </southwest> <northeast> <lat>47.4015195</lat> <lng>0.6598314</lng> </northeast> </viewport> <bounds> <southwest> <lat>47.3954730</lat> <lng>0.6559619</lng> </southwest> <northeast> <lat>47.4012707</lat> <lng>0.6574057</lng> </northeast> </bounds> </geometry> <partial_match>true</partial_match> </result> </GeocodeResponse>
Notez que la réponse xml est constituée d'un seul élément <GeocodeResponse> et de deux éléments de haut niveau :
<status>qui contient des métadonnées sur la requête. Voir : Codes d'état ci-dessous.- Zéro, un ou plusieurs éléments
<result>,contenantchacun un ensemble unique d'informations sur les adresse géocodées et des informations de type géométrique.
Notez que cette réponse est beaucoup plus longue que la réponse json.
Pour cette raison, il est recommandé d'utiliser de façon préférentielle le format
json, sauf si votre application nécessite le format xml
pour une raison quelconque. En outre, le traitement d'un arbre xml
nécessite une certaine attention, afin que vous fassiez référence aux nœuds
et éléments appropriés. Voir : analyse
XML avec XPath.
json. Dans
la plupart des cas, le format de sortie n'a pas d'importance à des fins d'illustration
de concepts ou noms de champs dans la documentation. Toutefois, notez les différences
subtiles suivantes :- les résultats
xmlsont enveloppés dans un élément racine<GeocodeResponse>. jsonreprésente les entrées avec plusieurs éléments sous forme de tableaux comportant plusieurs données (types), tandis quexmlles représente à l'aide de plusieurs éléments distincts (<type>).- Les éléments vides sont indiqués sous forme de tableaux vides dans
json, mais par l'absence d'un tel élément dansxml. Par exemple une réponse qui ne génère pas de résultats retournera un tableauresultsvide avecjson, mais aucun élément<result>avecxml.
Codes d'état
Le champ <status> dans l'objet réponse fournit par le géocodeur contient
le statut de la requête, et peut contenir des informations importantes pour vous
aider à traquer les bugs et dysfonctionnements liés au géocodage. Le champ <status>
peut contenir les valeurs suivantes :
"OK": aucune erreur ne s'est produite, l'adresse a été analysée avec succès et au moins un résultat a été retourné."ZERO_RESULTS": le géocodage a réussi, mais il ne comporte aucun résultat. Cela peut se produire lorsqu'une adresseaddressinexistante ou lelatlngdans un endroit éloigné a été pass au géocodeur."OVER_QUERY_LIMIT": vous avez dépassé votre quota."REQUEST_DENIED": votre requête a été refusée, généralement en raison de l'absence du paramètresensor."INVALID_REQUEST": la requête (addressoulatlng) est manquante.
Résultats
Lorsque les résultats du géocodeur sont retournés, ils sont placés dans un
tableau (json) results. Même si le géocodeur ne retourne
aucun résultat (si l'adresse n'existe pas par exemple), il retournera toujours
un tableau vide results . (Les réponses xml sont composées
de zéro, un ou plusieurs éléments <result>.).
Un résultat typique est composé des champs suivants :
- Les tableaux
types[]indiquent le type du résultat retourné. Ce tableau contient un ensemble d'une ou plusieurs étiquettes identifiant le type d'entité retournée dans le résultat. Par exemple, le géocodage de "Chicago" retourne "locality" qui indique que "Chicago" est une ville, et retourne également "political" qui indique qu'il s'agit d'une entité politique. formatted_addressest une chaîne contenant l'adresse, lisible par l'homme, de cet emplacement. Souvent, cette adresse est équivalente à l'"adresse postale", qui diffère parfois d'un pays à l'autre. Notez que certains pays, tels que le Royaume-Uni, ne permettent pas la distribution des véritables adresses postales en raison de restrictions de licence. Cette adresse est généralement composée d'un ou plusieurs composant adresse address components. Par exemple, l'adresse "111, 8e Avenue, New York, NY" contient des composants adresse distincts pour :- "111" (le numéro de rue),
- "8th Avenue" (la route),
- "New York" (la ville),
- "NY" ( le nom de l'état aux USA).
address_components[]est un tableau contenant les éléments d'adressage différents, comme expliqué ci-dessus. Chaqueaddress_componentcontient généralement :types[]: tableau indiquant le type de la composante adresse.long_name: description intégrale ou nom de la composante adresse renvoyée par le géocodeur.short_name: nom abrégé de la composante adresse, le cas échéant. Par exemple, le composant adresse pour l'État de l'Alaska peut avoir un nom longlong_nameégal à "Alaska" et un nom courtshort_nameégal à "AK" utilisant l'abréviation postale à 2 lettres.
address_components[]peut contenir plus de composants adresse qu'indiqué dansformatted_address.geometrycontient les informations suivantes :locationcontient les latitude et longitude géocodées. Pour les recherches d'adresse classiques, 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 prises en charge :"ROOFTOP": le résultat retourné est un géocodage précis pour lequel Google dispose d'informations dont la précision se situe au niveau de l'adresse postale."RANGE_INTERPOLATED": le résultat retourné reflète une approximation (généralement sur une route) par interpolation entre deux points précis (tels que des intersections). Les résultats interpolés sont généralement retournés lorsque le géocodage rooftop est indisponible pour une adresse de rue."GEOMETRIC_CENTER": le résultat retourné est le centre géométrique d'une polyline ( une rue par exemple ) ou d'un polygone ( région )."APPROXIMATE": le résultat retourné est approximatif.
viewport: contient la zone de visualisation recommandée pour l'affichage du résultat retourné, précisée sous la forme de deux couples latitude, longitude définissant le coin Sud-Ouestsouthwestet le coin Nord-Estnortheastdu rectangle englobant la zone de visualisation. Généralement, la zone de visualisation est utilisée pour encadrer un résultat lorsqu'il doit être affiché pour un utilisateur.bounds: (éventuellement retourné) stocke les limites du cadre capable de contenir entièrement le résultat retourné. Notez que ces limites peuvent ne pas correspondre à la zone de visualisation recommandée. (Par exemple, San Francisco comprend les îles Farallon, qui font partie techniquement de la ville, mais qui ne devront probablement pas être affichées dans la zone de visualisation.)partial_match: le géocodeur n'a pas retourné une correspondance exacte pour la requête initiale, si elle ne correspond pas à une partie de l'adresse demandée. Vous pouvez souhaiter examiner la requête initiale pour les fautes d'orthographe et / ou une adresse incomplète. Les correspondances partielles se produisent le plus souvent pour des adresses de rues qui n'existent pas dans la localité que vous avez passée dans la requête.
Comme le format exact d'une réponse individuelle à une requête de géocodage
n'est pas garanti, vous ne devriez jamais supposer que les éléments sont positionnés
de façon absolue. En particulier, le nombre d' address_components
au sein d'une réponse au géocodage varie en fonction de l'adresse demandée et
peut changer au fil du temps. Au lieu de cela, vous devez analyser
la réponse et sélectionner les valeurs appropriées via des
expressions. Voir Analyser les réponses du Web Service
pour plus d'informations.
Types de composants Adresse
Les tableau types[] dans le résultat retourné indique le type
d'adresse. Ces types peuvent également être retournés dans les tableaux
address_components[] pour indiquer le type d'un composant adresse
particulier. Les adresses dans le géocodeur peuvent avoir plusieurs types; les
types peuvent être considérés comme des "tags" (ou "étiquettes").
Par exemple, de nombreuses villes sont étiquetées avec les types political
et locality.
Les types suivants sont pris en charge et renvoyé par le Geocodeur HTTP :
street_address: indique une adresse préciseroute: indique une route nommée (exemple : N7)intersection: indique une intersection majeure, habituellement de deux routes principales.political: indique une entité politique. Habituellement, ce type indique un polygone de certaines administrations civiles.country: indique l'entité politique national, et est typiquement le type de premier ordre renvoyé par le géocodeur.administrative_area_level_1: indique une entité civile de premier ordre située en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs sont représentés par les états. Toutes les nations ne disposent de ces niveaux administratifs.administrative_area_level_2: indique une entité civile de second ordre située en dessous du niveau du pays. Aux États-Unis, ces niveaux administratifs sont représentés par les comtés. Toutes les nations ne disposent de ces niveaux administratifs.administrative_area_level_3: indique une troisième entité civile située en dessous du niveau du pays. Ce type indique une division civile mineure. Toutes les nations ne disposent de ces niveaux administratifs.colloquial_area: indique un nom alternatif couramment utilisé pour l'entité.locality: indique une cité ou une ville.sublocality: indique une entité civile de premier ordre située en dessous de la localité.neighborhood: indique un nom de quartier.premise: indique un emplacement nommé, généralement un bâtiment ou un ensemble de bâtiments avec un nom commun.subpremise: indique une entité de premier ordre située en dessous d'un emplacement nommé, généralement un bâtiment singulier dans un ensemble de bâtiments avec un nom commun.postal_code: indique un code postal.natural_feature: indique une caractéristique naturelle importante.airport: indique un aéroport.park: indique un parcpoint_of_interest: indique un point d'intérêt particulier. Généralement, ces "POI" sont des entités locales de premier plan qui ne s'insèrent pas facilement dans une autre catégorie telle que "l'Empire State Building" ou "La statue de la Liberté."
En plus de ce qui précède, les composants adresse peuvent comporter les types suivants :
post_box: indique une boîte postale spécifique.street_number: indique de façon précise le numéro de la rue.floor: indique l'étage, pour une adresse d'immeuble.room: indique l'appartement, pour une adresse d'immeuble.