API Géocodage

Introduction

Open Street est un service d’optimisation d’itinéraires qui permet de calculer un itinéraire avec l’ordre idéal pour minimiser la distance parcourue.

Notre application web en ligne utilise les API Open Street, dont notamment celle qui permet le géocodage, c’est à dire la transformation entre une adresse postale et une coordonnée latitude,longitude.

Exécuter un géocodage 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. Attention, cette API de géocodage est susceptible de recevoir des caractères spéciaux ou accentués, qui doivent correctement être encodés en séquences commençant par un pourcentage (%). Les espaces doivent être remplacés par des plus (+). 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.

Le temps de réponse de cet API est inférieur à 500ms. Grace à notre cache interne, les réponses peuvent être plus rapides si l’information a déjà été demandée précédemment, de l’ordre de quelques millisecondes.

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
address*	1 Rue de la Paix, Paris, France	Adresse postale la plus précise possible, et dont les champs sont séparés par des virgules ou des point-virgules. Elle doit être encodée comme une URL.
key*	chaine-de-caracteres	Clé d’authentification de chaque utilisateur.

L’URL qui interroge l’api de géocodage doit être encodée correctement, c’est à dire que tous les caractères spéciaux et accentués sont transformés par des séquences commençant par le signe pourcentage (%). Les espaces doivent être transformés en le signe plus (+).

Les navigateurs modernes encodent automatiquement les adresses saisies dans la barre d’URL, mais ce n’est pas toujours le cas des librairies HTTP comme curl.

Un exemple concret

Prenons l’exemple de la préfecture de Bourg-en-Bresse dont l’adresse sera « Préfecture de l’Ain, Bourg-en-Bresse, France ».

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

Utilisation des données de géocodage

Données de sortie

Le format de données de sortie est un objet 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.

Le document ainsi obtenu est compatible avec Google Geocoding API, tout en omettant les détails superflus. Si vous avez déjà développé une application qui utilise cette API, vous connaissez déjà le fonctionnement. Nous utilisons différentes bases de données pour ce service, donc les résultats peuvent parfois varier de ceux de Google.

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

Paramètre	Explication
formatted_address	Adresse corrigée telle qu’elle a été comprise par l’API.
lat	Latitude du point demandé.
lng	Longitude du point demandé.
status	Code de status

La structure du document n’a pas été représentée dans ce document, mais l’objet json contient également les chaînes suivantes : results, geometry, location.

 

Conseils d’utilisation

Lorsque vous traitez cet 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é. Vous pouvez sans risque transformer l’objet json en tableau de votre language de programmation avec une librairie spécialisée, à la condition de conserver les chaînes et les valeurs. 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 languages.

Vous pouvez utiliser cette API en lien avec notre API d’optimisation de tournées. Dans ce cas il est conseillé de lancer le géocodage le plus tôt possible, et de ne pas attendre que l’utilisateur lance un calcul d’optimisation. La fluidité de votre application sera ainsi améliorée.

Si vous connaissez d’avance la liste des adresses que vous êtes susceptible de demander, vous avez intérêt à lancer toutes vos requêtes de géocodage une première fois avec un script de votre création. Ainsi, toutes les futures requêtes bénéficieront de notre cache intégré, et seront beaucoup plus rapides.

Contrairement à notre API d’optimisation, nos routines de géocodage ne sont pas particulièrement plus performantes que celles disponibles gratuitement sur internet. Ainsi, si vos besoins de géocodage sont particulièrement importants, nous vous conseillons de vous appuyer en premier lieu sur Google Geocoding API ou un service équivalent, et de n’utiliser notre API de géocodage qu’en cas d’échec.

Les codes d’erreur

Le code de status standard doit être "OK". Pour toute autre valeur de retour, la requête de géocodage 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.
WRONG_KEY	Votre clé d’authentification est fausse. Contactez-nous.
ADDRESS_IS_INCONSISTENT	L’adresse demandée est une chaîne de caractères beaucoup trop courte, ou beaucoup trop longue.
REQUEST_DENIED / QUERY_FAILED	Impossible de répondre à cette requête. Le backend de géocodage n’est pas opérationnel.
INVALID_REQUEST	Impossible de répondre à cette requête. Le backend de géocodage n’est pas à jour.
LOW_CREDIT	Le coût de l’opération est supérieur au solde de l’espace client.
TIMEOUT / UNKNOWN_ERROR	Le délai de traitement normal a expiré. Ré-essayez ultérieurement.
OVER_QUERY_LIMIT	La requête n’a pu être traitée car notre infrastructure est trop fortement sollicitée en ce moment.
ZERO_RESULTS	La requête a réussi mais le lieu n’a pas été trouvé. Vous pouvez ré-essayer avec un numéro du rue différent ou une rue perpendiculaire proche en respectant les bonnes pratiques.

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.

Développements à venir

• D’autres paramètres facultatifs sont susceptibles de voir le jour pour affiner le calcul.
• La méthode GET du protocole HTTP limite la taille des requêtes à 8 Ko