Documentation de l'API et Playground

Clé de test :YOUR_API...

Introduction

L'API OSRMRoute Directions est un service web RESTful conçu pour intégrer un routage géospatial rapide et hautes performances, des matrices de trajets, la recherche d'adresses (géocodage) et l'optimisation d'itinéraires dans vos applications. Cette documentation explique en détail toutes les capacités de l'API, les paramètres et les étapes d'intégration.

Authentification

Les requêtes à l'API OSRMRoute utilisent une clé API unique pour l'authentification. Vous pouvez ajouter votre clé API à chaque requête en tant que paramètre de requête (?key=YOUR_KEY) ou via l'en-tête HTTP Authorization (comme jeton Bearer).

GETAny endpoint

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
key	string	Obligatoire	-	La clé API unique obtenue depuis votre tableau de bord personnel. Cette clé détermine les limites de vos requêtes.

Codes d'erreur

OSRMRoute utilise des codes de statut HTTP standard et des messages d'erreur JSON détaillés pour indiquer l'état d'une requête.

Explication de la structure de la réponse

Principaux codes de statut et leur signification : - **200 OK** : La requête a abouti. - **400 Bad Request** : Les paramètres sont invalides ou manquants. - **401 Unauthorized** : La clé API n'a pas été fournie ou est invalide. - **403 Forbidden** : La clé API est bloquée ou inactive. - **429 Too Many Requests** : La limite quotidienne de crédits a été dépassée. - **500 Internal Error** : Une erreur interne du système s'est produite.

Routing API

Calcule l'itinéraire le plus rapide et le plus court du point A au point B (avec des points via intermédiaires). Renvoie des instructions détaillées (turn-by-turn) et une géométrie GeoJSON pour différents profils de transport (driving, cycling, walking).

GET/api/v1/osrm/route/v1/{profile}/{coordinates}

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
profile	string	Obligatoire	driving	Profil du mode de transport. Valeurs prises en charge : driving (voiture), cycling (vélo), walking (piéton).
coordinates	string	Obligatoire	-	Coordonnées des points. Format : lon,lat;lon,lat;lon,lat... (au moins 2 points).
overview	string	Facultatif	full	Niveau de détail de la géométrie d'itinéraire renvoyée : simplified (simplifiée), full (géométrie complète), false (sans géométrie).
geometries	string	Facultatif	geojson	Format de géométrie : geojson (objet GeoJSON), polyline (chaîne encodée).
steps	boolean	Facultatif	true	Si des instructions étape par étape sont renvoyées pour chaque virage.

Explication de la structure de la réponse

Une réponse réussie contient la distance totale de l'itinéraire (en mètres), la durée du trajet (en secondes), les points de passage et la ligne d'itinéraire en GeoJSON.

Matrix API

Calcule une matrice rapide de distance et de temps de trajet entre plusieurs points (un tableau NxM). Un outil idéal pour optimiser les itinéraires logistiques.

GET/api/v1/osrm/table/v1/{profile}/{coordinates}

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
profile	string	Obligatoire	driving	Profil de transport (driving, cycling, walking).
coordinates	string	Obligatoire	-	Points de la matrice. Format : lon,lat;lon,lat;lon,lat...
annotations	string	Facultatif	duration,distance	Données à calculer : duration (temps), distance ou les deux.

Explication de la structure de la réponse

Une réponse réussie renvoie un tableau-matrice bidimensionnel de distances et de durations (durées) pour chaque combinaison de point de départ et d'arrivée.

Map Matching API

Aligne des traces GPS imprécises sur le réseau routier réel (snap to road). Utilisé pour nettoyer le bruit dans les signaux GPS.

GET/api/v1/osrm/match/v1/{profile}/{coordinates}

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
profile	string	Obligatoire	driving	Profil de transport.
coordinates	string	Obligatoire	-	La séquence de coordonnées GPS à aligner (lon,lat;lon,lat...)
overview	string	Facultatif	full	Précision de la géométrie de l'itinéraire aligné.

Nearest API

Aligne n'importe quelle coordonnée sur le segment de route réel le plus proche (snap) et renvoie des informations sur le nom de la route.

GET/api/v1/osrm/nearest/v1/{profile}/{coordinates}

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
profile	string	Obligatoire	driving	Profil de transport.
coordinates	string	Obligatoire	-	Le point à proximité duquel chercher. Format : lon,lat (une seule paire).
number	integer	Facultatif	3	Le nombre de routes candidates les plus proches à trouver.

