Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps Directions API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou choisir un projet
  2. Activer Google Maps Directions API
  3. Créer les clés appropriées
Continuer

Guide du développeur

Google Maps Directions API est un service qui calcule des itinéraires entre des points géographiques au moyen d'une requête HTTP.

Ce service est également disponible côté client avec Google Maps JavaScript API ou, pour une utilisation côté serveur, avec Java Client, Python Client, Go Client et Node.js Client for Google Maps Services. Remarque : Les mêmes limites d'utilisation journalières s'appliquent quelle que soit la manière dont vous utilisez le service. Le nombre de requêtes par jour est calculé en additionnant les requêtes côté client et côté serveur.

Ce document est destiné aux développeurs de sites Web et d'applications mobiles qui souhaitent calculer des données d'itinéraire sur les cartes fournies par l'une des Google Maps API. Il contient une introduction à l'utilisation de cette API et des références sur les paramètres disponibles.

Introduction

Cette vidéo illustre l'utilisation de Google Maps Directions API afin d'aider les utilisateurs à trouver leur chemin. Elle fournit des conseils sur l'utilisation de votre serveur comme proxy du service Web lorsque vous utilisez l'API sur une application mobile, et ce afin de protéger votre clé d'API.

Avec Directions API, vous pouvez :

  • Recherchez des itinéraires pour différents moyens de transport dont les transports en commun, la voiture, la marche à pied ou le vélo.
  • Affichez des itinéraires multi-segments passant par une série de points de cheminement.
  • Spécifiez des points de départ, des destinations et des points de cheminement sous forme de chaînes de texte (par ex., « Chicago, Illinois » ou « Darwin, Territoire du Nord, Australie »), de coordonnées de latitude/longitude ou d'identifiants de lieu.

Le calcul d'itinéraires est une tâche qui requiert beaucoup de temps et de ressources. Dans la mesure du possible, calculez les adresses connues à l'avance (en utilisant le service décrit ici) et stockez vos résultats dans une mémoire cache temporaire de votre propre conception.

Remarque : Ce service n'est pas conçu pour répondre en temps réel à la saisie de l'utilisateur. Pour le calcul d'itinéraires dynamiques (par exemple, au sein d'un élément de l'interface utilisateur), voir la documentation sur le service Directions de Google Maps JavaScript API.

Avant de commencer à développer avec Directions API, consultez les exigences d'authentification (vous avez besoin d'une clé d'API) et les limites d'utilisation de l'API.

Requêtes Directions

Les requêtes Google Maps Directions API ont la forme suivante :

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

outputFormat peut prendre l'une des valeurs suivantes :

  • json (recommandé) indique que la réponse doit être au format JSON (JavaScript Object Notation).
  • xml indique que la réponse doit être au format XML.

Remarque : Les URL doivent être correctement encodées pour être valides et sont limitées à 8 192 caractères pour tous les services Web. Veillez à respecter cette limite lorsque vous élaborez vos URL.

HTTPS ou HTTP

