Google Maps API Web Services

Google Maps Web Services regroupe des interfaces HTTP avec les services Google pour fournir des données géographiques à vos applications cartographiques. Ce guide ne fait que présenter les informations et services Web communs à tous les différents services. La documentation propre à chaque service est disponible ici :

Trouver l'API correspondant à vos besoins

Utilisez le sélecteur d'API pour trouver l'API adaptée à votre projet.

Informations supplémentaires sur les services Web

Le reste de ce guide aborde la configuration technique des requêtes de service Web et l'analyse des réponses. Cependant, pour des informations propres à chaque service, vous devez consulter la documentation appropriée.

Qu'est-ce qu'un service Web ?

Google Maps API fournit ces services Web sous la forme d'une interface qui permet de demander des données Maps API à des services externes et de les utiliser dans vos applications Maps. Conçus pour être utilisés avec une carte, ces services respectent les Restrictions des conditions de licence de Maps API.

Ces services Web utilisent des requêtes HTTP pour obtenir des URL spécifiques, en indiquant des paramètres URL comme arguments pour les services. En règle générale, ces services renvoient des données dans la requête HTTP au format JSON ou XML pour analyse et/ou traitement par votre application.

Généralement, une requête de service Web présente la forme suivante :

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

service indique le service spécifique interrogé et output le format de la réponse (généralement json ou xml).

Une documentation complète propre à chaque service est disponible dans les guides du développeur correspondant. Toutefois, ce guide contient des pratiques communes utiles pour configurer les requêtes de service Web et en traiter les réponses.

Accès SSL

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

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

Création d'une URL valide

Vous pensez peut-être qu'une URL « valide » est évidente, mais ce n'est pas toujours le cas. Une URL saisie dans la barre d'adresse d'un navigateur, par exemple, peut contenir des caractères spéciaux (exemple, "上海+中國") ; le navigateur doit alors convertir en interne ces caractères en un autre code avant l'envoi. Avec le même jeton, tout code qui génère ou accepte le format d'entrée UTF-8 peut considérer comme « valides » des URL contenant des caractères UTF-8 mais doit convertir ces caractères avant de les envoyer à un serveur Web. Ce processus est appelé encodage d'URL.

Nous devons convertir les caractères spéciaux car toutes les URL doivent respecter la syntaxe définie par la spécification W3 Uniform Resource Identifier. En fait, les URL doivent contenir un sous-ensemble spécifique de caractères ASCII (symboles alphanumériques courants), ainsi que des caractères réservés et utilisés comme caractères de commande dans les URL. Le tableau ci-dessous récapitule ces caractères :

Récapitulatif des caractères URL valides
JeuCaractèresUtilisation de l'URL
Alphanumérique a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 Chaînes de texte, utilisation de modèle (http), port (8080), etc.
Non réservé - _ . ~ Chaînes de texte
Réservé ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Caractères de commande et/ou chaînes de texte

Au moment de créer une URL valide, vous devez vérifier qu'elle contient uniquement les caractères ci-dessus. Vérifier qu'une URL utilise ce jeu de caractères permet généralement d'identifier deux problèmes : l'omission et le remplacement :

  • Les caractères que vous souhaitez utiliser ne figurent pas dans le tableau ci-dessus. Par exemple, les caractères d'une langue étrangère, tels que 上海+中國 doivent être encodés à l'aide des caractères ci-dessus. Selon une pratique courante, les espaces (qui ne sont pas autorisés dans les URL) sont souvent représentés à l'aide du caractère '+'.
  • Les caractères figurent dans le tableau ci-dessus comme des caractères réservés mais doivent être utilisés littéralement. Par exemple, ? est utilisé dans les URL pour indiquer le début de la chaîne de requête. Si vous utilisez la chaîne « ? and the Mysterions », vous devez encoder le caractère '?'.

Tous les caractères à encoder en URL le sont à l'aide du caractère '%' et d'une valeur hexadécimale à deux caractères correspondant à leur équivalent UTF-8. Par exemple, 上海+中國 en UTF-8 doit être encodé en URL comme suit :%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. La chaîne ? and the Mysterians doit être encodée en URL comme suit :%3F+and+the+Mysterians.

Certains caractères courants à encoder incluent :

Caractère non fiable Valeur encodée
Espace %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

Convertir une URL envoyée par un utilisateur est parfois difficile. Par exemple, un utilisateur peut saisir une adresse telle que « 5th&Main St. ». Généralement, vous devez créer votre URL à partir des éléments de cette adresse saisie, en traitant chaque entrée utilisateur comme des caractères littéraux.

En outre, les URL sont limitées à 2 048 caractères pour tous les services Web. Pour la plupart des services, cette limite de caractères est rarement atteinte. Toutefois, notez que certains services incluent plusieurs paramètres pouvant accroître la longueur des URL.

Traitement des réponses

