API Documentation & Playground

Test Key:YOUR_API...

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).

Directions API

Returns turn-by-turn navigation between two or more waypoints, with a clean instruction list (text, distance, duration, maneuver type and location). Supports car, bike and foot, plus up to 3 alternative routes in a single call.

GET/api/1/directions

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Waypoint as lat,lng. Repeat the parameter for each stop (minimum 2).
profile	string	Optional	driving	Travel mode: driving, cycling or walking.
alternatives	integer	Optional	0	Number of alternative routes to also return (0–3).
lang	string	Optional	en	Language code for the instruction text.

Response Structure Explained

Returns { code, profile, routes[], waypoints[] }. Each route has distance (m), duration (s), a GeoJSON geometry, and an instructions[] array; each instruction includes text, type, modifier, distance, duration, name and [lat,lng] location.

Snap to Road API

Snaps raw, imprecise GPS points onto the nearest position on the road network. Repeat the point parameter for each coordinate (up to 100).

GET/api/1/snap

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	GPS point as lat,lng. Repeat the parameter for each point (maximum 100).
profile	string	Optional	driving	Road network to snap to: driving, cycling or walking.

Response Structure Explained

Returns { code, profile, snapped[] }. Each item has the original input [lat,lng], the snapped [lat,lng] position, the snap distance in metres, and the road name.

Geocoding API

Turn a search text into geographic coordinates (forward) or coordinates into an address (reverse). Fast, typo-tolerant autocomplete that covers streets, addresses and points of interest (cafes, shops, hotels, offices). Ideal for search-as-you-type.

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).
point	string	Optional	lat,lng	Coordinate (lat,lng) to reverse geocode into an address. Required when reverse=true.
limit	integer	Optional	5	Maximum number of results to return (1–20, default 5).
lang	string	Optional	en	Preferred language for result names (e.g. en, az, ru). Defaults to en.
lat	number	Optional	-	Latitude to bias results toward (nearby matches rank first). Pair with lon.
lon	number	Optional	-	Longitude to bias results toward. Pair with lat.
bbox	string	Optional	-	Restrict results to a bounding box: minLon,minLat,maxLon,maxLat.
osm_tag	string	Optional	-	Filter by OSM tag, e.g. place (settlements) or amenity:cafe. Prefix with ! to exclude.
city	string	Optional	-	Prioritize results in this city to the top (e.g. Bakı) without hiding others.
elastic	boolean	Optional	true	Elastic (fuzzy, high-recall) search — default true. Tolerates typos, missing diacritics (ə↔e), reordered words, generic words (metro, rayonu) and house numbers. Set false for strict exact matching.

Examples

# Bias to a location, only settlements
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Prioritize a city to the top
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Reverse geocode (coordinates to address)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Places (Nearby POI)

Find points of interest near a location — cafes, shops, hotels, ATMs, pharmacies and more — filtered by category and radius, sorted by distance.

GET/api/1/places

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Center coordinate lat,lng to search around (required).
radius	number	Optional	1	Search radius in kilometers (0.05–20, default 1).
category	string	Optional	-	OSM tag filter, e.g. amenity:cafe, shop, tourism:hotel. Prefix with ! to exclude. Empty = all POIs.
limit	integer	Optional	10	Max results to return (1–50, default 10).
lang	string	Optional	en	Preferred language for names (e.g. en, az, ru).

Autocomplete API

Fast, typo-tolerant place suggestions as the user types, with optional location bias.

GET/api/1/autocomplete

Parameters (Query Params)

Parameter	Type	Status	Default	Description
q	string	Required	-	Search text — partial input is fine.
limit	integer	Optional	8	Maximum number of suggestions to return (1–15).
lang	string	Optional	en	Language code for result labels.
lat	number	Optional	-	Latitude to bias results toward (optional).
lon	number	Optional	-	Longitude to bias results toward (optional).
osm_tag	string	Optional	-	Filter suggestions by OSM type, e.g. place:city.

Response Structure Explained

Returns { suggestions[], took }. Each suggestion has label, name, city, state, country, countrycode, type, osm_id and point {lat,lng}.

Batch Geocoding API

Geocode hundreds of addresses in a single request — ideal for data pipelines and imports.

POST/api/1/geocode/batch

Parameters (Query Params)

Parameter	Type	Status	Default	Description
queries	array	Required	[]	Array of address strings to geocode (max 100).
lang	string	Optional	en	Language code for result labels.
limit	integer	Optional	1	Maximum matches to return per query (1–5).

Response Structure Explained

Returns { results[], count, took }. Each result pairs the input query with a hits[] array of matches, each including label, city, country and point {lat,lng}. Results keep the input order.

Timezone API

Get the IANA time zone, current UTC offset, DST status and local time for any coordinate on Earth.