Trip API

Résout le problème du voyageur de commerce (TSP) : trouve l'itinéraire circulaire (ou ouvert) le plus optimal pour visiter un ensemble de points donné et ordonne les points.

GET/api/v1/osrm/trip/v1/{profile}/{coordinates}

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
profile	string	Obligatoire	driving	Profil de transport.
coordinates	string	Obligatoire	-	Points à visiter. Format : lon,lat;lon,lat...
source	string	Facultatif	any	Le point où l'itinéraire peut commencer (any ou le premier point).
destination	string	Facultatif	any	Le point où l'itinéraire se termine (any ou le dernier point).

Directions API

Renvoie une navigation détaillée entre deux points ou plus avec une liste d’instructions claire (texte, distance, durée, type de manœuvre et position). Prend en charge voiture, vélo et à pied, ainsi que jusqu’à 3 itinéraires alternatifs en un seul appel.

GET/api/1/directions

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Point au format lat,lng. Répétez le paramètre pour chaque arrêt (minimum 2).
profile	string	Facultatif	driving	Mode de déplacement : driving, cycling ou walking.
alternatives	integer	Facultatif	0	Nombre d’itinéraires alternatifs supplémentaires à renvoyer (0–3).
lang	string	Facultatif	en	Code de langue du texte des instructions.

Explication de la structure de la réponse

Renvoie { code, profile, routes[], waypoints[] }. Chaque itinéraire a distance (m), duration (s), une géométrie GeoJSON et un tableau instructions[] ; chaque instruction inclut text, type, modifier, distance, duration, name et location [lat,lng].

Snap to Road API

Aligne des points GPS bruts et imprécis sur la position la plus proche du réseau routier. Répétez le paramètre point pour chaque coordonnée (jusqu’à 100).

GET/api/1/snap

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Point GPS au format lat,lng. Répétez le paramètre pour chaque point (maximum 100).
profile	string	Facultatif	driving	Réseau routier cible : driving, cycling ou walking.

Explication de la structure de la réponse

Renvoie { code, profile, snapped[] }. Chaque élément contient l’input d’origine [lat,lng], la position alignée [lat,lng], la distance d’alignement en mètres et le nom de la voie.

Geocoding API

Convertit un texte de recherche en coordonnées géographiques (directe) ou des coordonnées en adresse (inverse). Autocomplétion rapide et tolérante aux fautes de frappe couvrant rues, adresses et points d’intérêt (cafés, magasins, hôtels, bureaux). Idéal pour la recherche au fil de la saisie.

GET/api/1/geocode

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
q	string	Obligatoire	-	L'adresse à rechercher (par ex. : « rue Nizami, Bakou »).
reverse	boolean	Facultatif	false	Doit être true pour effectuer un géocodage inverse (recherche de coordonnée vers adresse).
point	string	Facultatif	lat,lng	Coordonnée (lat,lng) pour le géocodage inverse en adresse. Requis lorsque reverse=true.
limit	integer	Facultatif	5	Nombre maximum de résultats à renvoyer (1–20, par défaut 5).
lang	string	Facultatif	en	Langue préférée pour les noms de résultats (ex. en, az, ru). Par défaut en.
lat	number	Facultatif	-	Latitude pour orienter les résultats (les plus proches d’abord). Avec lon.
lon	number	Facultatif	-	Longitude pour orienter les résultats. Avec lat.
bbox	string	Facultatif	-	Limiter les résultats à une zone : minLon,minLat,maxLon,maxLat.
osm_tag	string	Facultatif	-	Filtrer par tag OSM, ex. place (localités) ou amenity:cafe. Préfixe ! pour exclure.
city	string	Facultatif	-	Prioriser les résultats de cette ville (ex. Bakı) en haut, sans masquer les autres.
elastic	boolean	Facultatif	true	Recherche élastique (floue, haute couverture) — true par défaut. Tolère fautes de frappe, diacritiques manquants (ə↔e), ordre des mots, mots génériques (metro, rayonu) et numéros de maison. false pour correspondance stricte.

Exemples

# Orienter vers un lieu, uniquement localités
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Prioriser une ville en haut
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Géocodage inverse (coordonnées vers adresse)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Lieux (POI à proximité)

