Maps, search & Studio APIs

Build with maps and location data

Authentication and errors

Send your key in the Authorization: Bearer header. Coordinates use [longitude, latitude]. Set OSRMROUTE_API_KEY locally; for dataset queries, set DATASET_ID to an owned dataset UUID. Never expose a Studio key in browser code.

401: missing or invalid key · 403: scope denied · 402: insufficient credits · 429: rate limit · 502/503: upstream unavailable. Check the HTTP status before using a response; failed charged operations release their reserved credits.

409: revision conflict. Read the latest resource and reconcile changes before retrying.

Natural Language Search

Find places using a short English query.

Request credits: 2
Required scopes: geocode + places

English category + near/in + place; optional radius 100–5000 m. Six categories, up to ten candidates. No ratings, prices, open-now or live availability. Two credits, including an empty successful result.

POST /api/v1/search/natural

Request body — Fields marked * are required.
`q *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`center`	`array`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/natural" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"cafes near Berlin within 2 km"}'

Response

intent
places[].distance_meters
places[].details
interpretation: constrained_english_grammar
exhaustive: false

Explore the API API reference

Place details

Read source attributes from a retrieved suggestion or route search.

Request credits: 1
Required scopes: places

One credit with places scope. Read one OpenStreetMap object by its search result ID; source cache lasts one hour. Missing phone, website, opening hours and accessibility remain null. Source update time is the object edit time, not business verification. No live opening status. 20 calls/min/key; source cache misses share 30/min.

POST /api/v1/places/details

Request body — Fields marked * are required.
`id *`	`string`	`maxLength: 24`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/details" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"osm:N:123"}'

Response

place.details.phone
place.details.website
place.details.opening_hours
place.details.wheelchair
place.details.observed_at
place.details.source_updated_at
place.details.open_now: null

Explore the API API reference

Text-to-style preview

Describe palette and layer changes, review the map, then apply.

Request credits: 0
Required scopes: studio

English commands separated by semicolons. Presets, hex colors and layer visibility only. Preview never saves or publishes; Apply enters the existing draft and autosave flow.

POST /api/v1/studio/preview

Request body — Fields marked * are required.
`prompt *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`design`	`object`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/studio/preview" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"dark; water #123456; hide buildings"}'

Response

design
changes[]
saved: false
method: explicit_style_commands

Explore the API API reference

Static Maps API

Export styled maps as PNG images for reports and applications.

Request credits: 4
Required scopes: maps

Four palettes: light, dark, navigation and minimal. Images are 128–512 px per side; zoom is 1–14. Simplified rendering includes source attribution; custom Studio layers and effects are not rendered.

POST /api/v1/maps/static

Request body — Fields marked * are required.
`center *`	`array`
`zoom`	`integer`	`min: 1 · max: 14 · default: 12`
`width`	`integer`	`min: 128 · max: 512 · default: 512`
`height`	`integer`	`min: 128 · max: 512 · default: 512`
`style`	`string`	`light \| dark \| navigation \| minimal`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/static" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"center":[13.405,52.52],"zoom":12,"width":512,"height":512,"style":"light"}' \
  --output map.png

Response

Content-Type: image/png

Explore the API API reference

Dataset Query API

Find nearby features in your own uploaded geographic datasets.

Request credits: 1
Required scopes: maps

Only datasets owned by the key owner are accessible. Radius: 0–50,000 m; limit: 1–50. Results contain nearest points and estimated local distances, not road distance or original full geometries. Empty successful results also cost one credit.

POST /api/v1/maps/datasets/{id}/query

Request body — Fields marked * are required.
`point *`	`array`
`radius`	`number`	`min: 0 · max: 50000 · default: 0`
`limit`	`integer`	`min: 1 · max: 50 · default: 10`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/datasets/$DATASET_ID/query" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"point":[2.3522,48.8566],"radius":1000,"limit":10}'

Response

type: FeatureCollection
features[].geometry.type: Point
features[].properties
returned

Explore the API API reference

Search Along Route API

Discover useful stops and compare their additional driving time.

Request credits: 14
Required scopes: places + route

Driving routes up to 200 km. Five sampled locations and at most eight candidate detours; discovery is not exhaustive. Categories: fuel, charging_station, restaurant, cafe, parking, pharmacy. No live traffic or charger availability.

POST /api/v1/places/along-route

Request body — Fields marked * are required.
`start *`	`array`
`end *`	`array`
`category *`	`string`	`fuel \| charging_station \| restaurant \| cafe \| parking \| pharmacy`
`max_detour_seconds`	`number`	`min: 0 · max: 1800 · default: 600`
`limit`	`integer`	`min: 1 · max: 8 · default: 5`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/along-route" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":[13.405,52.52],"end":[13.3777,52.5163],"category":"cafe","max_detour_seconds":600,"limit":5}'

