API Documentation, SDKs & Integration GuidesIntegration and migration

API Documentation, SDKs & Integration Guides

Postman · Quick start Postman · API Reference Postman · JSON ↓

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.

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.

Loading current limits…

Current plans and pricing OpenAPI JSON ↗

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

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

GET

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

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-Credits-Limit · X-Credits-Remaining · Retry-After

Provide a valid API key; check key status in your dashboard.

HTTP 401

{
  "error": "Invalid API Key"
}

Top up your balance or select a plan that covers this request.

HTTP 402

{
  "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.

HTTP 403

{
  "error": "This API Key is disabled"
}

Respect Retry-After when present and reduce request frequency.

HTTP 429

{
  "error": "Rate limit exceeded: more than 60 requests per minute. Please slow down."
}

The service or an upstream is unavailable. Retry cautiously with backoff.

HTTP 500

{
  "error": "Internal Server Error"
}

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. - **402 Payment Required**: The available free allowance and purchased balance together cannot cover this request. Top up or wait for free credits to become available. - **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	polyline	Geometry format: geojson (GeoJSON object), polyline (encoded string).
steps	boolean	Optional	false	Whether step-by-step instructions are returned for each turn.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Routing API

curl "https://osrmroute.com/api/v1/osrm/route/v1/driving/49.8516,40.3777;49.86,40.40?steps=true&overview=full&geometries=geojson&key=YOUR_KEY"

Limits and coordinates

Credit cost: 1 credit

OSRM path: lon,lat; GeoJSON: [lon,lat].

points ≥ 2; points ≤ plan.maxRoutePoints
snap_distance_m ≤ 2000

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Use a supported travel profile at these coordinates. No driving fallback is applied.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

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	Data to compute: duration (time), distance, or both.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Matrix API

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&key=YOUR_KEY"

Limits and coordinates

Credit cost: 1 credit / 10 cells

OSRM path: lon,lat; GeoJSON: [lon,lat].

points ≥ 2; points ≤ plan.maxRoutePoints
cells = sources × destinations
credits = max(1, ceil(cells / 10))

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Use a supported travel profile at these coordinates. No driving fallback is applied.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "UnreachablePoints",
  "error": "Some locations are disconnected in this road network."
}

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
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	full	Geometry precision of the matched route.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Map Matching API

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&key=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 is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Use a supported travel profile at these coordinates. No driving fallback is applied.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

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.

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

Nearest API

curl "https://osrmroute.com/api/v1/osrm/nearest/v1/driving/49.8516,40.3777?number=3&key=YOUR_KEY"

Limits and coordinates

Credit cost: 1 credit

OSRM path: lon,lat; GeoJSON: [lon,lat].

coordinates: 1
number: default = 1; example = 3

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "code": "Ok",
  "waypoints": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    }
  ]
}

Service-specific errors

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Use a supported travel profile at these coordinates. No driving fallback is applied.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

Response Structure Explained

waypoints[] → name, distance (m), location [lon,lat].

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Trip API (TSP)

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&key=YOUR_KEY"

Limits and coordinates

Credit cost: 5 credits

OSRM path: lon,lat; GeoJSON: [lon,lat].

points ≥ 2; points ≤ plan.maxRoutePoints
credits = 5

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Use a supported travel profile at these coordinates. No driving fallback is applied.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

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.

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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Directions API

curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&profile=driving&key=YOUR_KEY"

Alternative Routes API

curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&alternatives=2&key=YOUR_KEY"

Limits and coordinates

Credit cost: 1 credit

Input point=lat,lng. Instruction/waypoint locations: [lat,lng]; GeoJSON geometry: [lon,lat].

point: repeat ≥ 2; count ≤ plan.maxRoutePoints
alternatives: 0–3

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "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.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Snap to Road API

curl "https://osrmroute.com/api/1/snap?point=40.3778,49.8517&point=40.3801,49.8600&key=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 is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "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.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

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

Examples

GET /api/1/geocode?q=Nizami&country=AZ&key=YOUR_KEY
GET /api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1&key=YOUR_KEY

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&key=YOUR_KEY

# Only the selected country and city
GET /api/1/geocode?q=market&country=AZ&city=Bak%C4%B1&key=YOUR_KEY

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Geocoding API

curl "https://osrmroute.com/api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1&lang=az&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "The \"q\" parameter (search text) is required."
}

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "code": "InvalidGeocodeFilter",
  "error": "city requires exactly one country, for example country=AZ&city=Bakı."
}

No indexed address or place within the reverse lookup radius.

HTTP 422

{
  "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.

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Places API

curl "https://osrmroute.com/api/1/places?point=40.371,49.845&radius=1&category=amenity:cafe&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "The \"point\" parameter (lat,lng) is required."
}

The service or an upstream is unavailable. Retry cautiously with backoff.

HTTP 502

