Introduction

L’API Distance Matrix est un service qui fournit la distance et le temps de trajet pour une matrice d’origines et de destinations. L’API renvoie des informations basées sur l’itinéraire recommandé entre les points de début et de fin, calculé par l’API Google Maps, et se compose de lignes contenant des valeurs duration et distance pour chaque paire.

Remarque: Ce service ne renvoie pas d’informations détaillées sur l’itinéraire. Les informations d’itinéraire peuvent être obtenues en transmettant l’origine et la destination uniques souhaitées à l’API Directions.

Avant de commencer

Ce document est destiné aux développeurs qui souhaitent calculer la distance et le temps de parcours entre un certain nombre de points dans les cartes fournies par l’une des API Google Maps. Il fournit une introduction à l’utilisation de l’API et du matériel de référence sur les paramètres disponibles.

Avant de commencer à développer avec l’API Distance Matrix, passez en revue les exigences d’authentification (vous avez besoin d’une clé API) et les informations d’utilisation et de facturation de l’API (vous devez activer la facturation sur votre projet).

Demandes de Matrice de distance

Une demande d’API de Matrice de distance prend la forme suivante :

où outputFormatpeut être l’une des valeurs suivantes :

• json (recommandé), indique sortie en notation d’objet JavaScript (JSON) ; ou
• xml, indique la sortie en XML.

Remarque : Les URL doivent être correctement encodées pour être valides et sont limitées à 8192 caractères pour tous les services Web. Soyez conscient de cette limite lors de la construction de vos URL. Notez que différents navigateurs, proxys et serveurs peuvent également avoir des limites de caractères d’URL différentes.

HTTPS ou HTTP

La sécurité est importante et HTTPS est recommandé dans la mesure du possible, en particulier pour les applications qui incluent des données utilisateur sensibles, telles que l’emplacement d’un utilisateur, dans les requêtes. L’utilisation du cryptage HTTPS rend votre application plus sécurisée et plus résistante à l’espionnage ou à la falsification.

Si HTTPS n’est pas possible, pour accéder à l’API Distance Matrix via HTTP, utilisez:

Paramètres de requête

Certains paramètres sont requis tandis que d’autres sont facultatifs. Comme c’est la norme dans les URL, tous les paramètres sont séparés à l’aide du caractère esperluette (&). Tous les caractères réservés (par exemple le signe plus « + ») doivent être encodés en URL.La liste des paramètres et leurs valeurs possibles sont énumérées ci-dessous.

Paramètres requis

