Google Maps Distance Matrix API

Introduction

Le service Google Maps Distance Matrix API fournit les distances et les durées des trajets pour une matrice de points de départ et de destinations. Les informations renvoyées s'appuient sur l'itinéraire recommandé entre les points de départ et les destinations, selon les calculs de Google Maps API. Elles se présentent sous forme de lignes contenant les valeurs duration et distance pour chaque paire.

Ce service ne renvoie pas d'informations détaillées sur l'itinéraire. Pour obtenir les informations d'itinéraire, transmettez le point de départ et la destination souhaités à Google Maps Directions API.

Obtenir une clé Limites d'utilisation

Public ciblé

Ce document est destiné aux développeurs qui souhaitent calculer les distances et les durées des trajets entre différents points à l'aide de Google Maps API. Il contient une introduction à l'utilisation de cette API et des références sur les paramètres disponibles.

Requêtes Distance Matrix

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

https://maps.googleapis.com/maps/api/distancematrix/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.

output peut prendre la valeur :

• json (recommandé) pour spécifier que le format de sortie est JavaScript Object Notation (JSON) ou
• xml pour spécifier que le format de sortie est XML.

Les URL de Google Maps Distance Matrix API sont limitées à environ 2 000 caractères, après l'encodage des URL. Comme certaines URL du service Google Maps Distance Matrix API peuvent comporter de nombreux points géographiques, ayez toujours cette limite présente à l'esprit lorsque vous créez vos URL. Notez que le nombre maximum de caractères de l'URL peut également varier selon le navigateur, le proxy ou le serveur.

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 (&).

Paramètres obligatoires

• origins — Une ou plusieurs adresses et/ou valeurs de latitude/longitude au format texte, séparées par une barre verticale (|), à utiliser comme points de départ pour le calcul des distances et des durées. Si vous spécifiez une adresse sous la forme d'une chaîne de caractères, le service géocode cette dernière pour la convertir en coordonnées de latitude/longitude afin de calculer les distances. Si vous spécifiez des coordonnées, assurez-vous que les valeurs de latitude et de longitude ne sont séparées par aucun espace.

  origins=Bobcaygeon+ON|41.43206,-81.38992

• destinations — Une ou plusieurs adresses et/ou valeurs de latitude/longitude au format texte, séparées par une barre verticale (|), à utiliser comme destinations pour le calcul des distances et des durées. Si vous spécifiez une adresse sous la forme d'une chaîne de caractères, le service géocode cette dernière pour la convertir en coordonnées de latitude/longitude afin de calculer les distances. Si vous spécifiez des coordonnées, assurez-vous que les valeurs de latitude et de longitude ne sont séparées par aucun espace.

  destinations=Darling+Harbour+NSW+Australia|24+Sussex+Drive+Ottawa+ON|Capitola+CA

• key — Clé d'API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

Les utilisateurs de Google Maps API for Work doivent inclure des paramètres client et signature valides dans leurs requêtes Distance Matrix. Pour plus d'informations, reportez-vous au chapitre Google Maps API for Work Web Services.

Paramètres facultatifs

• mode (valeur par défaut : driving) — Spécifie le moyen de transport à utiliser pour le calcul de la distance. Les valeurs valides et les autres détails de la requête sont spécifiés dans la section Modes de transport du présent document.
• language — Langue dans laquelle les résultats sont renvoyés. Voir la liste des langues prises en charge. Notez que cette liste peut ne pas être exhaustive, car nous mettons régulièrement à jour les langues prises en charge.
• avoid — Permet de spécifier des restrictions pour l'itinéraire. Les valeurs valides sont spécifiées dans la section Restrictions du présent document. Vous ne pouvez spécifier qu'une seule restriction.
• units — Spécifie le système d'unités à utiliser lorsque les distances sont exprimées au format texte. Pour plus d'informations, voir la section Systèmes d'unités du présent document.
• arrival_time — Spécifie l'heure d'arrivée souhaitée pour les requêtes de transport 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 — 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 API for Work 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 si le mode de transport est driving, que le paramètre departure_time est spécifié et que la requête inclut une clé d'API ou un ID client Google Maps API for Work. 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.
• transit_mode — Spécifie un ou plusieurs moyens de transport en commun privilégiés. Vous ne pouvez spécifier ce paramètre que si le mode est défini sur transit. 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 requêtes de transport 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. Vous ne pouvez le spécifier que si le mode est défini sur transit. 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.

* Remarque : les requêtes qui spécifient le paramètre departure_time sont limitées à 100 éléments.

Modes de transport

Pour calculer les distances, vous pouvez spécifier le mode de transport à utiliser. Par défaut, les distances sont calculées pour le mode driving. Les modes de transport suivants sont pris en charge :

• driving (mode par défaut) indique que le calcul des distances se base sur le réseau routier.
• walking permet de calculer les distances pour des piétons qui emprunteraient les voies piétonnes et les trottoirs (dans la mesure du possible).
• bicycling permet de calculer les distances pour des cyclistes qui emprunteraient les pistes cyclables et les rues privilégiées (dans la mesure du possible).
• transit permet de calculer les distances correspondant aux itinéraires des transports publics (dans la mesure du possible). Vous ne pouvez spécifier cette valeur que si la requête inclut une clé d'API ou un ID client Google Maps API for Work. 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 n'incluent pas de voies piétonnes ou de pistes cyclables clairement définies. Dans ce cas, le résultat renvoyé contient des warnings que vous devez montrer à l'utilisateur.

Restrictions

Il est possible de calculer des distances 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
• avoid=indoor

* 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 Distance Matrix affichent des éléments text dans les champs distance pour indiquer la distance de l'itinéraire calculé. Vous pouvez spécifier le système d'unités à utiliser :

