Documentation menu
POST/v1/navigation/sessions
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| 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. Class: standard, or premium for truck and ADR work. Published as unit_rules.navigation_session in /pricing.json. |
| Premium | When 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
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
| Field | Type | Required | Description |
|---|---|---|---|
| adr | object | no | An ADR dangerous-goods profile, as on POST /route; needs
"costing": "truck". |
| arrive_at | object | no | point (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. |
| costing | string | no | auto (default), truck, bus, motorcycle, motor_scooter,
bicycle or pedestrian, as on POST /route. |
| costing_options | object | no | Valhalla costing options, as on POST /route. |
| destination | Waypoint | yes | Where it ends. |
| options | CreateOptions | no | Landmarks, language and units. |
| origin | Waypoint | yes | Where the journey starts. |
| truck | object | no | The 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
{
"destination": {
"lat": 0,
"lon": 0,
"place_id": "string"
},
"origin": {
"lat": 0,
"lon": 0,
"place_id": "string"
}
}Responses
| Field | Type | Required | Description |
|---|---|---|---|
| adr | object | no | The ADR profile echoed, when one was sent. |
| adr_tunnel_enforcement | object | no | What an ADR route does and does not prove, as on POST /route. |
| arrival | object | no | Which door the route ends at and why, exactly as POST /route
reports it, when arrive_at asked for an entrance. |
| costing | string | yes | Costing every route of the session uses. |
| expires_at | string | yes | When the session expires if no progress or read arrives (RFC 3339 UTC). |
| first_instruction | Instruction | yes | The first instruction to give. |
| idle_ttl_s | integer | yes | Idle seconds before expiry, reset by every progress or read. |
| landmarks | object | no | Landmark lookup summary, when landmarks were asked for. |
| privacy | string | yes | What the session keeps. |
| route | RouteSummary | yes | The route. |
| session_id | string | yes | Opaque 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
{
"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"
}lat/lon and place_id, an adr profile without truck costing, invalid costing options, or a malformed arrive_atapplication/problem+json · Problem
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
scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
place_id that no document carriesapplication/problem+json · Problem
text/plain
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
application/problem+json · Problem
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