• origins — Le point de départ pour calculer la distance et le temps de déplacement. Vous pouvez fournir un ou plusieurs emplacements séparés par le caractère de tuyau (|), sous la forme d’un identifiant de lieu, d’une adresse ou de coordonnées de latitude/longitude :
  • Si vous fournissez un identifiant de lieu, vous devez le préfixer par place_id:. Vous ne pouvez spécifier un ID de lieu que si la demande inclut une clé API ou un ID client du plan Premium de Google Maps Platform. Vous pouvez récupérer les IDENTIFIANTS de lieu à partir de l’API de géocodage et de l’API de Lieux (y compris la saisie semi-automatique des lieux). Pour un exemple d’utilisation des IDENTIFIANTS de lieu à partir de la saisie semi-automatique de lieu, voir Saisie semi-automatique de lieu et Directions. Pour en savoir plus sur les identifiants de lieu, consultez la vue d’ensemble des identifiants de lieu.
  • Si vous passez une adresse, le service géocode la chaîne et la convertit en coordonnées de latitude/longitude pour calculer la distance. Cette coordonnée peut être différente de celle renvoyée par l’API de géocodage, par exemple une entrée de bâtiment plutôt que son centre.

    origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON

    Remarque : il est préférable d’utiliser des identifiants de lieu plutôt que d’utiliser des adresses ou des coordonnées de latitude /longitude. L’utilisation des coordonnées entraînera toujours l’accrochage du point à la route la plus proche de ces coordonnées – qui peut ne pas être un point d’accès à la propriété, ou même une route qui mènera rapidement ou en toute sécurité à la destination.
  • Si vous passez les coordonnées de latitude / longitude, elles s’accrocheront à la route la plus proche. Il est préférable de passer un identifiant de lieu. Si vous transmettez des coordonnées, assurez-vous qu’il n’y a pas d’espace entre les valeurs de latitude et de longitude.

    origins=41.43206,-81.38992|-33.86748,151.20699

    origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

  • Les codes Plus doivent être formatés en tant que code global ou code composé. Formatez les codes plus comme indiqué ici (les signes plus sont échappés à l’URL vers %2B et les espaces sont échappés à l’url vers %20):
    • le code global est un indicatif régional à 4 caractères et un code local à 6 caractères ou plus (849VCWC8 + R9 est 849VCWC8%2BR9).Le code composé
    • est un code local de 6 caractères ou plus avec un emplacement explicite (CWC8 + R9 Mountain View, CA, USA est CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Vous pouvez également fournir un ensemble codé de coordonnées à l’aide de l’algorithme de polyligne codé. Ceci est particulièrement utile si vous avez un grand nombre de points d’origine, car l’URL est nettement plus courte lorsque vous utilisez une polyligne codée. Les polylignes codées
    • doivent être préfixées par enc: et suivies d’un deux-points (:).Par exemple : origins=enc:gfo}EtohhU:
    • Vous pouvez également inclure plusieurs polylignes codées, séparées par le caractère pipe (|). Exemple: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
• destinations — Un ou plusieurs emplacements à utiliser comme point d’arrivée pour calculer la distance et le temps de déplacement. Les options pour le paramètre destinations sont les mêmes que pour le paramètre origins, décrit ci-dessus.
• key – La clé API de votre application. Cette clé identifie votre demande à des fins de gestion des quotas. Apprenez à obtenir une clé.

  Note: Les clients du plan Premium de la plateforme Google Maps peuvent utiliser une clé API ou un identifiant client valide et une signature numérique dans vos demandes de matrice de distance. Obtenez plus d’informations sur les paramètres d’authentification pour les clients du plan Premium.

L’exemple suivant utilise les coordonnées de latitude/longitude pour spécifier les coordonnées de destination :

L’exemple suivant utilise des codes plus pour spécifier les coordonnées de destination :

L’exemple suivant montre la même requête en utilisant une polyligne codée:

Paramètres optionnels

• mode (par défaut driving) – Spécifie le mode de transport à utiliser lors du calcul de la distance. Les valeurs valides et les autres détails de la demande sont spécifiés dans la section Modes de déplacement de ce document.
• language – La langue dans laquelle retourner les résultats.
  • Voir la liste des langues prises en charge. Google met souvent à jour les langues prises en charge, cette liste peut donc ne pas être exhaustive.
  • Si language n’est pas fourni, l’API tente d’utiliser la langue préférée spécifiée dans l’en-tête Accept-Language, ou la langue maternelle du domaine à partir duquel la requête est envoyée.
  • L’API fait de son mieux pour fournir une adresse postale lisible à la fois pour l’utilisateur et les locaux. Pour atteindre cet objectif, il renvoie des adresses de rue dans la langue locale, translittérées dans un script lisible par l’utilisateur si nécessaire, en respectant la langue préférée. Toutes les autres adresses sont renvoyées dans la langue de votre choix. Les composants d’adresse sont tous renvoyés dans la même langue, qui est choisie parmi le premier composant.
  • Si un nom n’est pas disponible dans la langue préférée, l’API utilise la correspondance la plus proche.
  • La langue préférée a une petite influence sur l’ensemble des résultats que l’API choisit de renvoyer et sur l’ordre dans lequel ils sont renvoyés. Le géocodeur interprète les abréviations différemment selon la langue, comme les abréviations pour les types de rues, ou des synonymes qui peuvent être valides dans une langue mais pas dans une autre. Par exemple, utca et tér sont synonymes de rue en hongrois.
