osrmroute
API Documentation, SDKs & Integration GuidesIntegration and migration
OSRMRoute / API

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.

OpenAPI · Postman

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/info
    All 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.

HTTP
Authorization: Bearer YOUR_API_KEY

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-RateLimit-Reset · X-Compute-* · X-Quota-* · X-Credits-* · 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: this account has exceeded its configured requests-per-minute limit. Please slow down."
}

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

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

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

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
profilestringRequireddrivingTransport mode profile. Supported values: driving (car), cycling (bike), walking (pedestrian).
coordinatesstringRequired-Coordinates of the points. Format: lon,lat;lon,lat;lon,lat... (at least 2 points).
overviewstringOptionalsimplifiedDetail level of the returned route geometry: simplified, full (full geometry), false (no geometry).
geometriesstringOptionalpolylineGeometry format: geojson (GeoJSON object), polyline (encoded string).
stepsbooleanOptionalfalseWhether step-by-step instructions are returned for each turn.
alternativesinteger | booleanOptionalfalseNumber 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.

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

The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.

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

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

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

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

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

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
profilestringRequireddrivingTransport profile (driving, cycling, walking).
coordinatesstringRequired-Matrix points. Format: lon,lat;lon,lat;lon,lat...
annotationsstringOptionaldurationData to compute: duration (time), distance, or both.
sourcesstringOptionalallZero-based source indexes separated by semicolons, or all.
destinationsstringOptionalallZero-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.

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

The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.

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

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

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

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

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

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
geometriesstringOptionalpolylineGeometry format: geojson (GeoJSON object), polyline (encoded string).
profilestringRequireddrivingTransport profile.
coordinatesstringRequired-The sequence of GPS coordinates to snap (lon,lat;lon,lat...)
overviewstringOptionalsimplifiedGeometry precision of the matched route.
timestampsstringOptional-Non-decreasing Unix timestamps in seconds, one per point, separated by semicolons.
radiusesstringOptional-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.

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

The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.

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

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

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

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

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

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
profilestringRequireddrivingTransport profile.
coordinatesstringRequired-The point to search near. Format: lon,lat (a single pair).
numberintegerOptional1The 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" -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 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."
}

Check that the points are near accessible roads and that the roads are connected for the selected profile.

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

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

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

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

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
geometriesstringOptionalpolylineGeometry format: geojson (GeoJSON object), polyline (encoded string).
profilestringRequireddrivingTransport profile.
coordinatesstringRequired-Points to visit. Format: lon,lat;lon,lat...
sourcestringOptionalanyThe point the route can start from (any or the first point).
destinationstringOptionalanyThe point the route ends at (any or the last point).
roundtripbooleanOptionaltrueReturn 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.

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

The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.

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

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

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

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

GET
/api/1/directions

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngWaypoint as lat,lng. Repeat the parameter for each stop (minimum 2).
profilestringOptionaldrivingTravel mode: driving, cycling or walking.
alternativesintegerOptional0Number of alternative routes to also return (0–3).
langstringOptionalenLanguage 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" -H "Authorization: Bearer YOUR_KEY"
Alternative Routes API
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 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."
}

The API could not serve all points on a single road network for the selected profile. Submit separate requests for connected legs.

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

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

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

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

GET
/api/1/snap

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngGPS point as lat,lng. Repeat the parameter for each point (maximum 100).
profilestringOptionaldrivingRoad 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" -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 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."
}

Check that the points are near accessible roads and that the roads are connected for the selected profile.

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

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

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