Trouvez des points d’intérêt près d’un lieu — cafés, magasins, hôtels, distributeurs, pharmacies, etc. — filtrés par catégorie et rayon, triés par distance.

GET/api/1/places

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée centrale lat,lng (requis).
radius	number	Facultatif	1	Rayon de recherche en kilomètres (0.05–20, par défaut 1).
category	string	Facultatif	-	Filtre par tag OSM, ex. amenity:cafe, shop, tourism:hotel. Préfixe ! pour exclure. Vide = tous les POI.
limit	integer	Facultatif	10	Nombre max de résultats (1–50, par défaut 10).
lang	string	Facultatif	en	Langue préférée pour les noms (ex. en, az, ru).

Autocomplete API

Suggestions de lieux rapides et tolérantes aux fautes pendant la saisie, avec pondération géographique.

GET/api/1/autocomplete

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
q	string	Obligatoire	-	Texte de recherche — saisie partielle acceptée.
limit	integer	Facultatif	8	Nombre maximum de suggestions (1–15).
lang	string	Facultatif	en	Code de langue des libellés.
lat	number	Facultatif	-	Latitude pour pondérer les résultats (optionnel).
lon	number	Facultatif	-	Longitude pour pondérer les résultats (optionnel).
osm_tag	string	Facultatif	-	Filtrer les suggestions par type OSM, ex. place:city.

Explication de la structure de la réponse

Renvoie { suggestions[], took }. Chaque suggestion a label, name, city, state, country, countrycode, type, osm_id et point {lat,lng}.

Batch Geocoding API

Géocodez des centaines d’adresses en une seule requête — idéal pour les pipelines de données et les imports.

POST/api/1/geocode/batch

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
queries	array	Obligatoire	[]	Tableau d’adresses à géocoder (max 100).
lang	string	Facultatif	en	Code de langue des libellés.
limit	integer	Facultatif	1	Correspondances maximum par requête (1–5).

Explication de la structure de la réponse

Renvoie { results[], count, took }. Chaque résultat associe la requête d’entrée à un tableau hits[] ; chaque correspondance inclut label, city, country et point {lat,lng}. L’ordre d’entrée est conservé.

Timezone API

Fuseau horaire IANA, décalage UTC actuel, statut de l’heure d’été et heure locale pour toute coordonnée.

GET/api/1/timezone

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée au format lat,lng.
lat	number	Facultatif	-	Latitude (alternative à point).
lon	number	Facultatif	-	Longitude (alternative à point).
timestamp	integer	Facultatif	now	Temps Unix (secondes) ou date ISO pour résoudre le décalage ; par défaut maintenant.

Explication de la structure de la réponse

Renvoie { timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time }. utc_offset est une chaîne +HH:MM, dst vaut true en heure d’été, et local_time est un horodatage ISO avec le décalage du fuseau.

Elevation API

Altitude au-dessus du niveau de la mer, en mètres, pour toute coordonnée — un point ou le profil d’un itinéraire entier.

GET/api/1/elevation

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée au format lat,lng. Répétez pour chaque point (jusqu’à 100 en GET).

Explication de la structure de la réponse

Renvoie { results[], unit:"meters" }, où chaque résultat est { point:{lat,lng}, elevation }. elevation est en mètres au-dessus du niveau de la mer (null si inconnu, 0 sur mer). Pour un point unique, un champ elevation de niveau supérieur est aussi inclus. Pour les gros lots, POST { points:[[lat,lng],...] } (jusqu’à 1000).

Boundary Lookup API

Trouvez dans quel pays, région, ville et quartier se trouve une coordonnée — avec le polygone de la limite sur demande.

GET/api/1/boundary

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée au format lat,lng.
polygon	boolean	Facultatif	false	true pour renvoyer aussi la limite en GeoJSON.
lang	string	Facultatif	en	Code de langue des noms.

Explication de la structure de la réponse

Renvoie { point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } et, avec polygon=true, une géométrie de limite GeoJSON.

Geofencing API

Vérifiez en un appel dans lesquelles de vos zones tombe chaque point — clôtures polygonales ou circulaires.