GET/api/1/timezone

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Coordinate as lat,lng.
lat	number	Optional	-	Latitude (alternative to point).
lon	number	Optional	-	Longitude (alternative to point).
timestamp	integer	Optional	now	Unix time (seconds) or ISO date to resolve the offset for; defaults to now.

Response Structure Explained

Returns { timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time }. utc_offset is a +HH:MM string, dst is true when daylight saving is active, and local_time is an ISO timestamp with the zone offset.

Elevation API

Height above sea level, in metres, for any coordinate — one point or a whole route profile.

GET/api/1/elevation

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Coordinate as lat,lng. Repeat for each point (up to 100 on GET).

Response Structure Explained

Returns { results[], unit:"meters" }, where each result is { point:{lat,lng}, elevation }. elevation is metres above sea level (null if unknown, 0 over sea). For a single point, a top-level elevation is also included. For large batches, POST { points:[[lat,lng],...] } (up to 1000).

Boundary Lookup API

Find which country, state, city and district a coordinate falls in — with the boundary polygon on request.

GET/api/1/boundary

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Coordinate as lat,lng.
polygon	boolean	Optional	false	Set true to also return the boundary as GeoJSON.
lang	string	Optional	en	Language code for place names.

Response Structure Explained

Returns { point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } and, when polygon=true, a boundary GeoJSON geometry.

Geofencing API

Test in one call which of your zones each point falls inside — polygon or circular fences.

POST/api/1/geofence

Parameters (Query Params)

Parameter	Type	Status	Default	Description
fences	array	Required	[]	Array of fences: { id?, polygon:[[lat,lng],...] } or { id?, center:[lat,lng], radius_m }. Up to 100.
points	array	Required	[]	Array of [lat,lng] points to test (up to 1000).

Response Structure Explained

Returns { results[], count }. Each result is { point:{lat,lng}, inside:[fenceId,...] } listing every fence the point falls inside (empty when none).

Elevation Profile API

Elevation at every point of a path plus total ascent, descent and distance — a full route profile.

POST/api/1/elevation/profile

Parameters (Query Params)

Parameter	Type	Status	Default	Description
points	array	Required	[]	Array of [lat,lng] points forming the path (>=2, up to 2000).
polyline	string	Optional	-	Encoded polyline as an alternative to points.

Response Structure Explained

Returns { profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit }. Each profile item is { point, elevation, distance } (metres).

Solar API

Sunrise, sunset, twilight, solar noon and day length for any coordinate and date.

GET/api/1/solar

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Coordinate as lat,lng.
date	string	Optional	today	Date (YYYY-MM-DD) to compute times for; defaults to today.

Response Structure Explained

Returns { point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds }. Times are UTC ISO strings; null in polar day/night.

Geometry Utilities API

Distance, bearing, area, centroid, simplification and polyline encode/decode — spatial math as a service.

POST/api/1/geometry

Parameters (Query Params)

Parameter	Type	Status	Default	Description
op	string	Required	distance	Operation: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode or polyline_decode.
from	array	Optional	[lat,lng]	Start point [lat,lng] (for distance/bearing/destination/midpoint).
to	array	Optional	[lat,lng]	End point [lat,lng] (for distance/bearing/midpoint).
path	array	Optional	[]	Array of [lat,lng] (for length/simplify/polyline_encode).
polygon	array	Optional	[]	Array of [lat,lng] ring (for area).

Response Structure Explained

Returns { op, ... } with the result of the chosen operation, e.g. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } or { polyline }.

Coordinate Conversion API

Convert latitude/longitude to and from UTM and MGRS grid references.

GET/api/1/convert

Parameters (Query Params)

Parameter	Type	Status	Default	Description
point	string	Required	lat,lng	Coordinate as lat,lng to convert to UTM/MGRS.
mgrs	string	Optional	-	MGRS string to reverse-convert into a coordinate.

Response Structure Explained

Returns { point, mgrs, utm:{ zone, band, easting, northing, hemisphere } }. When mgrs= is supplied, returns { mgrs, point }.

Country Info API

Currency, calling code, languages, capital and flag for any country by ISO code or name.

GET/api/1/country

Parameters (Query Params)

Parameter	Type	Status	Default	Description
code	string	Required	AZ	ISO 3166 alpha-2 or alpha-3 country code (e.g. AZ or AZE).
name	string	Optional	-	Country name as an alternative to code.

Response Structure Explained

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

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 — each with an id, optional capacity, and a start location as a [lon, lat] array (longitude first).
services	array	Required	[]	The stops to serve — each with an id, a location as a [lon, lat] array (longitude first), and optional service time. Same coordinate order as all our other endpoints.

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.

Official SDKs

Zero dependencies, fully typed, every endpoint covered. Make your first call in under a minute.

osrmrouteosrmrouteSee the SDKs