La sécurité est importante et HTTPS est le protocole recommandé à chaque fois que possible, en particulier pour les applications qui incluent des données utilisateur sensibles (comme la position géographique de l'utilisateur) dans leurs requêtes. L'utilisation du chiffrement HTTPS rend votre application plus sûre et plus résistante au furetage ou à la falsification.

S'il n'est pas possible d'utiliser le protocole HTTPS et que vous devez accéder à Google Maps Directions API via HTTP, utilisez :

http://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Paramètres des requêtes

Certains paramètres sont obligatoires, d'autres sont facultatifs. Comme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&). Vous trouverez ci-dessous la liste des paramètres et leurs différentes valeurs possibles.

Paramètres obligatoires

  • origin — Adresse, valeur textuelle de latitude/longitude ou identifiant de lieu à partir duquel vous souhaitez calculer l'itinéraire.
    • Si vous spécifiez une adresse, le service Directions géocode la chaîne et la convertit en coordonnées de latitude/longitude pour calculer l'itinéraire. Ces coordonnées peuvent différer de celles renvoyées par Google Maps Geocoding API ; il peut s'agir, par exemple, de l'entrée d'un bâtiment plutôt que de son centre.
      origin=24+Sussex+Drive+Ottawa+ON
    • Si vous introduisez des coordonnées, elles sont utilisées telles quelles pour calculer l'itinéraire. Assurez-vous que les valeurs de latitude et de longitude ne sont séparées par aucun espace.
      origin=41.43206,-81.38992
    • Les identifiants de lieu doivent présenter le préfixe place_id:. L'identifiant de lieu ne peut être spécifié que si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Vous pouvez récupérer les identifiants de lieu depuis Google Maps Geocoding API et Google Places API (y compris Place Autocomplete). Pour consulter un exemple d'utilisation des identifiants de lieu à partir de Place Autocomplete, voir Place Autocomplete et Directions. Pour plus d'informations sur les identifiants de lieu, voir la présentation des identifiants de lieu.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination — Adresse, valeur textuelle de latitude/longitude ou identifiant de lieu vers lequel vous souhaitez calculer l'itinéraire. Les options du paramètre destination sont les mêmes que celles du paramètre origin décrites ci-dessus.
  • key — Clé d'API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

    Remarque : les clients Google Maps APIs Premium Plan peuvent utiliser soit une clé d'API, soit un ID client valide avec signature numérique dans leurs requêtes Directions. En savoir plus sur les paramètres d'authentification des clients Premium Plan.

Paramètres facultatifs

  • mode (valeur par défaut : driving) — Indique le moyen de transport à utiliser pour le calcul d'itinéraire. Les valeurs valides et les autres détails de la requête sont spécifiés dans la section Modes de transport.
  • waypoints — Spécifie un tableau de points de cheminement. Les points de cheminement modifient un itinéraire en le faisant passer par le ou les points géographiques indiqués. Un point de cheminement est spécifié sous forme de coordonnées de latitude/longitude, de polyligne encodée, d'identifiant de lieu ou d'adresse qui sera géocodée. Les polylignes encodées doivent être précédées du préfixe enc: et suivies de deux points (:). Les identifiants de lieu doivent présenter le préfixe place_id:. L'identifiant de lieu ne peut être spécifié que si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Les points de cheminement sont pris en charge uniquement pour les itinéraires en voiture, à pied ou à vélo. Pour plus d’infos sur les points de cheminement, voir le guide des points de cheminement ci-dessous.
  • alternatives — Si ce paramètre est défini sur true, il spécifie que le service Directions peut proposer plusieurs itinéraires dans la réponse. Notez que le calcul d'itinéraires alternatifs peut augmenter le temps de réponse du serveur.
  • avoid — Indique que les itinéraires calculés doivent éviter les caractéristiques indiquées. Il prend en charge les arguments suivants :
    • tolls indique que l'itinéraire calculé doit éviter les autoroutes et ponts à péage.
    • highways indique que l'itinéraire calculé doit éviter les autoroutes.
    • ferries indique que l'itinéraire calculé doit éviter les ferries.
    • indoor indique que l'itinéraire calculé doit éviter les étapes en intérieur lorsqu'il s'agit de trajets à pied ou en transports en commun. Seules les requêtes qui incluent une clé d'API ou un ID client Google Maps APIs Premium Plan reçoivent des étapes en intérieur par défaut.
    Pour plus d'informations, voir Restrictions d'itinéraire ci-dessous.
  • language — Langue dans laquelle les résultats sont renvoyés.
    • Voir la liste des langues prises en charge. Cette liste peut ne pas être exhaustive, car Google met régulièrement à jour les langues prises en charge.
    • Si le paramètre language n'est pas fourni, l'API tente d'utiliser la langue préférée telle que spécifiée dans l'en-tête Accept-Language ou la langue native du domaine à partir duquel la requête est envoyée.
    • L'API fait en sorte de fournir une adresse postale lisible tant par l'utilisateur que par les locaux. Pour ce faire, elle affiche les adresses postales dans la langue locale, translittérées sous la forme d'un script lisible par l'utilisateur, si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont affichées dans la langue préférée. Les composants d'adresse sont tous affichés dans la même langue, en fonction du premier composant.
    • Si un nom n'est pas disponible dans la langue préférée, l'API utilise le nom correspondant le plus proche.
    • La langue préférée a une influence réduite sur l'ensemble de résultats que l'API choisit d'afficher et l'ordre dans lequel ils sont affichés. Le géocodeur interprète les abréviations différemment en fonction de la langue, par exemple les abréviations pour les types de rues, ou les synonymes qui peuvent être valides dans une langue mais pas dans une autre. Ainsi, utca et tér sont tous deux synonymes de rue en hongrois.
  • units — Spécifie le système d'unités à utiliser pour l'affichage des résultats. Les valeurs valides sont spécifiées dans la section Systèmes d'unités ci-dessous.
  • region — Spécifie le code de région, indiqué sous forme de valeur ccTLD (« domaine de premier niveau ») à deux caractères. (Pour plus d'informations, voir Limiter les résultats à une région ci-dessous).
  • arrival_time — Spécifie l'heure d'arrivée souhaitée pour les itinéraires en transports en commun, en secondes depuis le 1er janvier 1970 à minuit UTC. Vous pouvez spécifier le paramètre departure_time ou arrival_time, mais pas les deux. Notez que le paramètre arrival_time spécifié doit être un nombre entier.
  • departure_time — Spécifie l'heure de départ souhaitée. Vous pouvez spécifier l'heure sous forme d'un nombre entier défini en secondes depuis le 1er janvier 1970 à minuit UTC. Si vous préférez, vous pouvez spécifier la valeur now pour définir l'heure de départ sur l'heure actuelle (à la seconde près). L'heure de départ peut être spécifiée dans deux cas :
    • Pour les requêtes où le moyen de transport est transit (transports en commun) : Si vous le souhaitez, vous pouvez spécifier une valeur pour departure_time ou arrival_time. Si aucune heure n'est spécifiée, le paramètre departure_time est défini par défaut sur la valeur « now » (en d'autres termes, l'heure de départ est par défaut l'heure actuelle).
    • Lorsque le mode de transport de la requête est driving (voiture) : Vous pouvez spécifier la valeur du paramètre departure_time pour obtenir un itinéraire et une durée de trajet (champ de réponse : duration_in_traffic) qui tiennent compte de l'état du trafic. Cette option n'est disponible que si la requête contient une clé d'API valide ou bien un ID client et une signature Google Maps APIs Premium Plan valides. Le paramètre departure_time doit être défini sur l'heure actuelle ou sur une heure future. Il ne peut pas être défini sur une heure passée.
  • traffic_model (valeur par défaut : best_guess) — Spécifie les hypothèses à utiliser pour un calcul de durée en fonction du trafic. Ce paramètre a un impact sur la valeur renvoyée dans le champ duration_in_traffic de la réponse, lequel contient la durée prévue en fonction du trafic d'après les moyennes historiques. Vous ne pouvez spécifier le paramètre traffic_model que pour un itinéraire en voiture, uniquement si le paramètre departure_time est spécifié et si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Les valeurs disponibles pour ce paramètre sont les suivantes :
    • best_guess (valeur par défaut) indique que la valeur duration_in_traffic renvoyée doit être la meilleure estimation de la durée du trajet, d'après les éléments connus concernant l'état du trafic historique et actuel. Plus la valeur du paramètre departure_time est proche de l'heure actuelle, plus le trafic actuel a d'importance.
    • pessimistic indique que la valeur duration_in_traffic renvoyée doit être supérieure à la durée du trajet observée la plupart des jours, même si certains jours, lorsque l'état du trafic est particulièrement mauvais, la durée observée peut dépasser cette valeur.
    • optimistic indique que la valeur duration_in_traffic renvoyée doit être inférieure à la durée du trajet observée la plupart des jours, même si certains jours, lorsque l'état du trafic est particulièrement bon, la durée observée peut être inférieure à cette valeur.
    La valeur par défaut définie pour best_guess donnera les prédictions les plus utiles pour la grande majorité des cas d'utilisation. En raison de la manière dont le modèle de prédiction best_guess intègre les informations en temps réel sur les conditions de circulation, la prédiction best_guess pour la durée du trajet peut être plus courte que la durée optimistic ou au contraire plus longue que la durée pessimistic.
  • transit_mode — Spécifie un ou plusieurs moyens de transport en commun privilégiés. Ce paramètre ne peut être spécifié que pour un itinéraire en transports en commun, uniquement si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Il prend en charge les arguments suivants :
    • bus indique que l'itinéraire calculé doit privilégier les trajets en bus.
    • subway indique que l'itinéraire calculé doit privilégier les trajets en métro.
    • train indique que l'itinéraire calculé doit privilégier les trajets en train.
    • tram indique que l'itinéraire calculé doit privilégier les trajets en tramway et en métro léger.
    • rail indique que l'itinéraire calculé doit privilégier les trajets en train, en tramway, en métro léger et en métro. Cet argument est équivalent à transit_mode=train|tram|subway.
  • transit_routing_preference — Spécifie les préférences des itinéraires en transports en commun. Ce paramètre vous permet de biaiser les options renvoyées, au lieu d'accepter le meilleur itinéraire choisi par défaut par l'API. Ce paramètre ne peut être spécifié que pour un itinéraire en transports en commun, uniquement si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Il prend en charge les arguments suivants :
    • less_walking indique que l'itinéraire calculé doit s'efforcer de limiter la distance parcourue à pied.
    • fewer_transfers indique que l'itinéraire calculé doit s'efforcer de limiter le nombre de correspondances.

Exemple de requêtes Directions

La requête suivante renvoie l'itinéraire en voiture de Toronto, en Ontario, à Montréal, au Québec.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

En changeant les paramètres mode et avoid, il est possible de modifier la requête initiale afin qu'elle renvoie un itinéraire à vélo pittoresque évitant les grands axes routiers.

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

La requête suivante recherche l'itinéraire en transports en commun entre Brooklyn, à New York, et le Queens, à New York. La requête ne spécifie pas de departure_time, donc l'heure de départ est par défaut l'heure actuelle :

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

La requête suivante inclut une heure de départ spécifique.

Remarque : Dans cet exemple, l'heure de départ spécifiée est le 30 juillet 2012 à 9h45. Pour éviter une erreur, vous devez remplacer le paramètre par une heure dans le futur avant de soumettre la requête.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

La requête suivante renvoie l'itinéraire en voiture de Glasgow, au Royaume-Uni, à Perth, au Royaume-Uni, à l'aide des identifiants de lieu.

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

Modes de transport

Lorsque vous calculez des itinéraires, vous pouvez spécifier le mode de transport à utiliser. Par défaut, les itinéraires sont calculés en voiture (driving). Les modes de transport suivants sont pris en charge :

  • driving (mode par défaut) indique l'itinéraire en voiture standard via le réseau routier.
  • walking permet de rechercher un itinéraire pour un piéton qui emprunterait les voies piétonnes et les trottoirs (dans la mesure du possible).
  • bicycling permet de calculer l'itinéraire pour un cycliste qui emprunterait les pistes cyclables et les rues privilégiées (dans la mesure du possible).
  • transit permet de rechercher un itinéraire empruntant les transports en commun (dans la mesure du possible). Si vous définissez le mode sur transit, vous pouvez, si vous le souhaitez, spécifier le paramètre departure_time ou arrival_time. Si aucune heure n'est spécifiée, le paramètre departure_time est défini par défaut sur la valeur « now » (en d'autres termes, l'heure de départ est par défaut l'heure actuelle). Vous avez également la possibilité de spécifier une valeur transit_mode et/ou une valeur transit_routing_preference.