• region – Le code de région, spécifié comme une valeur de deux caractères ccTLD (country code top-level domain). La plupart des codes ccTLD sont identiques aux codes ISO 3166-1, à quelques exceptions près. Ce paramètre n’influencera que les résultats du géocodeur, et non les limitera complètement. Si des résultats plus pertinents existent en dehors de la région spécifiée, ils peuvent être inclus.
• avoid— – Introduit des restrictions à la route. Les valeurs valides sont spécifiées dans la section Restrictions de ce document. Une seule restriction peut être spécifiée.
• units — Spécifie le système d’unités à utiliser lors de l’expression de la distance sous forme de texte. Voir la section Systèmes d’unités de ce document pour plus d’informations.
• arrival_time— – Spécifie l’heure d’arrivée souhaitée pour les demandes de transit, en secondes depuis minuit, le 1er janvier 1970 UTC. Vous pouvez spécifier departure_time ou arrival_time, mais pas les deux. Notez que arrival_time doit être spécifié comme un entier.
• departure_time — L’heure de départ souhaitée. Vous pouvez spécifier l’heure sous forme d’entier en secondes depuis minuit, le 1er janvier 1970 UTC. Si un departure_time plus tard que 9999-12-31T23:59:59.9999999999 Z est spécifié, l’API ramènera le departure_time à 9999-12-31T23:59:59.9999999999 Z. Alternativement, vous pouvez spécifier une valeur de now, qui définit l’heure de départ à l’heure actuelle (correcte à la seconde la plus proche). L’heure de départ peut être spécifiée dans deux cas:
  • Pour les demandes où le mode de voyage est le transit: Vous pouvez éventuellement spécifier l’un des departure_time ou arrival_time. Si aucune heure n’est spécifiée, la valeur par défaut de departure_time est maintenant (c’est-à-dire que l’heure de départ est par défaut l’heure actuelle).
  • Pour les demandes où le mode voyage est en cours de conduite : Vous pouvez spécifier le departure_time pour recevoir un itinéraire et une durée de trajet (champ de réponse: duration_in_traffic) qui tiennent compte des conditions de circulation. Cette option n’est disponible que si la demande contient une clé API valide ou un identifiant et une signature de client du plan Premium de Google Maps Platform valides. Le departure_time doit être réglé sur l’heure actuelle ou quelque temps dans le futur. Cela ne peut pas être dans le passé.

    Remarque: Si l’heure de départ n’est pas spécifiée, le choix de l’itinéraire et la durée sont basés sur le réseau routier et les conditions de circulation moyennes indépendantes du temps. Les résultats pour une demande donnée peuvent varier dans le temps en raison des changements dans le réseau routier, des conditions de circulation moyennes actualisées et de la nature distribuée du service. Les résultats peuvent également varier entre des itinéraires presque équivalents à tout moment ou à toute fréquence.

    Remarque : Les demandes de matrice de distance spécifiant departure_time lorsque mode=driving sont limitées à un maximum de 100 éléments par requête. Le nombre d’origines multiplié par le nombre de destinations définit le nombre d’éléments.