Response

places[]
baseline.duration_seconds
baseline.distance_meters
discovery
duration_model

Explore the API API reference

Structured Geocoding API

Search addresses with street, city, postcode and country components.

Request credits: 1
Required scopes: geocode

Provide street, city or postcode. Country codes contain two letters; other fields allow 100 characters. Components form a text search. Matched/different/missing comparisons and source precision are not guaranteed address validation.

POST /api/v1/search/structured

Request body — Fields marked * are required.
`housenumber`	`string`	`maxLength: 100`
`street`	`string`	`maxLength: 100`
`city`	`string`	`maxLength: 100`
`state`	`string`	`maxLength: 100`
`postcode`	`string`	`maxLength: 100`
`countrycode`	`string`	`maxLength: 2`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/structured" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"street":"Friedrichstraße","city":"Berlin","countrycode":"DE"}'

Response

features[].id
features[].address
features[].precision
features[].match.components
features[].precision_basis
search_method: composed_address_query

Explore the API API reference

Suggest & Retrieve API

Build place search with suggestions and a secure retrieval step.

Request credits: 1 + 1
Required scopes: geocode

Each suggest and retrieve request costs one credit. Query: 1–200 characters. Retrieval tokens expire after 10 minutes and belong to the key owner. Retrieve returns the signed suggestion snapshot, not a fresh lookup.

POST /api/v1/search/suggest

Request body — Fields marked * are required.
`q *`	`string`	`maxLength: 200`

POST /api/v1/search/retrieve

Request body — Fields marked * are required.
`token *`	`string`	`maxLength: 16384`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/suggest" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Paris"}'

Response

suggestions[].id
suggestions[].name
suggestions[].address
suggestions[].token
expires_in_seconds: 600

retrieve → place, retrieval: signed_suggestion_snapshot

cURL · retrieve

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/retrieve" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_SUGGEST"}'

Explore the API API reference

Studio API

Manage map styles, datasets and publication from your application.

Request credits: 0
Required scopes: studio

Explicit studio scope is required, including for unrestricted keys. GET lists owned styles or dataset metadata; POST manages resources. Styles use revisions and publication confirmation. Datasets support create/delete, not in-place editing. Limits: 30 reads or 5 writes/minute/key; workspace quotas apply.

GET / POST /api/v1/studio/{resource}

Request body — Fields marked * are required.
`action *`	`string`
`id`	`string`
`revision`	`integer`
`name`	`string`	`maxLength: 80`
`design`	`object`
`data`	`object`
`confirmPublic`	`boolean`
`confirmDelete`	`boolean`
`version`	`integer`

cURL

curl --fail-with-body "https://osrmroute.com/api/v1/studio/styles" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY"

Response

GET styles → styles[]
GET datasets → datasets[]

Studio actions
`styles · create`	`name, design`
`styles · save / autosave`	`id, revision, name, design`
`styles · duplicate`	`id, revision, name`
`styles · restore`	`id, revision, version`
`styles · publish`	`id, revision, confirmPublic: true`
`styles · unpublish / delete`	`id, revision`
`datasets · create`	`name, data: GeoJSON FeatureCollection`
`datasets · delete`	`id, confirmDelete: true`

POST /api/v1/studio/styles · application/json

{
  "action": "create",
  "name": "Berlin",
  "design": {
    "preset": "light",
    "colors": {
      "land": "#f1f3f5",
      "water": "#a9d8ed",
      "park": "#c9dfc6",
      "road": "#ffffff",
      "highway": "#edc779",
      "building": "#d9dee3",
      "label": "#334155"
    },
    "visible": {
      "roads": true,
      "buildings": true,
      "parks": true,
      "labels": true,
      "pois": true,
      "boundaries": true
    },
    "center": [
      13.405,
      52.52
    ],
    "zoom": 11,
    "overlays": []
  }
}

POST /api/v1/studio/datasets · application/json

{
  "action": "create",
  "name": "Paris places",
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "name": "Paris"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            2.3522,
            48.8566
          ]
        }
      }
    ]
  }
}

Explore the API API reference

Maps, search & Studio APIs

Authentication and errors

Natural Language Search

Place details

Text-to-style preview

Static Maps API

Dataset Query API

Search Along Route API

Structured Geocoding API

Suggest & Retrieve API

Studio API

OSRMRoute Support

How can we help?