Remarque : Parfois, les itinéraires à pied et à vélo ne comprennent pas de voies piétonnes ou de pistes cyclables. Dans ce cas, le résultat renvoyé contient des avertissements (warnings) que vous devez montrer à l'utilisateur.

Points de cheminement

Lors du calcul de trajets à l'aide de Google Maps Directions API, vous pouvez spécifier des points de cheminement pour les itinéraires en voiture, à pied ou à vélo. Les points de cheminement ne sont pas disponibles pour les itinéraires en transports en commun. Vous pouvez utiliser des points de cheminement pour calculer des trajets passant par des points géographiques supplémentaires, auquel cas l'itinéraire renvoyé inclut des arrêts à chacun des points de cheminement fournis.

Spécifiez les points de cheminement dans le paramètre waypoints.

  • Vous pouvez fournir un ou plusieurs lieux séparés par une barre verticale (|) sous la forme d'une adresse, de coordonnées de latitude/longitude ou d'un identifiant de lieu :
    • Si vous spécifiez une adresse, le service Directions géocode la chaîne et la convertit en coordonnées de latitude/longitude pour calculer l'itinéraire. Ces coordonnées peuvent différer de celles renvoyées par Google Maps Geocoding API ; il peut s'agir, par exemple, de l'entrée d'un bâtiment plutôt que de son centre.
    • Si vous introduisez des coordonnées de latitude/longitude, elles seront utilisées telles quelles pour calculer l'itinéraire. Assurez-vous que les valeurs de latitude et de longitude ne sont séparées par aucun espace.
    • Si vous fournissez un identifiant de lieu, vous devez y ajouter le préfixe place_id:. Vous ne pouvez spécifier un identifiant de lieu que si la requête inclut une clé d'API ou un ID client Google Maps APIs Premium Plan. Vous pouvez récupérer les identifiants de lieu depuis Google Maps Geocoding API et Google Places API (y compris Place Autocomplete). Pour consulter un exemple d'utilisation des identifiants de lieu à partir de Place Autocomplete, voir Place Autocomplete et Directions. Pour plus d'informations sur les identifiants de lieu, voir la présentation des identifiants de lieu.
  • Vous pouvez également fournir un ensemble encodé de coordonnées en utilisant l'algorithme de polyligne encodée. Cela peut s'avérer très utile si vous avez un nombre important de points de cheminement, car l'URL est nettement plus courte si l'on utilise une polyligne encodée.
    • Les polylignes encodées doivent être précédées du préfixe enc: et suivies de deux points (:). Par exemple : waypoints=enc:gfo}EtohhU:
    • Vous pouvez également inclure plusieurs polylignes encodées, séparées par une barre verticale (|). Par exemple : waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