{
  "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.

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

Examples

GET /api/1/autocomplete?q=Nizami&country=AZ&key=YOUR_KEY
GET /api/1/autocomplete?q=Nizami&country=AZ&city=Bak%C4%B1&key=YOUR_KEY

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.

Autocomplete API

curl "https://osrmroute.com/api/1/autocomplete?q=niz&lang=az&lat=40.40&lon=49.86&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "The \"q\" parameter (search text) is required."
}

Correct missing or invalid parameters before retrying.

HTTP 400

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Batch Geocoding API

curl -X POST "https://osrmroute.com/api/1/geocode/batch?key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "Body must include a non-empty \"queries\" array of address strings."
}

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "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.

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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Timezone API

curl "https://osrmroute.com/api/1/timezone?point=40.4093,49.8671&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "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.

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Elevation API

curl "https://osrmroute.com/api/1/elevation?point=40.4093,49.8671&point=41.30,48.50&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "results": [
    {
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "elevation": null
    }
  ],
  "unit": "meters"
}

Service-specific errors

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "error": "Provide at least one point=lat,lng (repeatable)."
}

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "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.

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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Boundary Lookup API

curl "https://osrmroute.com/api/1/boundary?point=40.4093,49.8671&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}

Detailed administrative data is unavailable here; check service coverage.

HTTP 422

{
  "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.

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Geofencing API

curl -X POST "https://osrmroute.com/api/1/geofence?key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "results": [
    {
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "inside": [
        "depot"
      ]
    }
  ],
  "count": 1,
  "took": 1
}

Service-specific errors

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "error": "Body must include non-empty \"fences\" and \"points\" arrays."
}

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "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.

POST

/api/1/elevation/profile

Parameters (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.

Elevation Profile API

curl -X POST "https://osrmroute.com/api/1/elevation/profile?key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "Provide a \"points\" array (>=2 [lat,lng]) or an encoded \"polyline\"."
}

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "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.

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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Solar API

curl "https://osrmroute.com/api/1/solar?point=40.4093,49.8671&date=2026-07-07&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "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.

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Geometry Utilities API

curl -X POST "https://osrmroute.com/api/1/geometry?key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "op": "distance",
  "distance": 2590.25,
  "unit": "meters"
}

Service-specific errors

Correct missing or invalid parameters before retrying.

HTTP 400

{
  "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.

GET

/api/1/convert

Parameters (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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Coordinate Conversion API

curl "https://osrmroute.com/api/1/convert?point=40.3755,49.8516&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "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.

GET

/api/1/country

Parameters (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.

Country Info API

curl "https://osrmroute.com/api/1/country?code=AZ&key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "Provide code=ISO2/ISO3 or name=CountryName."
}

Use a valid country code or the exact country name.

HTTP 404

{
  "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.

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

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Isochrones API

curl "https://osrmroute.com/api/1/isochrone?point=40.4093,49.8671&time_limit=600&key=YOUR_KEY"

Limits and coordinates

Credit cost: 5 credits

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 = 5

Driving is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "point parameter is required"
}

Check plan complexity limits and key restrictions in your dashboard.

HTTP 403

{
  "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.

HTTP 422

{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

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.

POST

/api/1/vrp

Parameters (Query Params)

Parameter	Type	Status	Default	Description
vehicles	array	Optional	[]	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.

Request example

Replace YOUR_KEY with your own API key. Paid API requests consume credits; copying this example does not send a request.

Route Optimization API

curl -X POST "https://osrmroute.com/api/1/vrp?key=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: 10 credits + 1 per stop

VRP start/location arrays: [lon,lat]; named objects: lat and lng/lon. Time is seconds.

vehicles.length ≤ plan.maxVehicles
services.length + 2 × shipments.length ≤ 250; vehicles.length ≤ 100
credits = 10 + services.length + 2 × shipments.length; 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 is global; walking and cycling are regional. Points must share a supported routing graph. VRP is heuristic and isochrones are approximate; neither promises a global optimum or live traffic.

Current plans and pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "code": "InvalidOptimizationInput",
  "error": "At least one service with valid coordinates is required."
}

Check plan complexity limits and key restrictions in your dashboard.

HTTP 403

{
  "error": "Your plan allows up to 1 vehicles per request. Upgrade your plan for more."
}

Choose points near connected roads, or split a request that crosses routing regions.

HTTP 422

{
  "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.

POST

/api/1/cluster

Parameters (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.

Location Clustering

curl -X POST "https://osrmroute.com/api/1/cluster?key=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 pricing Coverage by service

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

HTTP 200 · application/json

{
  "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.

HTTP 400

{
  "error": "Provide a \"customers\" array with valid coordinates."
}

Response Structure Explained

status → finished; job_id; no_clusters; clusters[] → ids[], center [lat,lon], size.

Official SDKs

JavaScript, Python, Kotlin and Swift clients for your API integrations.

JavaScript / TypeScriptPythonKotlin / AndroidSwift / iOSSee the SDKs