• traffic_model (par défaut best_guess) — Spécifie les hypothèses à utiliser lors du calcul du temps dans le trafic. Ce paramètre affecte la valeur renvoyée dans le champ duration_in_traffic de la réponse, qui contient le temps prévu dans le trafic en fonction des moyennes historiques. Le paramètre traffic_model ne peut être spécifié que pour les demandes dont le mode de déplacement est driving, et où la demande inclut un departure_time, et uniquement si la demande inclut une clé API ou un identifiant client de plan Premium Google Maps Platform. Les valeurs disponibles pour ce paramètre sont:
  • best_guess (par défaut) indique que le duration_in_traffic retourné doit être la meilleure estimation du temps de trajet compte tenu de ce que l’on sait à la fois des conditions de trafic historiques et du trafic en direct. Le trafic en direct devient plus important plus le departure_time est proche de maintenant.
  • pessimistic indique que le duration_in_traffic retourné doit être plus long que le temps de trajet réel la plupart du temps, bien que des jours occasionnels avec des conditions de circulation particulièrement mauvaises puissent dépasser cette valeur.
  • optimistic indique que le duration_in_traffic retourné doit être plus court que le temps de trajet réel la plupart du temps, bien que des jours occasionnels avec des conditions de circulation particulièrement bonnes puissent être plus rapides que cette valeur.
• transit_mode — Spécifie un ou plusieurs modes de transit préférés. Ce paramètre ne peut être spécifié que pour les requêtes où mode est transit. Le paramètre prend en charge les arguments suivants:
  • bus indique que l’itinéraire calculé devrait préférer voyager en bus.
  • subway indique que l’itinéraire calculé devrait préférer voyager en métro.
  • train indique que l’itinéraire calculé devrait préférer voyager en train.
  • tram indique que l’itinéraire calculé devrait préférer le tramway et le train léger.
  • rail indique que l’itinéraire calculé devrait préférer voyager en train, tram, train léger sur rail et métro. Ceci est équivalent à transit_mode=train|tram|subway.
• transit_routing_preference — Spécifie les préférences pour les demandes de transit. En utilisant ce paramètre, vous pouvez biaiser les options renvoyées, plutôt que d’accepter la meilleure route par défaut choisie par l’API. Ce paramètre ne peut être spécifié que pour les requêtes où mode est transit. Le paramètre prend en charge les arguments suivants:
  • less_walking indique que l’itinéraire calculé doit préférer des quantités limitées de marche.
  • fewer_transfers indique que la route calculée doit préférer un nombre limité de transferts.

Modes de déplacement

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

• driving (par défaut) indique le calcul de la distance en utilisant le réseau routier.
• walking demande le calcul de la distance pour la marche via les chemins piétonniers & trottoirs (le cas échéant).
• bicycling demande le calcul de la distance pour le vélo via les pistes cyclables &rues préférées (le cas échéant).
• transit demande le calcul de la distance via les itinéraires de transport en commun (le cas échéant). Cette valeur ne peut être spécifiée que si la demande comprend une clé API ou un identifiant client du plan Premium de Google Maps Platform. Si vous définissez le mode sur transit vous pouvez éventuellement spécifier un departure_time ou un arrival_time. Si aucune heure n’est spécifiée, la valeur par défaut de departure_time est maintenant (c’est-à-dire que l’heure de départ est par défaut l’heure actuelle). Vous pouvez également éventuellement inclure un transit_mode et/ou un transit_routing_preference.

Informations sur le trafic

Les informations sur le trafic sont utilisées lorsque toutes les conditions suivantes s’appliquent (ce sont les conditions requises pour recevoir le champ duration_in_traffic dans la réponse de la matrice de distance) :

• Le paramètre travel mode est driving, ou n’est pas spécifié (driving est le mode de déplacement par défaut).
• La requête inclut un paramètre departure_time valide. Le departure_time peut être réglé sur l’heure actuelle ou quelque temps dans le futur. Cela ne peut pas être dans le passé.

En option, vous pouvez inclure le paramètre traffic_model dans votre requête pour spécifier les hypothèses à utiliser lors du calcul du temps dans le trafic.

L’URL suivante initie une demande de Matrice de distance pour les distances de conduite entre Boston, MA ou Charlestown, MA, et Lexington, MA et Concord, MA. La demande comprend une heure de départ, répondant à toutes les exigences pour renvoyer le champ duration_in_traffic dans la réponse de la matrice de distance.

Restrictions

