API Route

Sommaire

Introduction

Notre application web Open Street utilise des API, notamment celle qui permet d’afficher sur une carte le tracé d’un itinéraire par la route, entre deux points (ou plus). Cet article décrit le fonctionnement de cet API pour votre propre usage.

Consultation de l'itinéraire optimisé

Les marqueurs rouges sont reliés par des routes en bleu

Sur l’image ci-dessus, on remarque les marqueurs rouges, et les étapes en bleu. Une étape relie un point de départ et une destination. Pour tracer une étape, on utilise un polyline, c’est à dire une ligne brisée constituée d’une succession de coordonnées GPS.

Demander un tracé avec l’API

Protocole utilisé

Cette API utilise la méthode GET implémentée dans le protocole HTTP 1.1. On peut donc l’utiliser depuis un navigateur web standard ou toute autre librairie permettant de télécharger des données depuis un serveur web. Cette API d’optimisation n’est pas susceptible de recevoir de caractères spéciaux ou accentués, mais les URL doivent tout de même être correctement encodées. Les navigateurs récents encodent automatiquement les URL mais pas toujours les librairies HTTP.

Toutes nos API supportent la compression gzip, il est donc fortement conseillé d’activer cette fonctionnalité dans votre client HTTP. Pour vérifier que la compression est active, l’en-tête de la requête du client doit comporter Accept-Encoding : "gzip, deflate" et l’en-tête de la réponse du serveur doit comporter Content-Encoding : "gzip" . Cela permet de diminuer de près de 50% le temps de téléchargement des données. La compression est particulièrement efficace avec cette API, c’est pourquoi il est important de l’activer.

Le temps de réponse de cet API est inférieur à 100ms, que les requêtes aient été précédemment demandées ou pas.

Données d’entrée

Pour fonctionner, cette API a besoin de données qui sont fournies en tant que paramètres d’URL. Dans la tableau ci-dessous, les astérisques* indiquent les paramètres qui sont obligatoires pour lancer un calcul.

Paramètre Valeur Explication
origin* 48.856614,2.352221 Coordonnée du point de départ. Les nombres doivent comporter un maximum de 10 décimales.
destination* 45.764043,4.835659 Coordonnée du point d’arrivée. Les nombres doivent comporter un maximum de 10 décimales.
mode* driving, walkingou trucking Mode de transport voiture (driving) ou à pieds (walking).
key* chaine-de-caracteres Clé d’authentification de chaque utilisateur.

Un exemple concret

Prenons l’exemple du tracé de l’itinéraire entre Paris et Lyon

Voici à quoi ressemble la requête formulée pour l’API de polylines. Notez qu’une clé d’authentification valide est requise.

Utilisation des données

Données de sortie

Le format de données de sortie est un document json qui peut être téléchargé et traité par une application, ou encore visualisé par un navigateur. La compression liée au protocole HTTP est gérée par le client HTTP de manière transparente pour le développeur.

Voici ci-après le tableau des paramètres de sortie.

Paramètre Explication
polyline Chaine de caractères qui contient le tracé géographique.
total_distance Distance en m.
total_time Temps en secondes.
status Code de status

La structure de l’objet json est très simple. La valeur derrière la chaîne "polyline" peut atteindre tout de même plusieurs dizaines de kilo-octets. C’est pourquoi nous insistons lourdement sur la nécessité d’activer la compression gzip coté client.

Le polyline est une méthode d’encodage d’une liste de coordonnées géographiques qui décrivent un tracé. Elle a été définie par Google et est reprise par plusieurs projets cartographiques. C’est une méthode efficace pour « compresser » une longue liste de coordonnées en une chaîne de caractères moins longue.

Le bloc ci-dessus est un résultat produit par notre API. Pour une meilleure lisibilité, le polyline a été tronqué et il n’est donc pas valide.

Conseils d’utilisation

Lorsque vous traitez l’objet json, vous devez impérativement récupérer les valeurs grâce à leur chaîne associée, et non pas par leur position dans le document ou leur numéro de ligne. En effet, d’autres données sont susceptibles de s’intercaler à l’avenir et c’est le seul moyen de respecter la compatibilité. Pour plus d’informations sur json, consultez le site json.org qui fournit une liste complète de librairies de décodage dans différents langages.

Vous pouvez utiliser cette API en lien avec notre API d’optimisation de tournées ou notre API de géocodage.

Il n’y a pas de cache lié à cette API, et donc pas de gain à espérer en répétant un calcul plusieurs fois.

Pour une superposition impeccable du polyline avec votre fond de carte, nous vous recommandons d’utiliser une carte issue du projet OpenStreetMap ®. Nous pouvons vous conseiller à ce sujet si besoin.

Les codes d’erreur

Le code de status standard doit être "OK". Pour toute autre valeur de retour, la requête aura échoué. Le tableau ci-dessous décrit la signification des différents codes que vous pouvez rencontrer en utilisant notre API.

Code Explication
SYNTAX_ERROR La requête est incomplète ou comporte une erreur.
LIMIT_REACHED Vous avez épuisé vos quotas d’utilisation. En savoir plus.
LOW_CREDIT Le coût de l’opération est supérieur au solde de l’espace client.
WRONG_KEY Votre clé d’authentification est fausse. Contactez-nous.
WRONG_VER Vous avez sollicité une version d’API non valable.
WRONG_METHOD Un des paramètres a été soumis en POST au lieu de GET (ou l’inverse).
REQUEST_DENIED Impossible de répondre à cette requête.
MISSING_CHILD_PARAMETER / MISSING_PARENT_PARAMETER / MISSING_PARAMETER Il manque un paramètre pour que la requête soit complète.
UNKNOWN_PARAMETER Un paramètre est inconnu.
REQUEST_TOO_LONG Les paramètres font une taille cumulée de plus de 4000 caractères, ce qui est beaucoup trop pour être valide.
WRONG_LATLON Les coordonnées GPS ne sont pas des décimaux positifs ou négatifs entre 1 et 10 décimales.

Vous pouvez voir comment ces codes de retour sont gérés sur notre application web, avec la page d’explication des messages d’erreurs du GUI pour les utilisateurs.

Exemple d’utilisation

Vous l’aurez compris, un polyline est une chaîne de caractères qui, une fois interprétée correctement par une application cartographique, s’affiche sous la forme d’un tracé sur une carte. Il peut être converti en une liste de coordonnées latitude,longitude grâce à une fonction de décodage appropriée. On en trouve sur internet.

Lors du décodage, il faut faire très attention à la précision décimale préalablement employée lors de l’encodage. Les API de Google encodent les polylines avec une précision de 5 décimales, tandis que notre API de polylines a une précision de 6 décimales.

De nombreuses librairies cartographiques sont compatibles avec ce format dont notamment OpenLayers, Leaflet, Google Maps et Bing Maps.

Une page de démonstration du tracé de polylines avec Leaflet.encoded est accessible ici. Voici une liste de projets en lien avec ce sujet.