Réponse transmise par le géocodeur au format JSON ou XML

API Google Geocoding exemples et tutoriels en Français

Cartographie et webmapping

Partager ce tutoriel sur les réseaux sociaux
Signaler une erreur dans cet article

Définir le format de la réponse à une requête de géocodage

Les réponses issues d'une requête de géocodage sont retournées dans le format indiqué dans l'URL de la requête.

Deux formats sont possibles :

  • JSON :
    https://maps.googleapis.com/maps/api/geocode/json?{autres_paramètres}
  • XML :
    https://maps.googleapis.com/maps/api/geocode/xml?{autres_paramètres}

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 :

https://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 :
 */

https://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 comportant des informations sur les adresses géocodées ainsi que des informations géographiques.

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 :

https://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 :
 */

https://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>, contenant chacun 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 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.

Le reste de cette documentation utilise la syntaxe JSON.
Notez certaines différences entre les deux formats :
  • les résultats XML sont enveloppés dans un élément racine <GeocodeResponse>.
  • JSON représente les entrées avec plusieurs éléments sous forme de tableaux comportant plusieurs données ( 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 dans JSON, mais par l'absence d'un tel élément dans XML. Par exemple une réponse qui ne génère pas de résultats retournera un tableau results vide avec JSON, mais aucun élément <result> avec XML.