L'URL suivante lance une requête d'itinéraire pour un trajet entre Boston, dans le Massachusetts, et Concors, dans le Massachusetts, avec des arrêts à Charlestown et Lexington, dans l'ordre suivant :

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&key=YOUR_API_KEY

Pour chaque point de cheminement dans la requête, la réponse d'itinéraire inclut une entrée supplémentaire dans le tableau legs afin de fournir les détails correspondant à cette section du trajet.

Si vous souhaitez influencer le trajet avec des points de cheminement sans ajouter d'arrêt, indiquez via: comme préfixe du point de cheminement. Les points de cheminement avec le préfixe via: n'ajoutent pas d'entrée au tableau legs ; cependant, l'itinéraire passe par le point de cheminement fourni.

L'URL suivante modifie la requête précédente de manière à faire passer le trajet par Lexington sans marquer d'arrêt :

https://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|via:Lexington,MA&key=YOUR_API_KEY

Le préfixe via: est particulièrement efficace pour la création d'itinéraires en réponse à l'utilisateur qui fait glisser les points de cheminement sur la carte. Ainsi, l'utilisateur peut voir le tracé final de l'itinéraire en temps réel et cela permet également de s'assurer que les points de cheminement sont placés sur des points géographiques accessibles à Google Maps Directions API.

L'URL suivante demande des points de cheminement utilisant des coordonnées de latitude/longitude :

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Voici la même requête utilisant une polyligne encodée :

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

Optimiser vos points de cheminement