• units=metric (par défaut) renvoie les distances en kilomètres et en mètres.
• units=imperial renvoie les distances en miles et en 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.

Réponses Distance Matrix

Les réponses aux requêtes Google Maps Distance Matrix API sont renvoyées au format spécifié par l'indicateur output dans le chemin de la requête URL.

Deux exemples de requêtes HTTP sont présentés ci-dessous. Elles permettent d'obtenir la distance et la durée des trajets parcourus à partir de Vancouver (Canada) et Seattle (États-Unis), jusqu'à San Francisco (États-Unis) et Victoria (Canada).

Cette requête illustre l'utilisation de l'indicateur output au format JSON :

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Cette requête illustre l'utilisation de l'indicateur output au format XML :

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Cette requête renvoie quatre éléments (les quatre trajets possibles avec les deux points de départ et les deux destinations) :

Les résultats sont renvoyés sous forme de lignes. Chaque ligne correspond à un point de départ associé à chaque destination.

Essayez ! Cliquez ici pour transférer l'exemple de requête vers votre navigateur. (Si vous êtes invité à spécifier l'application avec laquelle ouvrir le fichier, vous pouvez sélectionner votre navigateur ou l'éditeur de texte de votre choix.)

Cliquez sur les onglets ci-dessous pour voir les exemples de réponses aux formats JSON et XML.

{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

Éléments des réponses Distance Matrix

Les réponses Distance Matrix comprennent les éléments racine suivants :

• status contient des métadonnées sur la requête. Voir Codes de statut ci-dessous.
• origin_addresses contient un tableau d'adresses renvoyé par l'API à partir de la requête d'origine. Ces adresses sont formatées par le géocodeur et localisées en fonction du paramètre language transmis avec la requête.
• destination_addresses contient un tableau d'adresses renvoyé par l'API à partir de la requête d'origine. De même que pour origin_addresses, ces adresses sont localisées, le cas échéant.
• rows contient un tableau avec des elements, qui eux-mêmes contiennent les éléments status, duration et distance.

Codes de statut

Les champs status de l'objet de réponse contiennent le statut de la requête et peuvent contenir des informations utiles pour le débogage. Distance Matrix API renvoie un champ de statut de premier niveau contenant des informations générales sur la requête, ainsi qu'un champ de statut pour chaque champ d'élément avec des informations spécifiques à cette paire point de départ-destination.

Codes de statut de premier niveau

• OK indique que le champ result de la réponse contient une valeur valide.
• INVALID_REQUEST indique que la requête fournie n'était pas valide.
• MAX_ELEMENTS_EXCEEDED indique que le produit du nombre de points de départ et du nombre de destinations dépasse la valeur spécifiée dans le champ limit de la requête.
• 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 Distance Matrix.
• UNKNOWN_ERROR indique qu'une requête Distance Matrix n'a pas pu être traitée en raison d'une erreur du serveur. Si vous essayez à nouveau, la requête pourrait aboutir.

Codes de statut au niveau des éléments

• OK indique que le champ result de la réponse contient une valeur valide.
• NOT_FOUND indique que le point de départ et/ou la destination de cet élément n'ont pas pu être géocodés.
• ZERO_RESULTS indique qu'aucun itinéraire n'a pu être identifié entre le point de départ et la destination.

Messages d'erreur

Lorsque le code de statut de premier niveau n'est pas OK, l'objet de la réponse Distance Matrix 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 : Il n'est pas garanti que ce champ soit toujours présent et son contenu est susceptible de varier.

Lignes

Google Maps Distance Matrix API renvoie les résultats sous forme d'un tableau d'éléments row JSON. Même s'il n'y a aucun résultat (lorsque les points de départ et/ou les destinations n'existent pas, par exemple), un tableau vide est renvoyé. Les réponses XML sont constituées de zéro, d'un ou de plusieurs éléments <row>.

Les lignes sont ordonnées selon les valeurs fournies dans le paramètre origin de la requête. Chaque ligne correspond à un point de départ et chaque element de la ligne correspond à une paire formée par ce point de départ et une valeur destination.

Chaque tableau row contient une ou plusieurs entrées element qui à leur tour contiennent les informations concernant une paire point de départ-destination.

Éléments

Les informations concernant chaque paire point de départ-destination sont renvoyées dans une entrée element. Chaque entrée element contient les champs suivants :

• status : Pour obtenir la liste des codes de statut possibles, voir Codes de statut.
• duration : Durée du trajet pour cet itinéraire, exprimée en secondes (champ value) et au format texte (champ text). La représentation textuelle est localisée conformément à la valeur du paramètre language de la requête.

• duration_in_traffic : Durée du trajet pour cet itinéraire, en fonction de l'état du trafic actuel et historique. 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 est exprimée en secondes (champ value) et au format texte (champ text). La représentation textuelle est localisée conformément à la valeur du paramètre language de la requête. La durée du trajet n'est renvoyée que si toutes les conditions suivantes sont remplies :

  • La requête inclut un paramètre departure_time.
  • La requête inclut une clé d'API valide ou bien un ID client et une signature Google Maps API for Work valides.
  • L'état du trafic est disponible pour l'itinéraire demandé.
  • Le paramètre mode est défini sur driving.
• distance : Distance totale de l'itinéraire, exprimée en mètres (value) et au format texte (text). La valeur textuelle s'appuie sur le système d'unités spécifié à l'aide du paramètre unit de la requête d'origine ou sur la région du point de départ.
• 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 transport en commun et uniquement si les informations tarifaires sont disponibles pour les fournisseurs de transport en commun impliqués. 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 element contenant des informations tarifaires est présenté ci-dessous :

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

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.