Skip to content
Documentation menu
docs / api / post-v1-navigation-sessions
Routing

POST/v1/navigation/sessions

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 call per session opened, as a two-point /route; a place_id is resolved at no extra charge. A nav-session-limit refusal is not billed. Class: standard, or premium for truck and ADR work. Published as unit_rules.navigation_session in /pricing.json.
PremiumWhen the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true

What it does

Open a navigation session: compute the route and start guiding it.

An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per session opened, as a two-point /route; a place_id is resolved at no extra charge. A nav-session-limit refusal is not billed.

Call it

bash
curl -fsS -X POST "https://api.mapmap.ai/v1/navigation/sessions" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":{"lat":0,"lon":0,"place_id":"string"},"origin":{"lat":0,"lon":0,"place_id":"string"}}'

Request body

application/json · CreateSessionRequest

Where from and to (lat and lon, or a geocoder place_id), the costing and its options exactly as on POST /route (truck dimensions, a top-level truck object, an adr profile), and options (landmarks, language, units). Metered as one call, like a two-point route; Premium for truck costing or an ADR profile

FieldTypeRequiredDescription
adrobjectnoAn ADR dangerous-goods profile, as on POST /route; needs "costing": "truck".
arrive_atobjectnopoint (default): the destination's own coordinates. entrance, or an object {place_id?, entrance_kind?, wheelchair?}, ends the route at the place's mapped door exactly as POST /route arrive_at does (a destination given by place_id names the place); when no door can be chosen the destination stays where it is and arrival.applied is false with the reason.
costingstringnoauto (default), truck, bus, motorcycle, motor_scooter, bicycle or pedestrian, as on POST /route.
costing_optionsobjectnoValhalla costing options, as on POST /route.
destinationWaypointyesWhere it ends.
optionsCreateOptionsnoLandmarks, language and units.
originWaypointyesWhere the journey starts.
truckobjectnoThe vehicle, as the top-level truck object POST /route accepts.

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "destination": {
    "lat": 0,
    "lon": 0,
    "place_id": "string"
  },
  "origin": {
    "lat": 0,
    "lon": 0,
    "place_id": "string"
  }
}

Responses

201The session: its id, the route, the first instruction and when it expires if left idle (2 hours by default, reset by every progress or read). Sessions are held in memory and do not survive a gateway restart
FieldTypeRequiredDescription
adrobjectnoThe ADR profile echoed, when one was sent.
adr_tunnel_enforcementobjectnoWhat an ADR route does and does not prove, as on POST /route.
arrivalobjectnoWhich door the route ends at and why, exactly as POST /route reports it, when arrive_at asked for an entrance.
costingstringyesCosting every route of the session uses.
expires_atstringyesWhen the session expires if no progress or read arrives (RFC 3339 UTC).
first_instructionInstructionyesThe first instruction to give.
idle_ttl_sintegeryesIdle seconds before expiry, reset by every progress or read.
landmarksobjectnoLandmark lookup summary, when landmarks were asked for.
privacystringyesWhat the session keeps.
routeRouteSummaryyesThe route.
session_idstringyesOpaque id for the progress, read and delete calls.

Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json
{
  "costing": "string",
  "expires_at": "string",
  "first_instruction": {
    "maneuver_type": 0,
    "step_index": 0,
    "street_names": [
      "string"
    ],
    "text": "string"
  },
  "idle_ttl_s": 0,
  "privacy": "string",
  "route": {
    "distance_m": 0,
    "duration_s": 0,
    "geometry_polyline6": "string",
    "steps": 0,
    "version": 0
  },
  "session_id": "string"
}
400Invalid request: a bad coordinate, both or neither of lat/lon and place_id, an adr profile without truck costing, invalid costing options, or a malformed arrive_at

application/problem+json · Problem

401Missing or invalid API 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

403The 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

404A place_id that no document carries

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

429Quota or rate limit exceeded, or nav-session-limit: the key already holds its cap of live sessions (100 by default) or the gateway its own; not billed. DELETE a finished session or wait for one to expire. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

502The routing engine failed or found no route

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 Routing

Generated from https://api.mapmap.ai/openapi.json on 2026-11-22 · operationId create_session