Par défaut, le service Directions calcule un itinéraire passant par les points de cheminement dans l'ordre fourni. Vous pouvez également spécifier optimize:true comme premier argument dans le paramètre waypoints afin de permettre au service Directions d'optimiser l'itinéraire fourni en réorganisant les points de cheminement dans un ordre plus efficace. (Cette optimisation est une application du problème du voyageur de commerce.) La durée du trajet est le principal facteur optimisé, mais d'autres facteurs (tels que la distance, le nombre de bifurcations et bien d'autres) peuvent être pris en compte lors du choix de l'itinéraire le plus rapide. Tous les points de cheminement doivent être des arrêts pour que le service Directions optimise l'itinéraire.

Si vous demandez au service Directions d'optimiser l'ordre de ses points de cheminement, leur ordre est renvoyé dans le champ waypoint_order de l'objet routes. Le champ waypoint_order renvoie des valeurs de base zéro.

L'exemple suivant calcule l'itinéraire d'un trajet en voiture au départ d'Adélaïde, en Australie-Méridionale, vers chacune des principales régions viticoles d'Australie-Méridionale en utilisant l'optimisation de l'itinéraire.

https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&key=YOUR_API_KEY

Si l'on examine le trajet, on constate qu'il est calculé en suivant des points de cheminement dans l'ordre ci-dessous :

"waypoint_order": [ 1, 0, 2, 3 ]

Restrictions

Il est possible de calculer des itinéraires qui respectent des restrictions données. Pour spécifier une restriction, vous devez utiliser le paramètre avoid avec l'argument correspondant à la restriction souhaitée. Les restrictions suivantes sont prises en charge :

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

Il est possible d'obtenir un itinéraire qui évite toute combinaison de péages, d'autoroutes et de ferries en indiquant ces restrictions dans le paramètre « avoid ». Par exemple : avoid=tolls|highways|ferries.

Remarque : l'ajout d'une restriction n'exclut pas les itinéraires qui comprennent l'élément à éviter, mais privilégie simplement les itinéraires plus favorables.

Systèmes d'unités

Les résultats d'itinéraire affichent des éléments text dans les champs distance pouvant être affichés à l'utilisateur pour indiquer la distance d'une « étape » particulière sur le trajet. Ce texte utilise par défaut le système d'unités du pays ou de la région de départ.

Par exemple, un itinéraire allant de « Chicago, Illinois » à « Toronto, Ontario » affiche les résultats en miles alors que l'itinéraire inverse affiche des résultats en kilomètres. Vous pouvez modifier ce système d'unités en définissant explicitement un dans le paramètre units de la requête, en indiquant l'une des valeurs suivantes :

  • metric spécifie l'utilisation du système métrique. Les distances textuelles sont renvoyées en utilisant des kilomètres et des mètres.
  • imperial spécifie l'utilisation du système impérial (anglais). Les distances textuelles sont renvoyées en utilisant des miles et des pieds.

Remarque : ce paramètre de système d'unités n'a d'impact que sur les éléments text affichés dans les champs distance. Les champs distance contiennent également des éléments values qui sont toujours exprimés en mètres.

Limiter les résultats à une région

Vous pouvez également configurer le service Directions pour renvoyer des résultats privilégiant une région en particulier, en utilisant le paramètre region. Ce paramètre peut prendre un argument ccTLD (domaine de premier niveau correspondant au code pays) qui spécifie la région à privilégier. 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 » (ce qui correspond techniquement à l'entité « Royaume-Uni de Grande Bretagne et d'Irlande du Nord »).

Vous pouvez utiliser n'importe quel domaine dans lequel l'application Google Maps a lancé des itinéraires en voiture.

Par exemple, une requête d'itinéraire de « Toledo » à « Madrid » renvoie un résultat lorsque region est défini sur es, car « Toledo » est interprété comme la ville espagnole de Tolède :

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Un itinéraire de « Toledo » à « Madrid » lancé sans paramètre region ne renvoie pas de résultat étant donné que « Toledo » est interprété comme la ville de l'Ohio :

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Réponses aux requêtes Directions

Les réponses aux requêtes Directions sont renvoyées au format défini par l'indicateur output dans le chemin de la requête URL.

Exemples de réponses

Un exemple de requête HTTP est présenté ci-dessous. Elle calcule l'itinéraire de Chicago, dans l'Illinois, à Los Angeles, en Californie, via deux points de cheminement à Joplin, dans le Missouri, et Oklahoma City, dans l'Oklahoma.

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

L'exemple ci-dessus demande une réponse JSON. Il est également possible de demander une réponse XML. Cliquez sur les onglets ci-dessous pour voir les exemples de réponses aux formats JSON et XML.

Les résultats d'itinéraire pouvant être assez longs, les éléments répétés dans les réponses ont été omis dans un souci de clarté.

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

En règle générale, seule une entrée dans le tableau routes est renvoyée pour les recherches d'itinéraire. Néanmoins, le service Directions peut renvoyer plusieurs trajets si vous définissez alternatives=true.

Notez qu'il faut généralement analyser ces résultats pour pouvoir en extraire des valeurs. Les données JSON sont relativement faciles à analyser. Des modèles de conception recommandés sont disponibles dans la section Analyse JSON.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Notez que la réponse XML est constituée d'un seul élément <DirectionsResponse> et des éléments de niveau supérieur suivants :

  • <status> contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • Un élément <geocoded_waypoint> par point de cheminement, plus le point de départ et la destination, avec des détails sur le résultat de leur géocodage. Des éléments <geocoded_waypoint/> peuvent être vides. Voir Points de cheminement géocodés ci-dessous.
  • Zéro, un ou plusieurs éléments <result>, chacun contenant un ensemble unique d'informations d'itinéraire entre le point de départ et la destination.

Nous recommandons d'utiliser json comme indicateur de sortie privilégié, sauf si le service requiert xml pour une raison spécifique. Il peut s'avérer délicat de traiter les arborescences XML de manière à faire référence aux nœuds et aux éléments adéquats. Des modèles de conception recommandés pour le traitement des résultats sont disponibles dans la section Analyse XML avec XPath.

Dans la suite de la présente documentation, nous utiliserons la syntaxe JSON. Dans la plupart des cas, le format de sortie n'a pas d'importance lorsqu'il s'agit d'illustrer des concepts ou des noms de champs dans la documentation. Notez cependant les légères différences suivantes :

  • Les résultats XML sont incorporés dans un élément racine <DirectionsResponse>.
  • JSON représente les entrées ayant plusieurs éléments à l'aide de tableaux pluriels (tels que steps et legs), tandis que XML les représente à l'aide de plusieurs éléments singuliers (par exemple <step> et <leg>).
  • JSON représente l'ordre des points de cheminement via le champ waypoint_order, tandis que XML le représente à l'aide d'éléments <waypoint_index> individuels.
  • Les éléments vides sont indiqués sous forme de tableaux vides en JSON, mais par l'absence de ces éléments en XML. Par exemple, une réponse qui ne génère aucun résultat renvoie un tableau routes vide en JSON, mais aucun élément <route> en XML.

Éléments des réponses Directions

Les réponses d'itinéraire comprennent les éléments racine suivants :

  • status contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
  • geocoded_waypoints contient un tableau avec des détails sur le géocodage du point de départ, de la destination et des points de cheminement. Voir Étapes géocodées ci-dessous.
  • routes contient un tableau d'itinéraires entre le point de départ et la destination. Voir Itinéraires ci-dessous. Les itinéraires se composent de sections et d'étapes.
  • available_travel_modes contient un tableau des modes de transport disponibles. Ce champ est affiché lorsqu'une requête spécifie un mode de transport et n'obtient aucun résultat. Le tableau contient les modes de transport disponibles dans les pays de l'ensemble donné de points de cheminement. Ce champ n'est pas affiché si un ou plusieurs points de cheminement sont des points de cheminement via:. Voir les détails ci-dessous.

Codes de statut

Le champ status de l'objet de la réponse d'itinéraire contient le statut de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi le service Directions a échoué. Le champ status peut contenir les valeurs suivantes :

  • OK indique que le champ result de la réponse contient une valeur valide.
  • NOT_FOUND indique qu'au moins l'un des points géographiques spécifiés dans le point de départ, la destination ou les points de cheminement de la requête n'a pas pu être géocodé.
  • ZERO_RESULTS indique qu'aucun itinéraire n'a pu être identifié entre le point de départ et la destination.
  • MAX_WAYPOINTS_EXCEEDED indique que trop d'éléments waypoints (points de cheminement) ont été fournis dans la requête. Pour les applications qui utilisent Google Maps Directions API comme service Web ou le service Directions dans Google Maps JavaScript API, le nombre maximum de points de cheminement (waypoints) autorisé est de 23, en de plus l'origine et de la destination. Les clients Google Maps APIs Premium Plan peuvent soumettre des requêtes comprenant jusqu'à 23 points de cheminement, en plus de l'origine et de la destination.
  • INVALID_REQUEST indique que la requête fournie n'était pas valide. Un paramètre ou une valeur de paramètre non valide est généralement à l'origine de ce statut.
  • OVER_QUERY_LIMIT indique que le service a reçu trop de requêtes de la part de votre application au cours de la période autorisée.
  • REQUEST_DENIED indique que le service n'a pas autorisé votre application à utiliser le service Directions.
  • UNKNOWN_ERROR indique qu'une requête d'itinéraire 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 code de statut est autre que OK, l'objet de la réponse d'itinéraire peut comporter un champ supplémentaire error_message. Ce champ contient des informations plus détaillées sur les causes de ce code de statut.

Remarque : La présence de ce champ n'est pas garantie et son contenu est susceptible de varier.

Points de cheminement géocodés

Vous pouvez trouver des détails sur le géocodage de chaque point de cheminement, ainsi que du point de départ et de la destination, dans le tableau geocoded_waypoints (JSON). Ils peuvent vous aider à comprendre pourquoi le service renvoie des itinéraires inattendus voire aucun itinéraire.

Grâce à leur position base zéro, les éléments contenus dans le tableau geocoded_waypoints correspondent à l'origine, aux points de cheminement dans leur ordre de spécification, et à la destination. Chaque élément inclut les détails suivants sur l'opération de géocodage du point de cheminement correspondant :

  • geocoder_status indique le code de statut résultant de l'opération de géocodage. Ce champ peut contenir les valeurs suivantes :
    • "OK" indique qu'aucune erreur n'est survenue, que l'adresse a été analysée et qu'au moins un géocode a été trouvé.
    • "ZERO_RESULTS" indique que le géocode a réussi mais n'a renvoyé aucun résultat. Cela peut se produire si le géocodeur a reçu un paramètre address inexistant.
  • partial_match indique que le géocodeur n'a pas renvoyé de correspondance exacte pour la requête d'origine, mais qu'il a 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, « 21 Henr St, Bristol, UK » renvoie une correspondance partielle à la fois pour Henry Street et pour Henrietta Street. Notez que si une requête comprend un composant d'adresse mal saisi, le service de géocodage peut suggérer une autre adresse. Les suggestions déclenchées de cette façon sont également signalées comme des correspondances partielles.

  • place_id est un identifiant unique qui peut être utilisé avec d'autres API Google. Par exemple, vous pouvez utiliser l'élément place_id d'une réponse de Google Place Autocomplete pour calculer l'itinéraire vers une entreprise locale. Voir la présentation des identifiants de lieu.
  • types indique le type d'adresse du résultat du géocodage utilisé pour le calcul de l'itinéraire. Les types suivants sont renvoyés :
    • street_address indique une adresse de rue précise.
    • route indique une route nommée (comme « US 101 »).
    • intersection indique une intersection majeure, généralement de deux routes principales.
    • political indique une entité politique. Habituellement, ce type indique un polygone de certaines administrations civiles.
    • country indique l'entité politique nationale et correspond généralement au type de premier ordre renvoyé par le géocodeur.
    • administrative_area_level_1 indique une 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ématiquement garanti car nos résultats de géocodage se basent sur divers signaux et données de géolocalisation.
    • administrative_area_level_2 indique une 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 indique une 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 indique une 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 indique une 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.
    • colloquial_area indique un autre nom couramment utilisé pour l'entité.
    • locality indique une entité politique de ville ou de municipalité incorporée.
    • ward indique un type spécifique de localité japonaise afin de faciliter la distinction entre plusieurs composants de localité au sein d'une adresse japonaise.
    • sublocality indique une entité civile de premier ordre en dessous de la localité. Certains points géographiques peuvent 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 indique un quartier nommé.
    • premise indique un lieu nommé, généralement un bâtiment ou un ensemble de bâtiments ayant un nom commun.
    • subpremise indique une entité de premier ordre située en dessous d'un lieu nommé, généralement un bâtiment particulier au sein d'un ensemble de bâtiments ayant un nom commun.
    • postal_code indique un code postal tel qu'utilisé dans les adresses de courrier postal du pays.
    • natural_feature indique une caractéristique naturelle importante.
    • airport indique un aéroport.
    • park indique un parc nommé.
    • point_of_interest indique un point d'intérêt nommé. Généralement, ces « POI » sont des entités locales importantes qui ne s'intègrent pas facilement à une autre catégorie, comme l'« Empire State Building » ou la « Statue de la Liberté ».

    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.

Ces détails ne sont pas présents pour les points de cheminement spécifiés sous forme de valeurs textuelles de latitude/longitude si le service ne renvoie pas de résultat. En effet, seul un géocodage inversé de ces points de cheminement est effectué pour obtenir leur adresse représentative lorsqu'un itinéraire a été trouvé. Un objet JSON vide occupe les lieux correspondants dans le tableau geocoded_waypoints.

Itinéraires

Google Maps Directions API renvoie les résultats sous forme d'un tableau d'éléments routes (JSON). Même si le service ne renvoie aucun résultat (par exemple, si le point de départ et/ou la destination sont inexistants), il renvoie malgré tout un tableau routes vide. Les réponses XML sont composées de zéro, un ou plusieurs éléments <route>.

Chaque élément du tableau routes contient un seul résultat à partir du point de départ et de la destination spécifiés. Cet itinéraire peut se composer d'un ou de plusieurs éléments legs, en fonction des points de cheminement spécifiés, le cas échéant. L'itinéraire contient également des informations relatives aux droits d'auteur et aux avertissements qui doivent être affichées à l'utilisateur en plus des informations d'itinéraire.

Chaque itinéraire dans le champ routes peut contenir les champs suivants :

  • summary contient une brève description textuelle de l'itinéraire, afin de nommer l'itinéraire et de le distinguer des itinéraires alternatifs.
  • legs[] contient un tableau comportant des informations sur une section d'itinéraire, entre deux points géographiques sur un itinéraire donné. Une section séparée est présente pour chaque point de cheminement ou destination spécifié(e). Un itinéraire sans point de cheminement contient exactement une section dans le tableau legs. Chaque section se compose d'une série de steps. (Voir Sections d'itinéraire ci-dessous.)
  • waypoint_order (ou <waypoint_index> dans XML) contient un tableau indiquant l'ordre des points de cheminement de l'itinéraire calculé. Il est possible de réorganiser ces points de cheminement si optimize:true est spécifié dans le paramètre waypoints de la requête.
  • overview_polyline comporte un seul objet points qui contient une représentation sous forme de polyligne encodée de l'itinéraire. Cette polyligne est un tracé approximatif (lissé) de l'itinéraire obtenu.
  • bounds contient le cadre de la fenêtre d'affichage de overview_polyline.
  • copyrights contient le texte relatif aux droits d'auteur à afficher pour cet itinéraire. Vous devez gérer et afficher vous-même ces informations.
  • warnings[] contient un tableau d'avertissements devant apparaître lorsque l'itinéraire est affiché. Vous devez gérer et afficher vous-même ces avertissements.
  • fare : S'il est présent, ce champ contient le coût total de l'itinéraire (c'est-à-dire le total des prix des billets). Cette propriété n'est renvoyée que pour les requêtes de transports en commun et uniquement si les informations tarifaires sont disponibles pour toutes les sections en transports en commun. Ces informations comprennent les données suivantes :
    • currency : Code de devise ISO 4217 qui indique la devise dans laquelle le montant est exprimé.
    • value : Prix total, exprimé dans la devise spécifiée ci-dessus.
    • text : Prix total, formaté dans la langue spécifiée.

Un exemple d'informations tarifaires d'un itinéraire est présenté ci-dessous :

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

Sections

Chaque élément dans le tableau legs spécifie une unique section allant du point de départ à la destination dans l'itinéraire calculé. Les itinéraires sans point de cheminement se composent d'une seule « section ». En revanche, les itinéraires où un ou plusieurs points de cheminement sont définis se composent d'une ou de plusieurs sections de trajet.

Chaque section dans le(s) champ(s) legs peut contenir les champs suivants :

  • steps[] contient un tableau d'étapes comportant des informations sur chaque étape distincte de la section du trajet. (Voir Étapes d'itinéraire ci-dessous.)
  • distance indique la distance totale couverte par cette section sous forme de champ avec les éléments suivants :

    • value indique la distance en mètres.
    • text contient une représentation lisible de la distance, affichée dans les unités utilisées au point de départ (ou conformément à la modification du paramètre units dans la requête). Par exemple, des miles et des pieds sont utilisés pour tout point de départ aux États-Unis. Notez que, quel que soit le système d'unités affiché sous forme de texte, le champ distance.value contient toujours une valeur exprimée en mètres.

    Ces champs peuvent être absents si la distance est inconnue.

  • duration indique la durée totale de cette section sous forme de champ avec les éléments suivants :

    • value indique la durée en secondes.
    • text contient une représentation lisible de la durée.

    Ces champs peuvent être absents si la durée est inconnue.

  • duration_in_traffic indique la durée totale de la section. Cette valeur est une estimation de la durée en fonction du trafic sur la base des conditions de trafic actuelles et historiques. Reportez-vous au paramètre de requête traffic_model pour connaître les options à votre disposition pour obtenir une valeur optimiste, pessimiste ou encore la meilleure estimation. La durée du trajet n'est renvoyée que si toutes les conditions suivantes sont remplies :

    • La requête inclut une clé d'API valide ou bien un ID client et une signature Google Maps APIs Premium Plan valides.
    • La requête n'inclut pas de points de cheminement avec arrêt. Si la requête inclut des points de cheminement, le préfixe via: doit leur être ajouté pour éviter les arrêts.
    • La requête porte spécifiquement sur un itinéraire en voiture — le paramètre mode est défini sur driving.
    • La requête inclut un paramètre departure_time.
    • L'état du trafic est disponible pour l'itinéraire demandé.

    L'élément duration_in_traffic se compose des champs suivants :

    • value indique la durée en secondes.
    • text contient une représentation lisible de la durée.
  • arrival_time contient l'heure d'arrivée prévue pour la section. Cette propriété est renvoyée uniquement pour les itinéraires en transports en commun. Le résultat est renvoyé sous forme d'objet Time avec trois propriétés :
    • value est l'heure spécifiée en tant qu'objet Date JavaScript.
    • text est l'heure spécifiée sous forme de chaîne. L'heure est affichée dans le fuseau horaire de l'arrêt du transport en commun.
    • time_zone contient le fuseau horaire de cet arrêt. La valeur est le nom du fuseau horaire tel qu'il est défini dans la base de données des fuseaux horaires de l'IANA. Par exemple, « America/New_York ».
  • departure_time contient l'heure de départ prévue pour la section, spécifiée sous la forme d'un objet Time. Le champ departure_time est uniquement disponible pour les itinéraires en transports en commun.
  • start_location contient les coordonnées de latitude/longitude du point de départ de la section. Étant donné que Directions API calcule l'itinéraire entre des points géographiques en utilisant l'option de transport la plus proche (généralement une route) au point de départ et au point d'arrivée, l'élément start_location peut différer du point de départ fourni pour la section si, par exemple, aucune route ne se trouve à proximité de celui-ci.
  • end_location contient les coordonnées de latitude/longitude de la destination donnée pour cette section. Étant donné que Google Maps Directions API calcule l'itinéraire entre des points géographiques en utilisant l'option de transport la plus proche (généralement une route) au point de départ et au point d'arrivée, l'élément end_location peut différer de la destination fournie pour la section si, par exemple, aucune route ne se trouve à proximité de celle-ci.
  • start_address contient l'adresse lisible (généralement une adresse postale) obtenue en effectuant un géocodage inversé de l'élément start_location de la section.
  • end_address contient l'adresse lisible (généralement une adresse postale) obtenue en effectuant un géocodage inversé de l'élément end_location de la section.

Jalons

Chaque élément du tableau steps définit une étape unique dans l'itinéraire calculé. Une étape est l'unité la plus petite d'un itinéraire et décrit une instruction unique et spécifique au cours du trajet. Par exemple, « Tourner à gauche à W. 4th St. » Cette étape décrit non seulement l'instruction mais contient également des informations de distance et de durée concernant la relation entre cette étape et la suivante. Par exemple, une étape telle que « S'insérer sur l'I-80 West » peut contenir une durée de « 37 miles » et de « 40 minutes », indiquant que l'étape suivante se trouve à 37 miles/40 minutes de l'étape actuelle.

Lorsque vous utilisez Google Maps Directions API pour rechercher un itinéraire en transports en commun, le tableau d'étapes inclut des détails supplémentaires sur les transports en commun sous la forme d'un tableau transit_details. Si l'itinéraire inclut plusieurs modes de transport, des indications détaillées sont fournies pour les étapes à pied ou en voiture dans un tableau steps interne. Par exemple, une étape à pied inclut des indications à partir des points géographiques de départ et de destination : « Marcher jusqu'à Innes Avenue et Fitch Street. » Cette étape inclut des indications à pied détaillées pour cet itinéraire dans le tableau steps interne comme : « Prendre la direction nord-est. », « Prendre à gauche sur Arelious Walker » et « Prendre à gauche sur Innes Avenue. »

Chaque étape dans le(s) champ(s) steps peut contenir les champs suivants :

  • html_instructions contient des instructions formatées pour cette étape, présentées sous forme de chaîne de texte HTML.
  • distance contient la distance couverte par cette étape jusqu'à l'étape suivante. (Voir les explications sur ce champ dans Sections d'itinéraire ci-dessus.) Ce champ peut être non défini si la distance est inconnue.
  • duration contient la durée généralement nécessaire pour effectuer l'étape, jusqu'à l'étape suivante. (Voir la description dans Sections d'itinéraire ci-dessus.) Ce champ peut être non défini si la durée est inconnue.
  • start_location contient la localisation du point de départ de cette étape, sous la forme d'un ensemble unique de champs lat et lng.
  • end_location contient la localisation du dernier point de cette étape, sous la forme d'un ensemble unique de champs lat et lng.
  • polyline comporte un seul objet points qui contient une représentation sous forme de polyligne encodée de l'étape. Cette polyligne est un tracé approximatif (lissé) de l'étape.
  • steps contient des indications détaillées pour les étapes à pied ou en voiture dans les itinéraires en transports en commun. Des sous-étapes sont uniquement disponibles lorsque travel_mode est défini sur « transit ». Le tableau steps interne est de même type que le tableau steps.
  • transit_details contient des informations spécifiques aux transports en commun. Ce champ est uniquement renvoyé lorsque travel_mode est défini sur « transit ». Voir Détails sur les transports en commun ci-dessous.

Détails sur les transports en commun

Les itinéraires en transports en commun renvoient des informations supplémentaires qui ne sont pas pertinentes pour les autres modes de transport. Ces propriétés supplémentaires sont détaillées dans l'objet transit_details, renvoyé sous forme de champ d'un élément dans le tableau steps[]. Vous pouvez accéder à des informations supplémentaires sur l'arrêt, la ligne de transport et la société de transport dans l'objet TransitDetails.

Un objet transit_details peut contenir les champs suivants :

  • arrival_stop et departure_stop contiennent des informations sur l'arrêt ou la station pour cette partie du trajet. Les détails de l'arrêt peuvent inclure les éléments suivants :
    • name est le nom de la station ou de l'arrêt du transport en commun. Par exemple, « Union Square ».
    • location est la localisation de l'arrêt ou de la station du transport en commun, représentée par un champ lat et lng.
  • arrival_time et departure_time contiennent les heures d'arrivée et de départ pour cette section du trajet, spécifiées grâce aux trois propriétés suivantes :
    • text est l'heure spécifiée sous forme de chaîne. L'heure est affichée dans le fuseau horaire de l'arrêt du transport en commun.
    • value est l'heure spécifiée comme heure Unix ou les secondes depuis le 1er janvier 1970 à minuit UTC.
    • time_zone contient le fuseau horaire de cet arrêt. La valeur est le nom du fuseau horaire tel qu'il est défini dans la base de données des fuseaux horaires de l'IANA. Par exemple, « America/New_York ».
  • headsign spécifie la direction de voyage sur la ligne, telle qu'elle est signalée sur le véhicule ou à l'arrêt de départ. Il s'agit souvent du terminus.
  • headway spécifie le nombre de secondes prévues entre les départs depuis le même arrêt à l'heure actuelle. Par exemple, si la valeur headway est de 600, une attente de dix minutes est prévue si vous ratez votre bus.
  • num_stops contient le nombre d'arrêts pour cette étape, en comptant l'arrêt d'arrivée mais pas celui de départ. Par exemple, si votre itinéraire consiste à monter à l'arrêt A, à passer par les arrêts B et D, et à descendre à l'arrêt D, num_stops renvoie 3.
  • line contient des informations sur la ligne de transport en commun utilisée pour cette étape et peut inclure les propriétés suivantes :
    • name contient le nom complet de la ligne de transport en commun. Par exemple, « 7 Avenue Express ».
    • short_name contient le nom court de la ligne de transport en commun. Il s'agit généralement d'un numéro de ligne, comme « M7 » ou « 355 ».
    • color contient la couleur généralement utilisée pour signaliser la ligne de transports en commun. La couleur est spécifiée par une chaîne hexadécimale comme #FF0033.
    • agencies contient un tableau d'objets TransitAgency qui fournissent chacun des informations sur l'opérateur de la ligne, y compris les propriétés suivantes :
      • name contient le nom de la société de transports en commun.
      • url contient l'URL de la société de transports en commun.
      • phone contient le numéro de téléphone de la société de transports en commun.

      Vous devez afficher les noms et URL des sociétés de transports en commun desservant les résultats du trajet.

    • url contient l'URL de la ligne de transport fournie par la société de transports en commun.
    • icon contient l'URL de l'icône associée à la ligne.
    • text_color contient la couleur de texte généralement utilisée pour la signalisation de la ligne. La couleur est spécifiée par une chaîne hexadécimale.
    • vehicle contient le type de véhicule utilisé sur cette ligne. Cet élément peut inclure les propriétés suivantes :
      • name contient le nom du véhicule sur cette ligne. Par exemple, « Subway » (métro).
      • type contient le type de véhicule exploité sur cette ligne. Voir la documentation sur le type de véhicule pour consulter la liste complète des valeurs prises en charge.
      • icon contient l'URL d'une icône associée à ce type de véhicule.
      • local_icon contient l'URL de l'icône associée à ce type de véhicule, en fonction de la signalisation de transport locale.

Type de véhicule

La propriété vehicle.type peut renvoyer l'une des valeurs suivantes :

Valeur Définition
RAIL Transport ferroviaire.
METRO_RAIL Métro léger.
SUBWAY Métro léger souterrain.
TRAM Train léger en surface (tramway).
MONORAIL Monorail.
HEAVY_RAIL Métro.
COMMUTER_TRAIN Réseau ferré de banlieue.
HIGH_SPEED_TRAIN Train à grande vitesse.
BUS Bus.
INTERCITY_BUS Bus interurbain.
TROLLEYBUS Trolleybus.
SHARE_TAXI Type de bus pouvant faire monter et descendre des passagers n'importe où sur la ligne.
FERRY Ferry.
CABLE_CAR Véhicule tracté par un câble, généralement en surface. Lorsqu'ils sont aériens, ces véhicules peuvent être de type GONDOLA_LIFT (télécabine).
GONDOLA_LIFT Télécabine.
FUNICULAR Véhicule tracté par un câble le long d'une pente prononcée. Un funiculaire se compose généralement de deux rames, chacune agissant comme contrepoids de l'autre.
OTHER Ce type est renvoyé pour tous les autres véhicules.

Modes de transport disponibles

Le champ de réponse available_travel_modes contient un tableau des modes de transport disponibles. Ce champ est affiché lorsqu'une requête spécifie un mode de transport et n'obtient aucun résultat. Le tableau contient les modes de transport disponibles dans les pays de l'ensemble de points de cheminement donné qui renvoient des résultats. Ce champ n'est pas affiché si l'un des points de cheminement est un point de cheminement via:.

Par exemple, si vous essayez la requête suivante :

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

Elle génère la réponse suivante :

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

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 Directions API
Google Maps Directions API
Besoin d'aide ? Consultez notre page d'assistance.