API Documentation, SDKs & Integration Guides
Explore API endpoints, authentication, limits and examples. Set up mobile SDKs, CLI and MCP workflows, map styles, place search and road data.
API directory
Find an API by name, use case or endpoint. Each entry links to its parameters, examples and usage limits.
Navigation (10)
- Routing API →
Calculate a road route through the points in the supplied order for driving, cycling or walking. Request instructions with steps=true and select GeoJSON with geometries=geojson.
GET /api/v1/osrm/route/v1/{profile}/{coordinates} - Isochrones API →
Estimates reachability from sampled road travel times. quality.status is estimated when every sampled direction has a reachable point; otherwise it is insufficient_data and polygons is empty. Empty results do not prove there are no reachable roads. The boundary is approximate; only time limits are supported.
GET /api/1/isochrone - 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} - 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} - 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 - Alternative Routes 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 - 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 - Fuel Estimate API →
Estimate fuel volume and trip value from distance, loaded weight, observed empty/full consumption and your fuel price. Use it alone or include fuel in a Truck request.
POST /api/v1/fuel/estimate - Truck Routing API →
Plan truck routes within and across countries on connected roads. Send the dimensions and loaded weight of the vehicle with each request.
POST /api/v1/truck/route - Search Along Route API →
Discover useful stops and compare their additional driving time.
POST /api/v1/places/along-route
Operations & load planning (7)
- Route Optimization API →
Plans fleet routes with capacity, time windows, skills and paired pickup/delivery constraints. A bounded heuristic reduces travel time without guaranteeing a global optimum. Unassigned tasks remain in solution.unassigned; invalid inputs are rejected as a whole.
POST /api/1/vrp - Matrix API →
Calculate travel times, distances or both between origins and destinations. Use sources and destinations to select indexes in the coordinate list.
GET /api/v1/osrm/table/v1/{profile}/{coordinates} - Trip API (TSP) →
Order stops for one vehicle using the road network. The service can return a round trip or an open route. For an open route, send roundtrip=false&source=first&destination=last. The order is not guaranteed to be optimal.
GET /api/v1/osrm/trip/v1/{profile}/{coordinates} - Location Clustering →
Groups (clusters) given coordinates by their geographic proximity and density.
POST /api/1/cluster - Load Planning →
Plan mixed cargo for trucks, trailers and containers. Review stacking, loading order and space in 3D, or integrate the Load Planning API into your own software.
POST /api/v1/load-plansGET /api/v1/load-plansGET /api/v1/load-plans/{id}All endpoints (+38)
DELETE /api/v1/load-plans/{id}POST /api/v1/load-plans/{id}/cancelGET /api/v1/load-plans/{id}/worksheetGET /api/v1/load-plans/{id}/csvGET /api/v1/load-plans/{id}/modelGET /api/v1/load-plans/pricesGET /api/v1/load-plans/import-previewPOST /api/v1/load-plans/import-previewPOST /api/v1/load-plans/comparePOST /api/v1/load-plans/fleetPOST /api/v1/load-plans/{id}/placement-previewPOST /api/v1/load-plans/{id}/placement-revisionsGET /api/v1/load-plans/{id}/pdfGET /api/v1/load-plans/{id}/xlsxPOST /api/v1/load-plans/{id}/shareDELETE /api/v1/load-plans/{id}/sharePOST /api/v1/load-plans/shared-viewPOST /api/v1/load-plans/palletizePOST /api/v1/load-plans/{id}/axle-estimateGET /api/v1/load-plans/workspace/{kind}GET /api/v1/load-plans/workspace/{kind}/{id}PUT /api/v1/load-plans/workspace/{kind}/{id}DELETE /api/v1/load-plans/workspace/{kind}/{id}GET /api/v1/load-plans/webhookPOST /api/v1/load-plans/webhookDELETE /api/v1/load-plans/webhookGET /api/v1/load-plans/webhook/eventsPOST /api/v1/load-plans/webhook/events/{id}POST /api/v1/load-plans/multi-stopPOST /api/v1/load-plans/bulkPOST /api/v1/load-plans/packagingPOST /api/v1/load-plans/dispatchPOST /api/v1/load-plans/fulfillmentPOST /api/v1/load-plans/simulationGET /api/v1/load-plans/{id}/warehousePOST /api/v1/load-plans/{id}/warehouseGET /api/v1/load-plans/{id}/simulation-reportGET /api/v1/load-plans/partner - Trip Analytics: visit proof →
Map-matched visit, checkpoint and dwell evidence from your submitted trace.
POST /api/v1/trip-analytics/visit-proof - Truck fleet optimization →
Vehicle-specific static truck matrices with verified heuristic assignments.
POST /api/v1/truck/optimize
Search (8)
- 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 - Places API →
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 - Autocomplete API →
Fast, typo-tolerant place suggestions as the user types, with optional location bias.
GET /api/1/autocomplete - Batch Geocoding API →
Geocode up to 100 address strings per request. Results follow input order, and each query costs one credit.
POST /api/1/geocode/batch - Natural Language Search →
Find places using a short English query.
POST /api/v1/search/natural - Place details →
Read source attributes from a retrieved suggestion or route search.
POST /api/v1/places/details - Structured Geocoding API →
Search addresses with street, city, postcode and country components.
POST /api/v1/search/structured - Suggest & Retrieve API →
Build place search with suggestions and a secure retrieval step.
POST /api/v1/search/suggestPOST /api/v1/search/retrieve
Maps (4)
- Text-to-style preview →
Describe palette and layer changes, review the map, then apply.
POST /api/v1/studio/preview - Static Maps API →
Export styled maps as PNG images for reports and applications.
POST /api/v1/maps/static - Studio API →
Manage map styles, datasets and publication from your application.
GET /api/v1/studio/{resource}POST /api/v1/studio/{resource} - Map styles and vector tiles →
Load public basemaps or published styles in MapLibre. Public requests need no API key and use zero credits. Use the tile URLs supplied by the style and preserve attribution.
GET /api/basemaps/{style}GET /api/map-styles/{id}GET /api/map-styles/{id}/tiles/{dataset}/{z}/{x}/{y}All endpoints (+2)
GET /api/private-maps/{id}GET /api/private-maps/{id}/tiles/{dataset}/{z}/{x}/{y}
Data (15)
- Timezone API →
Get the IANA time zone, current UTC offset, DST status and local time for any coordinate on Earth.
GET /api/1/timezone - Elevation API →
Height above sea level, in metres, for any coordinate — one point or a whole route profile.
GET /api/1/elevation - Boundary Lookup API →
Find which country, state, city and district a coordinate falls in — with the boundary polygon on request.
GET /api/1/boundary - Geofencing API →
Test in one call which of your zones each point falls inside — polygon or circular fences.
POST /api/1/geofence - 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 - Solar API →
Sunrise, sunset, twilight, solar noon and day length for any coordinate and date.
GET /api/1/solar - Geometry Utilities API →
Distance, bearing, area, centroid, simplification and polyline encode/decode — spatial math as a service.
POST /api/1/geometry - Coordinate Conversion API →
Convert latitude/longitude to and from UTM and MGRS grid references.
GET /api/1/convert - Country Info API →
Currency, calling code, languages, capital and flag for any country by ISO code or name.
GET /api/1/country - Dataset Query API →
Find nearby features in your own uploaded geographic datasets.
POST /api/v1/maps/datasets/{id}/query - Road Data API →
Speed limits, road attributes and traffic-sign observations within available coverage.
POST /api/v1/roads/lookupPOST /api/v1/roads/batch - Account usage →
Road data: 100,000 operations / month
POST /api/v1/roads/usage - Road Signs API →
Find road sign observations within a map area. Retrieve sign classifications, coordinates, directions and observation dates with cursor pagination.
POST /api/v1/roads/signs - Route compliance evidence →
Source-qualified speed evidence for submitted route positions.
POST /api/v1/roads/compliance - Road speed limit lookup →
Read the mapped passenger-car speed limit near a coordinate. A missing or ambiguous limit returns null.
GET /api/1/speed-limit
Platform Integration Guide (6)
- Async jobs →
Operations: geocode_batch, matrix, optimize. POST /api/jobs returns 202 and a job ID. Reusing the same Idempotency-Key and payload returns the existing job; a different payload returns 409.
POST /api/jobsGET /api/jobsGET /api/jobs/{id}All endpoints (+1)
DELETE /api/jobs/{id} - Sandbox API →
Validate response parsing in the fixture sandbox before a paid live call.
POST /api/sandbox - Source metadata →
Check data sources, geographic coverage and freshness by service.
GET /api/source-metadata - Mobile Access →
Connect your mobile application without embedding a private API key.
POST /api/mobile/challengePOST /api/mobile/token - Remote MCP API →
Connect AI tools to location services.
POST /api/mcp - Compatibility endpoints →
For existing integrations, check coordinate order and response units before switching to a canonical API.
GET /api/v1/route/{profile}/{coordinates}GET /api/1/routeGET /api/1/route/infoAll endpoints (+9)
GET /api/1/matrixPOST /api/1/matrixPOST /api/1/matrix/calculatePOST /api/1/matchPOST /api/1/elevationPOST /api/1/optimizePOST /api/1/vrp/optimizePOST /api/1/cluster/calculatePOST /api/1/batch-geocode
Introduction
#OSRMRoute provides APIs for road routing, fleet planning, address search, mapping and geographic data. Use the directory to find the right guide for the operation you want to integrate.
Current plan limits
Credit and requests-per-minute limits are shared across all account keys. An additional key credit cap cannot enlarge the account budget. Included credits are used first, then purchased credits.
Free includes Routing, Route Optimization, Geocoding (including reverse lookup and autocomplete) and Matrix APIs within plan limits. Map Matching, Isochrone, Truck Routing, Fuel Estimate and other separate APIs require a paid plan, including PAYG. API access follows the account’s effective plan; a positive balance alone does not override Free restrictions. Road Data and AI retain their separate Business requirements.
Route, Directions and Truck Routing: a processed request with no nearby accessible road or no connected route costs 0.5 credit once, on every eligible plan including PAYG. Invalid input, access/plan or unsupported graph coverage rejections, and server failures are not charged. The successful-request price is reserved first; unused credits are returned.
Loading current limits…
The public map demo supports Route, Matrix, Match, Nearest and Trip, with separate demo limits. Use your API key and the examples below for every other service.
Authentication
#Send your API key in the Authorization header as a Bearer token. Check the endpoint guide for its required key scope and environment. Query-string keys are accepted by some legacy endpoints.
Authorization: Bearer YOUR_API_KEYError Codes
#OSRMRoute uses standard HTTP status codes and detailed JSON error messages to indicate the state of a request.
Errors can contain error and an optional code; do not rely on a single error message. Read the HTTP status and remaining-budget headers. Reset headers describe rolling windows, not a midnight reset.
X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · X-Compute-* · X-Quota-* · X-Credits-* · Retry-AfterProvide a valid API key; check key status in your dashboard.
{
"error": "Invalid API Key"
}Top up your balance or select a plan that covers this request.
{
"error": "Insufficient balance: this request costs 1 credit and your balance is 0 credits. Top up your account to continue."
}Check plan complexity limits and key restrictions in your dashboard.
{
"error": "This API Key is disabled"
}Respect Retry-After when present and reduce request frequency.
{
"error": "Rate limit exceeded: this account has exceeded its configured requests-per-minute limit. Please slow down."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"error": "Internal Server Error"
}Routing API
#Calculate a road route through the points in the supplied order for driving, cycling or walking. Request instructions with steps=true and select GeoJSON with geometries=geojson.
/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 | simplified | Detail level of the returned route geometry: simplified, full (full geometry), false (no geometry). |
| geometries | string | Optional | polyline | Geometry format: geojson (GeoJSON object), polyline (encoded string). |
| steps | boolean | Optional | false | Whether step-by-step instructions are returned for each turn. |
| alternatives | integer | boolean | Optional | false | Number of alternatives to try to find. Availability depends on the road network. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/v1/osrm/route/v1/driving/49.8516,40.3777;49.86,40.40?steps=true&overview=full&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit per started block of 10 input points, including origin and destination.
Route, Directions and Truck Routing: a processed request with no nearby accessible road or no connected route costs 0.5 credit once, on every eligible plan including PAYG. Invalid input, access/plan or unsupported graph coverage rejections, and server failures are not charged. The successful-request price is reserved first; unused credits are returned.
OSRM path: lon,lat; GeoJSON: [lon,lat].
- points ≥ 2; points ≤ plan.maxRoutePoints
- snap_distance_m ≤ 2000
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"routes": [
{
"distance": 3200,
"duration": 420,
"geometry": {
"type": "LineString",
"coordinates": [
[
49.8516,
40.3777
],
[
49.86,
40.4
]
]
},
"legs": [
{
"distance": 3200,
"duration": 420,
"steps": []
}
]
}
],
"waypoints": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidQuery",
"error": "Coordinates must be finite longitude,latitude pairs."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.
{
"code": "CrossRegionNotSupported",
"error": "These coordinates are not served by one routing graph. Split the request by region."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
The response contains distance in metres and duration in seconds. The default overview is simplified and the default geometry format is polyline. Use overview=full for the full route line.
Matrix API
#Calculate travel times, distances or both between origins and destinations. Use sources and destinations to select indexes in the coordinate list.
/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 | Data to compute: duration (time), distance, or both. |
| sources | string | Optional | all | Zero-based source indexes separated by semicolons, or all. |
| destinations | string | Optional | all | Zero-based destination indexes separated by semicolons, or all. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/v1/osrm/table/v1/driving/49.85,40.37;49.86,40.40;49.83,40.39?annotations=duration,distance" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: max(1, ceil(cells * 2 / 5))
OSRM path: lon,lat; GeoJSON: [lon,lat].
- points ≥ 2; points ≤ plan.maxRoutePoints
- cells = sources × destinations
- credits = max(1, ceil(cells * 2 / 5))
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"durations": [
[
0,
420
],
[
430,
0
]
],
"distances": [
[
0,
3200
],
[
3300,
0
]
],
"sources": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2
},
{
"name": "Second road",
"location": [
49.86,
40.4
],
"distance": 3
}
],
"destinations": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2
},
{
"name": "Second road",
"location": [
49.86,
40.4
],
"distance": 3
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidQuery",
"error": "Coordinates must be finite longitude,latitude pairs."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.
{
"code": "CrossRegionNotSupported",
"error": "These coordinates are not served by one routing graph. Split the request by region."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "UnreachablePoints",
"error": "Some locations are disconnected in this road network."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
The durations matrix is returned by default. Request annotations=distance for distances or annotations=duration,distance for both. Durations are in seconds and distances in metres. A disconnected pair returns HTTP 422 with UnreachablePoints when no eligible graph can complete the matrix.
Map Matching API
#Snaps imprecise GPS traces to the real road network (snap to road). Used to clean up noise in GPS signals.
/api/v1/osrm/match/v1/{profile}/{coordinates}Parameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| geometries | string | Optional | polyline | Geometry format: geojson (GeoJSON object), polyline (encoded string). |
| profile | string | Required | driving | Transport profile. |
| coordinates | string | Required | - | The sequence of GPS coordinates to snap (lon,lat;lon,lat...) |
| overview | string | Optional | simplified | Geometry precision of the matched route. |
| timestamps | string | Optional | - | Non-decreasing Unix timestamps in seconds, one per point, separated by semicolons. |
| radiuses | string | Optional | - | GPS accuracy in metres, one value per point, separated by semicolons. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/v1/osrm/match/v1/driving/49.851536,40.375480;49.844011,40.379982;49.839336,40.389620;49.837774,40.389268?overview=full&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
OSRM path: lon,lat; GeoJSON: [lon,lat].
- points ≥ 2; points ≤ plan.maxRoutePoints
- tracepoints[]: object | null
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"matchings": [
{
"distance": 3200,
"duration": 420,
"geometry": {
"type": "LineString",
"coordinates": [
[
49.8516,
40.3777
],
[
49.86,
40.4
]
]
},
"legs": [
{
"distance": 3200,
"duration": 420,
"steps": []
}
],
"confidence": 0.97
}
],
"tracepoints": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2
},
null
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidQuery",
"error": "Coordinates must be finite longitude,latitude pairs."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.
{
"code": "CrossRegionNotSupported",
"error": "These coordinates are not served by one routing graph. Split the request by region."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
matchings[] → distance (m), duration (s), confidence (0–1), geometry; tracepoints[] → object | null.
Nearest API
#Snaps any coordinate to the nearest real road segment and returns information about the road name.
/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 | 1 | The number of nearest road candidates to find. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/v1/osrm/nearest/v1/driving/49.8516,40.3777?number=3" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
OSRM path: lon,lat; GeoJSON: [lon,lat].
- coordinates: 1
- number: default = 1; example = 3
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"waypoints": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidQuery",
"error": "Coordinates must be finite longitude,latitude pairs."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
waypoints[] → name, distance (m), location [lon,lat].
Trip API
#Order stops for one vehicle using the road network. The service can return a round trip or an open route. For an open route, send roundtrip=false&source=first&destination=last. The order is not guaranteed to be optimal.
/api/v1/osrm/trip/v1/{profile}/{coordinates}Parameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| geometries | string | Optional | polyline | Geometry format: geojson (GeoJSON object), polyline (encoded string). |
| 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). |
| roundtrip | boolean | Optional | true | Return to the start. For false, use source=first and destination=last. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/v1/osrm/trip/v1/driving/49.85,40.37;49.86,40.40;49.83,40.39?source=first&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 5 credits
OSRM path: lon,lat; GeoJSON: [lon,lat].
- points ≥ 2; points ≤ plan.maxRoutePoints
- credits = 5
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"trips": [
{
"distance": 3200,
"duration": 420,
"geometry": {
"type": "LineString",
"coordinates": [
[
49.8516,
40.3777
],
[
49.86,
40.4
]
]
},
"legs": [
{
"distance": 3200,
"duration": 420,
"steps": []
}
]
}
],
"waypoints": [
{
"name": "Example road",
"location": [
49.8516,
40.3777
],
"distance": 4.2,
"trips_index": 0,
"waypoint_index": 0
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidQuery",
"error": "Coordinates must be finite longitude,latitude pairs."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.
{
"code": "CrossRegionNotSupported",
"error": "These coordinates are not served by one routing graph. Split the request by region."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
trips[] → distance (m), duration (s), geometry; waypoints[] → trips_index, waypoint_index, location [lon,lat].
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.
/api/1/directionsParameters (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. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&profile=driving" -H "Authorization: Bearer YOUR_KEY"curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&alternatives=2" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit per started block of 10 input points, including origin and destination.
Route, Directions and Truck Routing: a processed request with no nearby accessible road or no connected route costs 0.5 credit once, on every eligible plan including PAYG. Invalid input, access/plan or unsupported graph coverage rejections, and server failures are not charged. The successful-request price is reserved first; unused credits are returned.
Input point=lat,lng. Instruction/waypoint locations: [lat,lng]; GeoJSON geometry: [lon,lat].
- point: repeat ≥ 2; count ≤ plan.maxRoutePoints
- alternatives: 0–3
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"profile": "driving",
"routes": [
{
"distance": 3200,
"duration": 420,
"geometry": {
"type": "LineString",
"coordinates": [
[
49.8516,
40.3777
],
[
49.86,
40.4
]
]
},
"instructions": [
{
"text": "Continue on Example road",
"type": "continue",
"modifier": "straight",
"distance": 300,
"duration": 40,
"name": "Example road",
"bearing_after": 90,
"location": [
40.3777,
49.8516
]
}
]
}
],
"waypoints": [
{
"name": "Example road",
"location": [
40.3777,
49.8516
]
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "At least two points must be provided (point=lat,lng repeated)."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.
{
"code": "CrossRegionNotSupported",
"error": "These coordinates are not served by one routing graph. Split the request by region."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}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).
/api/1/snapParameters (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. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/snap?point=40.3778,49.8517&point=40.3801,49.8600" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- point: repeat 1–100
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"code": "Ok",
"profile": "driving",
"snapped": [
{
"input": [
40.3777,
49.8516
],
"snapped": [
40.3778,
49.8517
],
"distance": 14,
"name": "Example road"
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "At least one point must be provided (point=lat,lng repeated)."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}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.
/api/1/geocodeParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| q | string | Optional | - | 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. |
| country | string | Optional | - | ISO 3166-1 alpha-2 country code, for example AZ. Returns results only within that country. |
| city | string | Optional | - | Strict city filter, for example Baku. Requires exactly one country code. |
| 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. |
Country and city filters
Without country, search is global. country=AZ restricts results to Azerbaijan; country=AZ&city=Bakı restricts them to Baku in Azerbaijan. No match returns HTTP 200 with an empty list, without expanding to another area. A city without a country or an invalid country code returns HTTP 400 InvalidGeocodeFilter. lat/lon only affect proximity ranking and cannot override these filters. Records without confirmed city metadata are excluded from city-filtered results.
GET /api/1/geocode?q=Nizami&country=AZ
GET /api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1
HTTP 200: { "hits": [], "took": 12 }
HTTP 400: { "code": "InvalidGeocodeFilter", "error": "city requires exactly one country, for example country=AZ&city=Bakı." }Examples
# Bias to a location, only settlements
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place
# Only the selected country and city
GET /api/1/geocode?q=market&country=AZ&city=Bak%C4%B1
# Reverse geocode (coordinates to address)
GET /api/1/geocode?reverse=true&point=40.409,49.867For exact address search, pass the street and house number in q. locality and postcode require a single country. unit selects an exact source unit and implies address_mode=units. The default buildings mode groups co-located unit records.
/api/1/geocode?q=101+Main+Street&country=US&locality=Boston&postcode=02129&unit=2&address_mode=unitsRequest example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1&lang=az" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- limit: 1–20
- reverse: max_distance_m = 1000
- city: exactly 1 country
No match can be a successful empty list. Explicit country/city filters are not expanded to other markets. Detailed addresses depend on indexed data.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"hits": [
{
"name": "Nizami Street",
"city": "Baku",
"country": "Azerbaijan",
"countrycode": "AZ",
"point": {
"lat": 40.3777,
"lng": 49.8516
}
}
],
"took": 12
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "The \"q\" parameter (search text) is required."
}Correct missing or invalid parameters before retrying.
{
"code": "InvalidGeocodeFilter",
"error": "city requires exactly one country, for example country=AZ&city=Bakı."
}No indexed address or place within the reverse lookup radius.
{
"code": "NoNearbyAddress",
"error": "No indexed address or place within 1 km."
}Response Structure Explained
hits[] → name, city, country, countrycode, point (lat,lng); took (ms). reverse=true → source, accuracy, distance_m.
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.
/api/1/placesParameters (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). |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/places?point=40.371,49.845&radius=1&category=amenity:cafe" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- radius: 0.05–20 km
- limit: 1–50
No match can be a successful empty list. Explicit country/city filters are not expanded to other markets. Detailed addresses depend on indexed data.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"places": [
{
"name": "Example cafe",
"category": "amenity",
"type": "cafe",
"distance_m": 85,
"point": {
"lat": 40.3777,
"lng": 49.8516
}
}
],
"took": 12
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "The \"point\" parameter (lat,lng) is required."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"error": "Places service unavailable."
}Response Structure Explained
places[] → name, category, type, distance_m, point (lat,lng); took (ms).
Autocomplete API
#Fast, typo-tolerant place suggestions as the user types, with optional location bias.
/api/1/autocompleteParameters (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). |
| country | string | Optional | - | ISO 3166-1 alpha-2 country code, for example AZ. Returns results only within that country. |
| city | string | Optional | - | Strict city filter, for example Baku. Requires exactly one country code. |
| osm_tag | string | Optional | - | Filter suggestions by OSM type, e.g. place:city. |
Country and city filters
Without country, search is global. country=AZ restricts results to Azerbaijan; country=AZ&city=Bakı restricts them to Baku in Azerbaijan. No match returns HTTP 200 with an empty list, without expanding to another area. A city without a country or an invalid country code returns HTTP 400 InvalidGeocodeFilter. lat/lon only affect proximity ranking and cannot override these filters. Records without confirmed city metadata are excluded from city-filtered results.
GET /api/1/autocomplete?q=Nizami&country=AZ
GET /api/1/autocomplete?q=Nizami&country=AZ&city=Bak%C4%B1
HTTP 200: { "suggestions": [], "took": 12 }
HTTP 400: { "code": "InvalidGeocodeFilter", "error": "city requires exactly one country, for example country=AZ&city=Bakı." }Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/autocomplete?q=niz&lang=az&lat=40.40&lon=49.86" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- limit: 1–15
- city: exactly 1 country
No match can be a successful empty list. Explicit country/city filters are not expanded to other markets. Detailed addresses depend on indexed data.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"suggestions": [
{
"name": "Nizami Street",
"city": "Baku",
"country": "Azerbaijan",
"countrycode": "AZ",
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"label": "Nizami Street, Baku, Azerbaijan"
}
],
"took": 12
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "The \"q\" parameter (search text) is required."
}Correct missing or invalid parameters before retrying.
{
"code": "InvalidGeocodeFilter",
"error": "city requires exactly one country, for example country=AZ&city=Bakı."
}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 up to 100 address strings per request. Results follow input order, and each query costs one credit.
/api/1/geocode/batchParameters (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). |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/geocode/batch" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"queries":["Nizami küçəsi 10","28 May, Bakı"],"lang":"az"}'Limits and coordinates
Credit cost: 1 credit / query
See the named fields in the JSON; this request does not require a coordinate pair.
- queries: 1–100
- limit: 1–5 / query
- credits = queries.length
No match can be a successful empty list. Explicit country/city filters are not expanded to other markets. Detailed addresses depend on indexed data.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"results": [
{
"query": "Baku",
"hits": [
{
"name": "Nizami Street",
"city": "Baku",
"country": "Azerbaijan",
"countrycode": "AZ",
"point": {
"lat": 40.3777,
"lng": 49.8516
}
}
]
}
],
"count": 1,
"took": 12
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Body must include a non-empty \"queries\" array of address strings."
}Correct missing or invalid parameters before retrying.
{
"error": "A maximum of 100 queries can be geocoded per batch request."
}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.
/api/1/timezoneParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| point | string | Optional | - | Supply point=lat,lng or both lat and lon. |
| lat | number | Optional | - | Latitude (alternative to point). |
| lon | number | Optional | - | Longitude (alternative to point). |
| timestamp | string | Optional | now | Unix time (seconds) or ISO date to resolve the offset for; defaults to now. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/timezone?point=40.4093,49.8671" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- timestamp: Unix seconds | ISO 8601; default = now
- utc_offset_seconds: seconds
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"timezone": "Asia/Baku",
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"utc_offset": "+04:00",
"utc_offset_seconds": 14400,
"dst": false,
"abbreviation": "GMT+4",
"local_time": "2026-01-01T16:00:00",
"utc_time": "2026-01-01T12:00:00.000Z"
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}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.
/api/1/elevationParameters (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). |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/elevation?point=40.4093,49.8671&point=41.30,48.50" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit / 10 points
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- GET: point count = 1–100
- POST: points count = 1–1000
- credits = max(1, ceil(points / 10))
- elevation: number | null
- GET with 1 point: elevation alias
Elevation can be null where data is unavailable. Do not replace missing height with zero.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"results": [
{
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"elevation": null
}
],
"unit": "meters"
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide at least one point=lat,lng (repeatable)."
}Correct missing or invalid parameters before retrying.
{
"error": "A maximum of 100 points can be queried per GET request; use POST for larger batches."
}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.
/api/1/boundaryParameters (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. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/boundary?point=40.4093,49.8671" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- polygon: true | false
- HTTP 422: BoundaryCoverageUnavailable
Detailed boundaries exist only in accepted regional datasets. Unsupported coordinates return BoundaryCoverageUnavailable.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"display_name": "Baku, Azerbaijan",
"boundary_scope": "city",
"country": "Azerbaijan",
"countrycode": "AZ",
"city": "Baku",
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
49.84,
40.37
],
[
49.87,
40.37
],
[
49.87,
40.4
],
[
49.84,
40.37
]
]
]
}
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}Detailed administrative data is unavailable here; check service coverage.
{
"code": "BoundaryCoverageUnavailable",
"error": "Detailed administrative boundary data is not available at this coordinate."
}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.
/api/1/geofenceParameters (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). |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/geofence" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"fences":[{"id":"zone1","polygon":[[40.40,49.85],[40.43,49.85],[40.43,49.90],[40.40,49.90]]}],"points":[[40.41,49.87],[40.50,50.10]]}'Limits and coordinates
Credit cost: 1 credit / 100 points
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- fences: 1–100
- points: 1–1000
- credits = max(1, ceil(points / 100))
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"results": [
{
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"inside": [
"depot"
]
}
],
"count": 1,
"took": 1
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Body must include non-empty \"fences\" and \"points\" arrays."
}Correct missing or invalid parameters before retrying.
{
"error": "Limits: up to 100 fences and 1000 points per request."
}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.
/api/1/elevation/profileParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| points | array | Optional | [] | Array of [lat,lng] points forming the path (>=2, up to 2000). |
| polyline | string | Optional | - | Encoded polyline as an alternative to points. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/elevation/profile" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"points":[[40.37,49.85],[40.80,48.90],[41.30,48.05]]}'Limits and coordinates
Credit cost: 1 credit / 10 points
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- points: 2–2000
- credits = max(1, ceil(points / 10))
- elevation: number | null
Elevation can be null where data is unavailable. Do not replace missing height with zero.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"profile": [
{
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"elevation": null,
"distance": 0
},
{
"point": {
"lat": 40.4,
"lng": 49.86
},
"elevation": null,
"distance": 2590
}
],
"total_ascent": 0,
"total_descent": 0,
"min_elevation": null,
"max_elevation": null,
"distance": 2590,
"unit": "meters",
"took": 12
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide a \"points\" array (>=2 [lat,lng]) or an encoded \"polyline\"."
}Correct missing or invalid parameters before retrying.
{
"error": "A maximum of 2000 points is allowed per request."
}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.
/api/1/solarParameters (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. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/solar?point=40.4093,49.8671&date=2026-07-07" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- date: YYYY-MM-DD; default = today
- times: UTC ISO 8601 | null
Solar times can be null in polar day or night. Times are UTC.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"point": {
"lat": 40.3777,
"lng": 49.8516
},
"date": "2026-01-01",
"sunrise": "2026-01-01T04:00:00.000Z",
"sunset": "2026-01-01T13:00:00.000Z",
"solar_noon": "2026-01-01T08:30:00.000Z",
"day_length_seconds": 32400
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}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.
/api/1/geometryParameters (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). |
distance, bearing, midpoint → from, to
destination → from, bearing (°), distance_m
length → path (≥ 2)
area → polygon (≥ 3)
centroid → points (≥ 1)
simplify → path (2–2000), tolerance_m (10)
polyline_encode → path (≥ 1), precision (5)
polyline_decode → polyline, precision (5)Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/geometry" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"op":"distance","from":[40.37,49.85],"to":[40.40,49.86]}'Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- op: distance | bearing | destination | midpoint | length | area | centroid | simplify | polyline_encode | polyline_decode
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"op": "distance",
"distance": 2590.25,
"unit": "meters"
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Invalid geometry input for the requested op."
}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.
/api/1/convertParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| point | string | Optional | lat,lng | Coordinate as lat,lng to convert to UTM/MGRS. |
| mgrs | string | Optional | - | MGRS string to reverse-convert into a coordinate. |
Provide point=lat,lng, both lat and lon, or mgrs. A nonempty mgrs takes precedence. Reverse conversion returns the centre of the MGRS cell and omits utm.
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/convert?point=40.3755,49.8516" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- point=lat,lng OR (lat=... AND lon=...) OR mgrs=...
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"point": {
"lat": 40.3755,
"lng": 49.8516
},
"mgrs": "39TVE0251070068",
"utm": {
"zone": 39,
"band": "T",
"easting": 402511,
"northing": 4470068,
"hemisphere": "N"
}
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide point=lat,lng (or lat= & lon=), or mgrs= to reverse-convert."
}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.
/api/1/countryParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| code | string | Optional | 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. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/country?code=AZ" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 1 credit
See the named fields in the JSON; this request does not require a coordinate pair.
- code=ISO2/ISO3 OR name=...
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"name": "Azerbaijan",
"official_name": "Republic of Azerbaijan",
"cca2": "AZ",
"cca3": "AZE",
"capital": "Baku",
"region": "Asia",
"subregion": "Western Asia",
"currency": {
"code": "AZN",
"name": "Azerbaijani manat",
"symbol": "₼"
},
"calling_code": "+994",
"languages": [
"Azerbaijani"
],
"flag": "🇦🇿",
"latlng": [
40.5,
47.5
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide code=ISO2/ISO3 or name=CountryName."
}Use a valid country code or the exact country name.
{
"error": "Country not found."
}Response Structure Explained
Returns { name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng }.
Isochrone API
#Estimates reachability from sampled road travel times. quality.status is estimated when every sampled direction has a reachable point; otherwise it is insufficient_data and polygons is empty. Empty results do not prove there are no reachable roads. The boundary is approximate; only time limits are supported.
/api/1/isochroneParameters (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). |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl "https://osrmroute.com/api/1/isochrone?point=40.4093,49.8671&time_limit=600" -H "Authorization: Bearer YOUR_KEY"Limits and coordinates
Credit cost: 2 credits / minute; minimum 10
point=lat,lng; JSON points: [lat,lng]. GeoJSON geometry always uses [lon,lat].
- time_limit: min = 60 s
- time_limit ≤ plan.maxIsochroneMinutes × 60
- quality.status = estimated | insufficient_data; polygons = [] when any bearing lacks a reachable sample
- Sampled OSRM estimate, not an exact reachable-area boundary; an empty polygon does not prove no reachable roads
- credits = max(10, ceil(time_limit_seconds / 30))
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"quality": {
"status": "estimated",
"method": "sampled_osrm",
"sampled_points": 80,
"reachable_points": 48,
"covered_bearings": 16,
"total_bearings": 16,
"unknown_points": 0
},
"polygons": [
{
"type": "Feature",
"properties": {
"bucket": 0,
"time_limit": 600
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
49.84,
40.37
],
[
49.87,
40.37
],
[
49.87,
40.4
],
[
49.84,
40.37
]
]
]
}
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "point parameter is required"
}Check plan complexity limits and key restrictions in your dashboard.
{
"error": "The Isochrone API is not available on your plan. Upgrade your plan to use it."
}Use a supported travel profile at these coordinates. No driving fallback is applied.
{
"code": "ProfileNotAvailable",
"error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}The service or an upstream is unavailable. Retry cautiously with backoff.
{
"code": "RoutingTimeout",
"error": "The routing service did not respond within the request deadline. Retry later."
}Response Structure Explained
polygons[] → GeoJSON Feature; geometry → Polygon [lon,lat]; properties.time_limit (s).
Route Optimization API
#Plans fleet routes with capacity, time windows, skills and paired pickup/delivery constraints. A bounded heuristic reduces travel time without guaranteeing a global optimum. Unassigned tasks remain in solution.unassigned; invalid inputs are rejected as a whole.
/api/1/vrpParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| vehicles | array | Optional | one default vehicle | The list of vehicles — each with an id, optional capacity, and a start location as a [lon, lat] array (longitude first). |
| services | array | Optional | [] | The stops to serve — each with an id, a location as a [lon, lat] array (longitude first), and optional service time. |
| shipments | array | Optional | [] | Paired pickup and delivery tasks, with amount and skills. Provide services, shipments or both; at most 250 task endpoints. |
| profile | string | Optional | driving | One shared travel profile: driving, cycling or walking, including their documented aliases. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/vrp" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"vehicles":[{"vehicle_id":"v1","start":[49.85,40.37]}],"services":[{"id":10,"location":[49.86,40.40]}]}'Limits and coordinates
Credit cost: max(10, ceil(vehicles * task_points * 13 / 15)) credits
VRP start/location arrays: [lon,lat]; named objects: lat and lng/lon. Time is seconds.
- vehicles.length ≤ plan.maxVehicles
- vehicles defaults to one vehicle when omitted
- services.length + 2 × shipments.length ≤ 250; vehicles.length ≤ 100
- task_points = services.length + 2 × shipments.length
- credits = max(10, ceil(vehicles * task_points * 13 / 15)); invalid inputs are refunded
- Capacity arrays, time_windows, skills and paired shipments are enforced; unsupported options return 400
- solution.unassigned lists tasks not assigned by the bounded heuristic; this is not proof of infeasibility
- transport_time is travel only; service_time, waiting_time and elapsed time are separate; costs is travel seconds
Driving, walking and cycling are worldwide. Points must connect through roads or paths that allow the selected mode. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"status": "finished",
"job_id": "opt-1234567890",
"processing_time": 0,
"solution": {
"unassigned": [],
"quality": {
"solver": "vroom",
"version": "1.15.0",
"constraints_verified": true,
"optimality_proven": false
},
"costs": 420,
"distance": 3200,
"time": 420,
"no_vehicles": 1,
"no_unassigned": 0,
"routes": [
{
"vehicle_id": "v1",
"distance": 3200,
"transport_time": 420,
"activities": [
{
"type": "start",
"location_id": "depot",
"end_time": 0
},
{
"type": "service",
"id": 10,
"location_id": "stop_1",
"arr_time": 200,
"end_time": 200
},
{
"type": "end",
"location_id": "depot",
"arr_time": 420
}
]
}
]
}
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"code": "InvalidOptimizationInput",
"error": "At least one service with valid coordinates is required."
}Check plan complexity limits and key restrictions in your dashboard.
{
"error": "Your plan allows up to 1 vehicles per request. Upgrade your plan for more."
}Check that the points are near accessible roads and that the roads are connected for the selected profile.
{
"code": "NoNearbyRoad",
"error": "No connected route within 2000 metres of the requested coordinates."
}Response Structure Explained
status → finished; job_id; solution → distance (m), time (s), costs (s), no_vehicles, no_unassigned, routes[]. routes[] → vehicle_id, distance (m), transport_time (s), activities[].
Location Clustering API
#Groups (clusters) given coordinates by their geographic proximity and density.
/api/1/clusterParameters (Query Params)
| Parameter | Type | Status | Default | Description |
|---|---|---|---|---|
| customers | array | Required | [] | Customer coordinates and weights to be clustered. |
Request example
Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.
curl -X POST "https://osrmroute.com/api/1/cluster" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"customers":[[49.85,40.37],[49.86,40.40],[49.83,40.39]],"clusters":2}'Limits and coordinates
Credit cost: 3 credits
Customer input arrays: [lon,lat]; cluster center output: [lat,lon].
- customers: valid coordinates ≥ 1
- 1 ≤ clusters ≤ valid_customers.length
Validate the input format and use the field units shown in the example.
Current plans and pricingCoverage by serviceJSON response example
Illustrative, abbreviated JSON. Values, optional fields and available map data vary. Distances are metres and routing durations are seconds unless a field says otherwise.
{
"status": "finished",
"job_id": "cluster-1234567890",
"processing_time": 0,
"no_clusters": 1,
"clusters": [
{
"ids": [
"s1",
"s2"
],
"center": [
40.385,
49.855
],
"size": 2
}
]
}Service-specific errors
Correct missing or invalid parameters before retrying.
{
"error": "Provide a \"customers\" array with valid coordinates."
}Response Structure Explained
status → finished; job_id; no_clusters; clusters[] → ids[], center [lat,lon], size.
Compatibility endpoints
For existing integrations, check coordinate order and response units before switching to a canonical API.
Shorthand Routing has the same inputs and output as the canonical OSRM route. The older Route endpoint uses repeated latitude,longitude points. Its paths[].time is in milliseconds and paths[].distance is in metres. Route info describes configured coverage and costs one credit.
GET /api/v1/route/driving/49.8516,40.3755;49.8378,40.3892
GET /api/1/route?point=40.3755,49.8516&point=40.3892,49.8378
GET /api/1/route/infoLegacy Matrix accepts repeated point entries or separate from_point and to_point lists in a GET request. In JSON use from_points and to_points as latitude,longitude pairs. The result has times in milliseconds and distances in metres.
GET /api/1/matrix?point=40.3755,49.8516&point=40.3892,49.8378{"from_points":[[40.3755,49.8516]],"to_points":[[40.3892,49.8378]]}Legacy Match accepts an ordered GPS trace as [lon, lat] pairs and optional timestamps in seconds and radiuses in metres, one per point. Its result has matching distances in metres and times in milliseconds. Batch Elevation accepts up to 1,000 [lat, lon] pairs and returns heights in metres or null.
{"points":[[49.8516,40.3755],[49.8378,40.3892]],"timestamps":[1760000000,1760000120],"radiuses":[20,20]}{"points":[[40.3755,49.8516],[40.3892,49.8378]]}The optimize and vrp/optimize paths use the same request as VRP. Cluster and batch geocoding aliases use their canonical request bodies. VRP and clustering return their results in the response.
POST /api/1/optimize·POST /api/1/vrp/optimize→ Route Optimization APIPOST /api/1/cluster/calculate→ Location Clustering APIPOST /api/1/batch-geocode→ Batch Geocoding API
Official SDKs
JavaScript, Python, Kotlin and Swift clients for your API integrations.