Le format exact de chacune des réponses à une requête de service Web n'étant pas garanti (certains éléments peuvent manquer ou apparaître à plusieurs endroits), vous ne devez jamais considérer que le format d'une réponse donnée est identique pour toutes les requêtes. Vous devez donc traiter la réponse et sélectionner les valeurs appropriées via des expressions. Cette section explique comment extraire ces valeurs de manière dynamique à partir des réponses d'un service Web.

Google Web Services fournit des réponses simples à comprendre mais pas vraiment conviviales. Lors de l'exécution d'une requête, vous souhaitez extraire quelques valeurs spécifiques et non afficher un groupe de données. En règle générale, vous souhaitez analyser les réponses du service Web et extraire uniquement les valeurs qui vous intéressent.

Le modèle d'analyse que vous utilisez dépend du format des réponses : XML ou JSON. Déjà sous la forme d'objets Javascript, les réponses JSON peuvent être traitées dans Javascript sur le client. Les réponses XML doivent être traitées à l'aide d'un outil de traitement XML et d'un langage de requête XML pour gérer les éléments du format XML. Nous utilisons XPath dans les exemples suivants car ce paramètre est généralement pris en charge par les bibliothèques de traitement XML.

Traitement XML avec XPath

XML est un format d'informations structuré relativement abouti utilisé pour l'échange de données. Bien qu'il ne soit pas aussi léger que JSON, le format XML prend en charge davantage de langages et fournit des outils puissants. Par exemple, le code pour le traitement XML dans Java est intégré dans les packages javax.xml.

Lors du traitement des réponses XML, vous devez utiliser un langage de requête approprié pour sélectionner les nœuds dans le document XML et non supposer que les éléments résident à des emplacements absolus au sein du marquage XML. XPath est une syntaxe linguistique qui permet de décrire de manière unique les nœuds et éléments d'un document XML. Les expressions XPath vous permettent d'identifier un contenu spécifique dans le document de réponse XML.

Expressions XPath

Bien connaître XPath c'est pouvoir développer un modèle d'analyse fiable. Cette section décrit comment sont traités les éléments au sein d'un document XML avec XPath, pour vous permettre de traiter plusieurs éléments et créer des requêtes complexes.

XPath utilise des expressions pour sélectionner des éléments dans un document XML à l'aide d'une syntaxe similaire à celle utilisée pour les chemins d'accès aux répertoires. Ces expressions identifient les éléments au sein d'une arborescence de documents XML, à savoir, une arborescence hiérarchique identique à celle d'un modèle DOM. En règle générale, les expressions XPath sont gourmandes, dans le sens où elles renvoient tous les nœuds correspondants aux critères fournis.

Nous utilisons l'élément XML suivant pour illustrer nos exemples :

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

Sélection de nœud dans les expressions

Les sélections XPath permettent de sélectionner des nœuds. Le nœud racine inclut l'ensemble du document. Vous sélectionnez ce nœud à l'aide de l'expression spéciale « / ». Notez que le nœud racine n'est pas le nœud de niveau supérieur du document XML. En réalité, il est situé un niveau au-dessus de cet élément supérieur et l'inclut.

Les nœuds d'éléments représentent les différents éléments de l'arborescence de documents XML. Par exemple, un élément <WebServiceResponse> représente l'élément supérieur renvoyé dans notre exemple de service ci-dessus. Vous sélectionnez chaque nœud via des chemins absolus ou relatifs indiqués par la présence ou non d'un caractère de fin « / ».

  • Chemin absolu : l'expression « /WebServiceResponse/result » permet de sélectionner tous les nœuds <result> qui sont enfants du nœud <WebServiceResponse>. (Notez que ces deux éléments sont hérités du nœud racine « / ».)
  • Chemin relatif en fonction du contexte actuel : l'expression « result » permet de renvoyer tous les éléments <result> dans le contexte actuel. En général, vous n'avez pas à vous soucier du contexte dans la mesure où vous traitez les résultats du service Web via une seule expression.

