API Documentation & Playground

Test Key:b602a7df...

Introduction

The OSRMRoute Directions API is a RESTful web service built to integrate fast, high-performance geospatial routing, travel matrices, address search (geocoding) and route optimization into your applications. This documentation explains all of the API's capabilities, parameters and integration steps in detail.

Authentication

OSRMRoute API requests use a unique API key for authentication. You can add your API key to each request as a query parameter (?key=YOUR_KEY) or via the HTTP Authorization header (as a Bearer token).

GETAny endpoint

Parameters (Query Params)

Parameter	Type	Status	Default	Description
key	string	Required	-	The unique API key obtained from your personal dashboard. This key determines the limits of your requests.

Error Codes

OSRMRoute uses standard HTTP status codes and detailed JSON error messages to indicate the state of a request.

Response Structure Explained

Main status codes and their meaning: - **200 OK**: The request was completed successfully. - **400 Bad Request**: Parameters are invalid or missing. - **401 Unauthorized**: The API key was not provided or is invalid. - **403 Forbidden**: The API key is blocked or inactive. - **429 Too Many Requests**: The daily credit limit was exceeded. - **500 Internal Error**: An internal system error occurred.

Routing API

Computes the fastest and shortest route from point A to point B (with intermediate via-points). Returns turn-by-turn instructions and GeoJSON geometry for different transport profiles (driving, cycling, walking).

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

Parameters (Query Params)

Parameter	Type	Status	Default	Description
profile	string	Required	driving	Transport mode profile. Supported values: driving (car), cycling (bike), walking (pedestrian).
coordinates	string	Required	-	Coordinates of the points. Format: lon,lat;lon,lat;lon,lat... (at least 2 points).
overview	string	Optional	full	Detail level of the returned route geometry: simplified, full (full geometry), false (no geometry).
geometries	string	Optional	geojson	Geometry format: geojson (GeoJSON object), polyline (encoded string).
steps	boolean	Optional	true	Whether step-by-step instructions are returned for each turn.

Response Structure Explained

A successful response contains the route's total distance (in meters), travel duration (in seconds), waypoints and the GeoJSON route line.

Matrix API

Computes a fast distance and travel-time matrix between multiple points (an NxM table). An ideal tool for optimizing logistics routes.

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

Parameters (Query Params)

Parameter	Type	Status	Default	Description
profile	string	Required	driving	Transport profile (driving, cycling, walking).
coordinates	string	Required	-	Matrix points. Format: lon,lat;lon,lat;lon,lat...
annotations	string	Optional	duration,distance	Data to compute: duration (time), distance, or both.

Response Structure Explained

A successful response returns a two-dimensional distances and durations matrix table for every start-and-end point combination.

Map Matching API

Snaps imprecise GPS traces to the real road network (snap to road). Used to clean up noise in GPS signals.

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

Parameters (Query Params)

Parameter	Type	Status	Default	Description
profile	string	Required	driving	Transport profile.
coordinates	string	Required	-	The sequence of GPS coordinates to snap (lon,lat;lon,lat...)
overview	string	Optional	full	Geometry precision of the matched route.

Nearest API

Snaps any coordinate to the nearest real road segment and returns information about the road name.

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

Parameters (Query Params)

Parameter	Type	Status	Default	Description
profile	string	Required	driving	Transport profile.
coordinates	string	Required	-	The point to search near. Format: lon,lat (a single pair).
number	integer	Optional	3	The number of nearest road candidates to find.

Trip API

Solves the Traveling Salesman Problem (TSP): finds the most optimal round (or open) route to visit a given set of points and orders the points.

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

Parameters (Query Params)

Parameter	Type	Status	Default	Description
profile	string	Required	driving	Transport profile.
coordinates	string	Required	-	Points to visit. Format: lon,lat;lon,lat...
source	string	Optional	any	The point the route can start from (any or the first point).
destination	string	Optional	any	The point the route ends at (any or the last point).

Geocoding API

Converts addresses to geographic coordinates (or vice versa). Ideal for integrated search systems.

GET/api/1/geocode

Parameters (Query Params)

Parameter	Type	Status	Default	Description
q	string	Required	-	The address to search (e.g. "Nizami Street, Baku").
reverse	boolean	Optional	false	Must be true to perform reverse geocoding (searching from coordinate to address).

Isochrone API

Returns polygons of the geographic zones reachable from a given point within a given time or distance.

GET/api/1/isochrone

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	-	Center point. Format: lat,lon.
time_limit	integer	Optional	600	Travel time limit (in seconds).

Route Optimization API

Optimizes the routes of a vehicle fleet (Vehicle Routing Problem). Computes the delivery and haulage plan of vehicles at the lowest cost.

POST/api/1/vrp

Parameters (Query Params)

Parameter	Type	Status	Default	Description
vehicles	array	Required	[]	The list of vehicles (id, capacity, start address, etc.).
services	array	Required	[]	The addresses to be serviced (id, coordinates, service time, etc.).

Location Clustering API

Groups (clusters) given coordinates by their geographic proximity and density.

POST/api/1/cluster

Parameters (Query Params)

Parameter	Type	Status	Default	Description
customers	array	Required	[]	Customer coordinates and weights to be clustered.