Skip to content
Documentation menu
docs / api / get-directions-v5-user-profile-coordinates
Mapbox-compatible paths

GET/directions/v5/{user}/{profile}/{coordinates}

Access and price

AuthAn API key, as Authorization: Bearer snk_…, ?api_key=snk_… or ?access_token=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 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.
PremiumFor 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

bash
curl -fsS -X GET "https://api.mapmap.ai/directions/v5/{user}/{profile}/{coordinates}" \
  -H "Authorization: Bearer $MAPMAP_KEY"

Parameters

NameInTypeRequiredDescription
userpathstringyesmapbox or mapmap
profilepathstringyesdriving, driving-traffic (served as driving: traffic-aware times cover the England strategic road network only), walking, cycling or truck (MapMap extension, premium)
coordinatespathstringyeslon,lat pairs separated by ;
access_tokenquerystringnoYour MapMap key (snk_...), accepted here as Mapbox clients send it; api_key and a bearer header work too
alternativesquerybooleannoReturn up to three alternative routes
annotationsquerystringnoComma-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
geometriesquerystringnopolyline (default), polyline6 or geojson
overviewquerystringnosimplified (default), full or false
stepsquerybooleannoTurn-by-turn steps
languagequerystringnoBCP 47 instruction language
voice_instructionsquerybooleannoMapbox-shaped voiceInstructions on each step (metric units)
banner_instructionsquerybooleannoMapbox-shaped bannerInstructions on each step
excludequerystringnotoll, motorway, ferry, tunnel: hard exclusions, so an unavoidable one answers NoRoute where Mapbox would return a violating route
depart_atquerystringnoLocal departure time, YYYY-MM-DDThh:mm
arrive_byquerystringnoLocal arrival time, YYYY-MM-DDThh:mm; send this or depart_at, not both
approachesquerystringnocurb or unrestricted per coordinate, ; separated
continue_straightquerybooleannoOnly false is accepted: it describes what the engine already does. true is refused
roundabout_exitsquerybooleannoOnly false is accepted: it describes what the engine already does. true is refused
voice_unitsquerystringnoOnly metric is accepted; any other value is refused
waypointsquerystringnoAccepted only when it names every coordinate (0;1;…;n-1): every coordinate is a leg boundary on this endpoint

Responses

200Mapbox Directions response: 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)
FieldTypeRequiredDescription
codestringnoOk, or a Mapbox error code.
routesobject[]noRoutes: distance (metres), duration (seconds), geometry in the requested format, and legs with steps when asked for.
uuidstringnoAn identifier for this answer.
waypointsobject[]noThe 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

json
{
  "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": ""
    }
  ]
}
400{code, message}: InvalidQuery or InvalidValue, including any Mapbox option MapMap does not honour (the message names the supported set). Not billed

application/json

401Missing or invalid key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403A browser (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

404ProfileNotFound

application/json

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (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