Des distances peuvent être calculées qui respectent certaines restrictions. Les restrictions sont indiquées par l’utilisation du paramètre avoid, et un argument de ce paramètre indiquant la restriction à éviter. Les restrictions suivantes sont prises en charge :

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

* Remarque : l’ajout de restrictions n’exclut pas les itinéraires qui incluent la fonctionnalité restreinte ; il biaisera le résultat vers des itinéraires plus favorables.

Systèmes unitaires

Les résultats de la matrice de distance contiennent des champs text dans les champs distance pour indiquer la distance de l’itinéraire calculé. Le système d’unités à utiliser peut être spécifié :

• 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 du système d’unités n’affecte que les champs text affichés dans les champs distance. Les champs distance contiennent également values qui sont toujours exprimés en mètres.

Réponses de matrice de distance

Les réponses aux requêtes d’API de matrice de distance sont renvoyées dans le format indiqué par l’indicateur output dans le chemin de la requête d’URL.

Deux exemples de requêtes HTTP sont présentés ci-dessous, demandant la distance et la durée de Vancouver, BC, Canada et de Seattle, WA, États-Unis, à San Francisco, CA, États-Unis et à Victoria, BC, Canada.

Cette requête démontre l’utilisation de l’indicateur JSON output:

Cette requête démontre en utilisant le drapeau XML output:

Cette requête renverra quatre éléments – deux origines fois deux destinations :

Les résultats sont renvoyés en lignes, chaque ligne contenant une origine associée à chaque destination.

Vous pouvez le tester en entrant l’URL dans votre navigateur Web (assurez-vous de remplacer YOUR_API_KEY par votre clé API réelle).

Sélectionnez les onglets ci-dessous pour voir les exemples de réponses JSON et XML.

Le reste de cette documentation utilisera la syntaxe JSON.

Éléments de réponse de la matrice de distance

Les réponses de la matrice de distance contiennent les éléments racine suivants :

• status contient des métadonnées sur la requête. Voir les codes d’état ci-dessous.
• origin_addresses contient un tableau d’adresses renvoyées par l’API à partir de votre requête d’origine. Ceux-ci sont formatés par le géocodeur et localisés selon le paramètre language passé avec la requête.
• destination_addresses contient un tableau d’adresses renvoyées par l’API à partir de votre requête d’origine. Comme avec origin_addresses, ceux-ci sont localisés le cas échéant.
• rows contient un tableau de elements, qui à leur tour contiennent chacun un statusduration, et distance élément.

Codes d’état

Les champs status de l’objet response contiennent l’état de la requête et peuvent contenir des informations de débogage utiles. L’API Distance Matrix renvoie un champ d’état de niveau supérieur, avec des informations sur la demande en général, ainsi qu’un champ d’état pour chaque champ d’élément, avec des informations sur ce couplage origine-destination particulier.

Codes d’état de niveau supérieur

• OK indique que la réponse contient un result valide.
• INVALID_REQUEST indique que la requête fournie n’était pas valide.
• MAX_ELEMENTS_EXCEEDED indique que le produit des origines et des destinations dépasse la limite par requête.
• MAX_DIMENSIONS_EXCEEDED indique que le nombre d’origines ou de destinations dépasse la limite par requête.
• OVER_DAILY_LIMIT indique l’un des éléments suivants :
  • La clé API est manquante ou invalide.
  • La facturation n’a pas été activée sur votre compte.
  • Un plafond d’utilisation auto-imposé a été dépassé.
  • Le mode de paiement fourni n’est plus valide (par exemple, une carte de crédit a expiré).

  Consultez la FAQ Maps pour savoir comment résoudre ce problème.

• OVER_QUERY_LIMIT indique que le service a reçu trop de demandes de votre application dans le délai imparti.
• REQUEST_DENIED indique que le service a refusé l’utilisation du service de matrice de distance par votre application.
• UNKNOWN_ERROR indique qu’une requête de matrice de distance n’a pas pu être traitée en raison d’une erreur de serveur. La demande peut aboutir si vous réessayez.