POST/api/1/geofence

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
fences	array	Obligatoire	[]	Tableau de clôtures : { id?, polygon:[[lat,lng],...] } ou { id?, center:[lat,lng], radius_m }. Jusqu’à 100.
points	array	Obligatoire	[]	Tableau de points [lat,lng] à tester (jusqu’à 1000).

Explication de la structure de la réponse

Renvoie { results[], count }. Chaque résultat est { point:{lat,lng}, inside:[fenceId,...] } listant toutes les clôtures contenant le point (vide si aucune).

Elevation Profile API

Altitude en chaque point d’un trajet plus dénivelé positif, négatif et distance — un profil complet.

POST/api/1/elevation/profile

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
points	array	Obligatoire	[]	Tableau de points [lat,lng] du trajet (>=2, jusqu’à 2000).
polyline	string	Facultatif	-	Polyline encodée en alternative à points.

Explication de la structure de la réponse

Renvoie { profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit }. Chaque élément { point, elevation, distance } (mètres).

Solar API

Lever, coucher, crépuscule, midi solaire et durée du jour pour toute coordonnée et date.

GET/api/1/solar

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée au format lat,lng.
date	string	Facultatif	today	Date (YYYY-MM-DD) à calculer ; par défaut aujourd’hui.

Explication de la structure de la réponse

Renvoie { point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds }. Heures en UTC ISO ; null en jour/nuit polaire.

Geometry Utilities API

Distance, cap, aire, centroïde, simplification et polyline encode/decode — la géométrie en service.

POST/api/1/geometry

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
op	string	Obligatoire	distance	Opération : distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode ou polyline_decode.
from	array	Facultatif	[lat,lng]	Point de départ [lat,lng].
to	array	Facultatif	[lat,lng]	Point d’arrivée [lat,lng].
path	array	Facultatif	[]	Tableau de [lat,lng] (length/simplify/polyline_encode).
polygon	array	Facultatif	[]	Anneau [lat,lng] (area).

Explication de la structure de la réponse

Renvoie { op, ... } avec le résultat de l’opération, ex. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } ou { polyline }.

Coordinate Conversion API

Convertit latitude/longitude vers et depuis les références de grille UTM et MGRS.

GET/api/1/convert

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	lat,lng	Coordonnée lat,lng à convertir en UTM/MGRS.
mgrs	string	Facultatif	-	Chaîne MGRS à reconvertir en coordonnée.

Explication de la structure de la réponse

Renvoie { point, mgrs, utm:{ zone, band, easting, northing, hemisphere } }. Avec mgrs=, renvoie { mgrs, point }.

Country Info API

Devise, indicatif, langues, capitale et drapeau de tout pays par code ISO ou nom.

GET/api/1/country

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
code	string	Obligatoire	AZ	Code pays ISO 3166 alpha-2 ou alpha-3 (ex. AZ ou AZE).
name	string	Facultatif	-	Nom du pays en alternative au code.

Explication de la structure de la réponse

Renvoie { name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng, population }.

Isochrone API

Renvoie des polygones des zones géographiques accessibles depuis un point donné dans un temps ou une distance donnés.

GET/api/1/isochrone

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
point	string	Obligatoire	-	Point central. Format : lat,lon.
time_limit	integer	Facultatif	600	Limite de temps de trajet (en secondes).

Route Optimization API

Optimise les itinéraires d'une flotte de véhicules (Vehicle Routing Problem). Calcule le plan de livraison et de transport des véhicules au moindre coût.

POST/api/1/vrp

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
vehicles	array	Obligatoire	[]	La liste des véhicules — chacun avec un id, une capacité optionnelle et un point de départ sous forme de tableau [lon, lat] (longitude d'abord).
services	array	Obligatoire	[]	Les arrêts à desservir — chacun avec un id, une position sous forme de tableau [lon, lat] (longitude d'abord) et un temps de service optionnel. Même ordre de coordonnées que sur tous nos endpoints.

Location Clustering API

Regroupe (en clusters) les coordonnées données selon leur proximité et leur densité géographique.

POST/api/1/cluster

Paramètres (Query Params)

Paramètre	Type	Statut	Par défaut	Description
customers	array	Obligatoire	[]	Coordonnées des clients et poids à regrouper en clusters.

SDK officiels

Zéro dépendance, entièrement typé, tous les points de terminaison. Premier appel en moins d’une minute.

osrmrouteosrmrouteVoir les SDK