Ces deux expressions peuvent être complétées par l'ajout d'un chemin générique indiqué par une double barre oblique (« // »). Ce chemin générique indique qu'un ou plusieurs éléments peuvent correspondre dans le chemin intermédiaire. Par exemple, l'expression XPath « //formatted_address » correspond à tous les nœuds de ce nom dans le document actuel. L'expression //viewport//lat correspond à tous les éléments <lat> pouvant avoir <viewport> comme parent.

Par défaut, les expressions XPath renvoient tous les éléments. Vous pouvez limiter l'expression à un élément spécifique en indiquant un prédicat entre crochets ([]). L'expression XPath « /GeocodeResponse/result[2] » renvoie toujours le second résultat, par exemple.

Type d'expression
Nœud racine
Expression XPath :  « / »
Sélection :
    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
    
Chemin absolu
Expression XPath :  « /WebServiceResponse/result »
Sélection :
    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
    
Chemin avec générique
Expression XPath :  « /WebServiceResponse//location »
Sélection :
    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
    
Chemin avec prédicat
Expression XPath :  « /WebServiceResponse/result[2]/message »
Sélection :
    <message>The secret message</message>
    
Tous les enfants directs du premier paramètre result
Expression XPath :  « /WebServiceResponse/result[1]/* »
Sélection :
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    
Le paramètre name d'un paramètre result dont le texte type est « sample ».
Expression XPath :  « /WebServiceResponse/result[type/text()='sample']/name »
Sélection :
    Sample XML
    

Il est important de noter que lors de la sélection des éléments, vous sélectionnez des nœuds et pas seulement le texte à l'intérieur de ces objets. En règle générale, vous souhaiter répéter l'opération sur tous les nœuds correspondants et extraire le texte. Vous pouvez aussi renvoyer les nœuds de texte directement. Voir les nœuds de texte ci-dessous.

Notez que XPath prend également en charge les nœuds d'attributs. Toutefois, tous les services Web Google Maps utilisent des éléments sans attributs. La recherche d'attributs n'est dont pas nécessaire.

Sélection de texte dans les expressions

Le texte d'un document XML est spécifié dans les expressions XPath via un opérateur de nœud de texte. Cet opérateur « text() » indique l'extraction de texte à partir du nœud indiqué. Par exemple, l'expression XPath « //formatted_address/text() » permet de renvoyer l'ensemble du texte inclus dans les éléments <formatted_address>.

Type d'expression
Tous les nœuds de texte (y compris les espaces vides)
Expression XPath :  « //text() »
Sélection :
    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
    
Sélection de texte
Expression XPath :  « /WebServiceRequest/result[2]/message/text() »
Sélection :
    The secret message
    
Sélection en fonction du contexte
Expression XPath :  « /WebServiceRequest/result[type/text() = 'sample']/name/text() »
Sélection :
    Sample XML
    

Vous pouvez également évaluer une expression et renvoyer un ensemble de nœuds puis répéter l'opération sur cet « ensemble de nœuds» pour extraire le texte de chaque nœud. Cette approche est utilisée dans l'exemple ci-dessous.

Pour plus d'informations sur XPath, voir la Spécification XPath W3C.

Évaluer XPath dans Java

Java prend largement en charge l'analyse XML et l'utilisation d'expressions XPath dans le package javax.xml.xpath.*. C'est pourquoi l'échantillon de code de cette section utilise Java pour illustrer comment traiter les données XML et les analyser à partir des réponses du service XML.

Pour utiliser XPath dans le code Java, vous devez d'abord instancier une instance de XPathFactory et appeler newXPath() sur cette instance pour créer un objet XPath . Cet objet peut ensuite traiter les expressions XML et XPath renvoyées à l'aide de la méthode evaluate().

Lors de l'évaluation des expressions XPath, veillez à répéter l'opération sur tous les « ensembles de nœuds» possibles renvoyés. Dans la mesure où ces résultats sont renvoyés comme des nœuds DOM dans le code Java, vous devez capturer ces valeurs multiples dans un objet NodeList et répéter l'opération sur cet objet pour extraire le texte ou les valeurs de ces nœuds.

Le code suivant décrit comme créer un objet XPath, lui affecter le format XML et une expression XPath, puis évaluer l'expression pour imprimer le contenu pertinent.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}

Télécharger le code à partir de js-v2-samples

Traitement JSON avec JavaScript

JSON (Javascript Object Notation) présente un certain avantage sur XML dans la mesure où sa réponse est légère. L'analyse d'un tel résultat est simple dans JavaScript car le format est déjà un objet Javascript valide. Par exemple, pour extraire la valeur des clés 'formatted_address' d'un objet de résultat JSON, il suffit d'y accéder à l'aide du code suivant :

for (i = 0; i < myJSONResult.results.length; i++) {
  myAddress[i] = myJSONResult.results[i].formatted_address;
}

Notez que dans la mesure où JSON peut contenir plusieurs valeurs, il est préférable de répéter l'opération sur l'ensemble des paramètres results pour capturer toutes les valeurs possibles. Dans la pratique, vous pouvez cependant renvoyer uniquement le premier résultat (results[0]).

L'analyse JSON dans d'autres langages n'est que légèrement plus complexe. L'exemple Python suivant lance une requête de service Web de géocodage et affiche toutes les valeurs de résultat formatted_address à l'utilisateur dans un tableau :

import simplejson, urllib

GEOCODE_BASE_URL = 'https://maps.googleapis.com/maps/api/geocode/json'

def geocode(address, **geo_args):
    geo_args.update({
        'address': address
    })

    url = GEOCODE_BASE_URL + '?' + urllib.urlencode(geo_args)
    result = simplejson.load(urllib.urlopen(url))

    print simplejson.dumps([s['formatted_address'] for s in result['results']], indent=2)

if __name__ == '__main__':
    geocode(address="San+Francisco")

Output: [ "San Francisco, CA, USA" ]

Télécharger le code à partir de js-v2-samples

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 API pour les services Web
Google Maps API pour les services Web