Codes d’état au niveau de l’élément

• OK indique que la réponse contient un result valide.
• NOT_FOUND indique que l’origine et/ou la destination de ce couplage n’ont pas pu être géocodées.
• ZERO_RESULTS indique qu’aucun itinéraire n’a pu être trouvé entre l’origine et la destination.
• MAX_ROUTE_LENGTH_EXCEEDED indique que la route demandée est trop longue et ne peut pas être traitée.

Messages d’erreur

Lorsque le code d’état de niveau supérieur est autre que OK, il peut y avoir un champ error_message supplémentaire dans l’objet de réponse de la matrice de distance. Ce champ contient des informations plus détaillées sur les raisons du code d’état donné.

Remarque: Ce champ n’est pas garanti pour être toujours présent, et son contenu est sujet à changement.

Lignes

Lorsque l’API Distance Matrix renvoie des résultats, elle les place dans un tableau JSON rows. Même si aucun résultat n’est renvoyé (par exemple lorsque les origines et / ou les destinations n’existent pas), il renvoie toujours un tableau vide. Les réponses XML se composent de zéro ou plusieurs éléments <row>.

Les lignes sont ordonnées en fonction des valeurs du paramètre origin de la requête. Chaque ligne correspond à une origine, et chaque element dans cette ligne correspond à un appariement de l’origine avec une valeur destination.

Chaque tableau row contient une ou plusieurs entrées element, qui à leur tour contiennent les informations sur un seul appariement origine-destination.

Elements

Les informations sur chaque appariement origine-destination sont renvoyées dans une entrée element. Un element contient les champs suivants :

• status : Voir Codes d’état pour une liste des codes d’état possibles.
• duration: Le temps qu’il faut pour parcourir cet itinéraire, exprimé en secondes (le champ value) et en tant que text. La représentation textuelle est localisée en fonction du paramètre language de la requête.

• duration_in_traffic: Le temps nécessaire pour parcourir cet itinéraire, en fonction des conditions de circulation actuelles et historiques. Voir le paramètre de requête traffic_model pour les options que vous pouvez utiliser pour demander que la valeur renvoyée soit optimiste, pessimiste ou une estimation optimale. La durée est exprimée en secondes (le champ value) et en tant que text. La représentation textuelle est localisée en fonction du paramètre language de la requête. La durée dans le trafic n’est renvoyée que si toutes les valeurs suivantes sont vraies :

  • La requête inclut un paramètre departure_time.
  • La demande comprend une clé API valide ou un identifiant et une signature de client Google Maps Platform Premium.
  • Les conditions de circulation sont disponibles pour l’itinéraire demandé.
  • Le paramètre mode est défini sur driving.
• distance: La distance totale de cet itinéraire, exprimée en mètres (value) et en text. La valeur textuelle utilise le système d’unités spécifié avec le paramètre unit de la requête d’origine ou de la région d’origine.
• fare: S’il est présent, contient le tarif total (c’est-à-dire le coût total du billet) sur cet itinéraire. Cette propriété n’est retournée que pour les demandes de transport en commun et uniquement pour les fournisseurs de transport en commun où des informations sur les tarifs sont disponibles. Les informations comprennent:
  • currency: Un code de devise ISO 4217 indiquant la devise dans laquelle le montant est exprimé.
  • value : Le montant total du tarif, dans la devise spécifiée ci-dessus.
  • text : Le montant total du tarif, formaté dans la langue demandée.

Voici un exemple d’un element contenant des informations sur les tarifs :

Le paramètre sensor

L’API Google Maps exigeait auparavant que vous incluiez le paramètre sensor pour indiquer si votre application utilisait asensor pour déterminer l’emplacement de l’utilisateur. Ce paramètre n’est plus requis.