Documentation menu
GET/directions/v5/{user}/{profile}/{coordinates}
Access and price
| Auth | An API key, as Authorization: Bearer snk_…, ?api_key=snk_… or ?access_token=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| Price | 1 call per started block of 20 coordinates. Class: standard, or premium for truck and ADR work. Published as unit_rules.route_waypoints in /pricing.json. |
| Premium | For the truck profile, or any truck or ADR query parameter |
What it does
Mapbox-compatible Directions. Metered exactly as GET /route/v1: one unit per started block of 20 waypoints, premium on the truck profile.
An API key, as Authorization: Bearer snk_…, ?api_key=snk_… or ?access_token=snk_…. Metered. Price: 1 call per started block of 20 coordinates.
Call it
curl -fsS -X GET "https://api.mapmap.ai/directions/v5/{user}/{profile}/{coordinates}" \
-H "Authorization: Bearer $MAPMAP_KEY"Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| user | path | string | yes | mapbox or mapmap |
| profile | path | string | yes | driving, driving-traffic (served as driving: traffic-aware times cover the England strategic road network only), walking, cycling or truck (MapMap extension, premium) |
| coordinates | path | string | yes | lon,lat pairs separated by ; |
| access_token | query | string | no | Your MapMap key (snk_...), accepted here as Mapbox clients send it; api_key and a bearer header work too |
| alternatives | query | boolean | no | Return up to three alternative routes |
| annotations | query | string | no | Comma-separated: distance, duration, speed (each manoeuvre's engine length and time spread over its segments by length) and maxspeed. congestion, congestion_numeric, closure and state_of_charge are refused with a 400 naming the supported set |
| geometries | query | string | no | polyline (default), polyline6 or geojson |
| overview | query | string | no | simplified (default), full or false |
| steps | query | boolean | no | Turn-by-turn steps |
| language | query | string | no | BCP 47 instruction language |
| voice_instructions | query | boolean | no | Mapbox-shaped voiceInstructions on each step (metric units) |
| banner_instructions | query | boolean | no | Mapbox-shaped bannerInstructions on each step |
| exclude | query | string | no | toll, motorway, ferry, tunnel: hard exclusions, so an unavoidable one answers NoRoute where Mapbox would return a violating route |
| depart_at | query | string | no | Local departure time, YYYY-MM-DDThh:mm |
| arrive_by | query | string | no | Local arrival time, YYYY-MM-DDThh:mm; send this or depart_at, not both |
| approaches | query | string | no | curb or unrestricted per coordinate, ; separated |
| continue_straight | query | boolean | no | Only false is accepted: it describes what the engine already does. true is refused |
| roundabout_exits | query | boolean | no | Only false is accepted: it describes what the engine already does. true is refused |
| voice_units | query | string | no | Only metric is accepted; any other value is refused |
| waypoints | query | string | no | Accepted only when it names every coordinate (0;1;…;n-1): every coordinate is a leg boundary on this endpoint |
Responses
code, routes (each with weight_name: "duration"), waypoints and uuid (the request id). NoRoute and NoSegment also answer 200 with that code and empty routes, as Mapbox documents. With exclude_locations or exclude_polygons the body also carries the top-level exclusions block of GET /route/v1 (what each excluded location snapped to and each exclusion a leg of the first route passes within 5 m of, or whose polygon it enters)| Field | Type | Required | Description |
|---|---|---|---|
| code | string | no | Ok, or a Mapbox error code. |
| routes | object[] | no | Routes: distance (metres), duration (seconds), geometry in
the requested format, and legs with steps when asked for. |
| uuid | string | no | An identifier for this answer. |
| waypoints | object[] | no | The snapped input points: location and name. |
Example: Recorded from the hosted gateway on 2026-11-05 with a test key: GET /directions/v5/mapbox/driving/-0.1410,50.8290;-0.1370,50.8220?steps=true&geometries=geojson&overview=simplified; lists trimmed to their first items
{
"code": "Ok",
"routes": [
{
"distance": 1190,
"duration": 275.606,
"geometry": {
"coordinates": [
[
-0.140699,
50.828975
],
[
-0.141681,
50.827583
],
[
-0.142213,
50.826317
],
[
-0.140142,
50.825822
],
[
-0.138163,
50.825525
],
[
-0.135733,
50.825001
],
[
-0.136283,
50.823181
],
[
-0.136552,
50.822016
]
],
"type": "LineString"
},
"legs": [
{
"distance": 1190,
"duration": 275.606,
"steps": [
{
"country": "GB",
"distance": 106,
"driving_side": "left",
"duration": 98.545,
"geometry": {
"coordinates": [
[
-0.140699,
50.828975
],
[
-0.14071,
50.828922
],
[
-0.140731,
50.828814
],
[
-0.14076,
50.82869
],
[
-0.141146,
50.828605
],
[
-0.14116,
50.828579
],
[
-0.141256,
50.828353
],
[
-0.141375,
50.828332
]
],
"type": "LineString"
},
"maneuver": {
"bearing_after": 187,
"bearing_before": 0,
"location": [
-0.140699,
50.828975
],
"modifier": "right",
"type": "depart"
},
"mode": "driving",
"name": "",
"road_class": "service_other",
"speedLimitSign": "vienna",
"speedLimitUnit": "mph",
"subdivision": "GB-ENG",
"weight": 98.545
},
{
"country": "GB",
"distance": 253,
"driving_side": "left",
"duration": 40.659,
"geometry": {
"coordinates": [
[
-0.141375,
50.828332
],
[
-0.141557,
50.827859
],
[
-0.14172,
50.827497
],
[
-0.141756,
50.827421
],
[
-0.141797,
50.827274
],
[
-0.141857,
50.827066
],
[
-0.142213,
50.826317
],
[
-0.1423,
50.826138
]
],
"type": "LineString"
},
"maneuver": {
"bearing_after": 160,
"bearing_before": 254,
"location": [
-0.141375,
50.828332
],
"modifier": "slight left",
"type": "turn"
},
"mode": "driving",
"name": "Queen's Road",
"ref": "A2010",
"road_class": "primary",
"speedLimitSign": "vienna",
"speedLimitUnit": "mph",
"subdivision": "GB-ENG",
"weight": 40.659
}
],
"summary": "North Road, A23",
"weight": 275.606
}
],
"weight": 275.606,
"weight_name": "duration"
}
],
"uuid": "7014f24c-70ad-4c54-a768-a28d8127dcfd",
"waypoints": [
{
"location": [
-0.141,
50.829
],
"name": ""
},
{
"location": [
-0.137,
50.822
],
"name": ""
}
]
}{code, message}: InvalidQuery or InvalidValue, including any Mapbox option MapMap does not honour (the message names the supported set). Not billedapplication/json
unauthorized); the body carries signup, docs and a one-call hint for a free keyapplication/problem+json · Problem
X-PAYMENT). Not problem+jsonapplication/json · X402PaymentRequired
maps) key: routing needs a full key. Also: The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
ProfileNotFoundapplication/json
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Also under Mapbox-compatible paths
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId get_directions