GET
/api/1/geocode

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
qstringOptional-The address to search (e.g. "Nizami Street, Baku").
reversebooleanOptionalfalseMust be true to perform reverse geocoding (searching from coordinate to address).
pointstringOptionallat,lngCoordinate (lat,lng) to reverse geocode into an address. Required when reverse=true.
limitintegerOptional5Maximum number of results to return (1–20, default 5).
langstringOptionalenPreferred language for result names (e.g. en, az, ru). Defaults to en.
latnumberOptional-Latitude to bias results toward (nearby matches rank first). Pair with lon.
lonnumberOptional-Longitude to bias results toward. Pair with lat.
bboxstringOptional-Restrict results to a bounding box: minLon,minLat,maxLon,maxLat.
osm_tagstringOptional-Filter by OSM tag, e.g. place (settlements) or amenity:cafe. Prefix with ! to exclude.
countrystringOptional-ISO 3166-1 alpha-2 country code, for example AZ. Returns results only within that country.
citystringOptional-Strict city filter, for example Baku. Requires exactly one country code.
elasticbooleanOptionaltrueElastic (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
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

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

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

GET
/api/1/geocode?q=101+Main+Street&country=US&locality=Boston&postcode=02129&unit=2&address_mode=units

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

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngCenter coordinate lat,lng to search around (required).
radiusnumberOptional1Search radius in kilometers (0.05–20, default 1).
categorystringOptional-OSM tag filter, e.g. amenity:cafe, shop, tourism:hotel. Prefix with ! to exclude. Empty = all POIs.
limitintegerOptional10Max results to return (1–50, default 10).
langstringOptionalenPreferred 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" -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 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)

ParameterTypeStatusDefaultDescription
qstringRequired-Search text — partial input is fine.
limitintegerOptional8Maximum number of suggestions to return (1–15).
langstringOptionalenLanguage code for result labels.
latnumberOptional-Latitude to bias results toward (optional).
lonnumberOptional-Longitude to bias results toward (optional).
countrystringOptional-ISO 3166-1 alpha-2 country code, for example AZ. Returns results only within that country.
citystringOptional-Strict city filter, for example Baku. Requires exactly one country code.
osm_tagstringOptional-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.

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

Autocomplete API
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 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 up to 100 address strings per request. Results follow input order, and each query costs one credit.

POST
/api/1/geocode/batch

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
queriesarrayRequired[]Array of address strings to geocode (max 100).
langstringOptionalenLanguage code for result labels.
limitintegerOptional1Maximum 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" \
  -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 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)

ParameterTypeStatusDefaultDescription
pointstringOptional-Supply point=lat,lng or both lat and lon.
latnumberOptional-Latitude (alternative to point).
lonnumberOptional-Longitude (alternative to point).
timestampstringOptionalnowUnix 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" -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 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)

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngCoordinate 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" -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 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)

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngCoordinate as lat,lng.
polygonbooleanOptionalfalseSet true to also return the boundary as GeoJSON.
langstringOptionalenLanguage 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" -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 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)

ParameterTypeStatusDefaultDescription
fencesarrayRequired[]Array of fences: { id?, polygon:[[lat,lng],...] } or { id?, center:[lat,lng], radius_m }. Up to 100.
pointsarrayRequired[]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" \
  -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 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)

ParameterTypeStatusDefaultDescription
pointsarrayOptional[]Array of [lat,lng] points forming the path (>=2, up to 2000).
polylinestringOptional-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" \
  -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 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)

ParameterTypeStatusDefaultDescription
pointstringRequiredlat,lngCoordinate as lat,lng.
datestringOptionaltodayDate (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" -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 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)

ParameterTypeStatusDefaultDescription
opstringRequireddistanceOperation: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode or polyline_decode.
fromarrayOptional[lat,lng]Start point [lat,lng] (for distance/bearing/destination/midpoint).
toarrayOptional[lat,lng]End point [lat,lng] (for distance/bearing/midpoint).
patharrayOptional[]Array of [lat,lng] (for length/simplify/polyline_encode).
polygonarrayOptional[]Array of [lat,lng] ring (for area).
op → JSON
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.

Geometry Utilities API
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 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)

ParameterTypeStatusDefaultDescription
pointstringOptionallat,lngCoordinate as lat,lng to convert to UTM/MGRS.
mgrsstringOptional-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.

Coordinate Conversion API
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 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)

ParameterTypeStatusDefaultDescription
codestringOptionalAZISO 3166 alpha-2 or alpha-3 country code (e.g. AZ or AZE).
namestringOptional-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" -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 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)

ParameterTypeStatusDefaultDescription
pointstringRequired-Center point. Format: lat,lon.
time_limitintegerOptional600Travel 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" -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 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."
}

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

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

POST
/api/1/vrp

Parameters (Query Params)

ParameterTypeStatusDefaultDescription
vehiclesarrayOptionalone default vehicleThe list of vehicles — each with an id, optional capacity, and a start location as a [lon, lat] array (longitude first).
servicesarrayOptional[]The stops to serve — each with an id, a location as a [lon, lat] array (longitude first), and optional service time.
shipmentsarrayOptional[]Paired pickup and delivery tasks, with amount and skills. Provide services, shipments or both; at most 250 task endpoints.
profilestringOptionaldrivingOne 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.

Route Optimization API
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 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."
}

Check that the points are near accessible roads and that the roads are connected for the selected profile.

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)

ParameterTypeStatusDefaultDescription
customersarrayRequired[]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" \
  -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 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.

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.

HTTP
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/info

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

HTTP
GET /api/1/matrix?point=40.3755,49.8516&point=40.3892,49.8378
POST /api/1/matrix · POST /api/1/matrix/calculate
{"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.

POST /api/1/match
{"points":[[49.8516,40.3755],[49.8378,40.3892]],"timestamps":[1760000000,1760000120],"radiuses":[20,20]}
POST /api/1/elevation
{"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.

Map Playground

Official SDKs

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

JavaScript / TypeScriptPythonKotlin / AndroidSwift / iOSSee the SDKs

OSRMRoute Support

Talk directly to our team

HERE TO HELP

How can we help?

Send a message. Ticket replies are also sent to your verified email.

Your chats

Your chats will appear here.