Documentation menu
Navigation sessions
A navigation session is turn-by-turn guidance that runs on the gateway instead of on the device. You open a session with an origin and a destination, then post each position as it arrives. Every answer says whether the traveller is on the route, has left it, has been rerouted or has arrived, and what the next instruction is, how far away it is, and how much of the journey is left.
It is for clients that cannot run guidance themselves: voice assistants, smart glasses, watches and other wearables, robots, and AI agents that hold a conversation rather than a map. The guidance decisions come from the same engine the mobile SDKs run on the device.
If you are building a phone or in-car app, use the mobile SDKs instead: the React Native, Android and iOS SDKs already run turn-by-turn guidance on the device, offline, with no request per position. A session is the answer for the clients that have no such runtime.
How a session works
POST /v1/navigation/sessionscomputes the route and opens a session over it. The answer carries thesession_id, the route summary and the first instruction.POST /v1/navigation/sessions/{id}/progresstakes one position fix and answers with astateand the next instruction. Post one fix per update from the device's location source; there is no need to resend the route.- When the traveller leaves the route, the session confirms it over several
fixes and then computes a new route from where they are, facing the way
they are heading. The answer that carries the new route has
state: "rerouted". DELETE /v1/navigation/sessions/{id}ends the session.GETon the same path reads it back without posting a fix.
export BASE=https://api.mapmap.ai
export API_KEY=snk_...
# 1. Open a session
curl -fsS -X POST "$BASE/v1/navigation/sessions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"origin": {"lat": 52.2000, "lon": 0.1300},
"destination": {"lat": 52.2040, "lon": 0.1420},
"costing": "pedestrian",
"options": {"landmarks": true, "language": "en-GB"}
}'
# 2. Post a fix (session_id from the answer above)
curl -fsS -X POST "$BASE/v1/navigation/sessions/nav_3f2c.../progress" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"lat": 52.2001, "lon": 0.1342, "heading_deg": 91.0,
"speed_mps": 1.4, "accuracy_m": 8.0,
"timestamp": "2026-11-20T16:04:05Z"}'
# 3. End it
curl -fsS -X DELETE "$BASE/v1/navigation/sessions/nav_3f2c..." \
-H "Authorization: Bearer $API_KEY"
What a session keeps, and for how long
- The route and the last accepted fix, nothing else. The session needs the last position and its time to judge the next fix and to reroute from it. It keeps no trail of earlier positions, and no position is written to a database, to disk or to a log.
- Two hours idle. A session that receives no progress and no read for
two hours expires. Every progress request and every
GETresets the clock.expires_atin each answer says when it will expire if nothing else arrives. - Gateway memory only. Sessions live in the memory of the gateway that
opened them. They do not survive a gateway restart or a deploy: a client
whose session has gone gets a
404and should open a new session from where it is now. - 100 live sessions per account. The cap counts every key on the
account together. Opening one more answers
429with the problem typenav-session-limit; end sessions you no longer need withDELETErather than waiting for them to expire.
Opening a session: POST /v1/navigation/sessions
Answers 201 Created.
Request fields
| Field | Type | Meaning |
|---|---|---|
origin | object, required | Where the journey starts: {lat, lon}, or {place_id} with a place id from GET /geocode/suggest or GET /geocode. Never both. |
destination | object, required | Where it ends, in the same shape as origin. |
costing | string | auto (default), truck, bus, motorcycle, motor_scooter, bicycle or pedestrian, as on POST /route. |
costing_options | object | Per-costing options, exactly as on POST /route. |
truck | object | The vehicle's dimensions, as the top-level truck object POST /route accepts. |
adr | object | A dangerous-goods profile (dimensions, tunnel_code, hazmat), as on POST /route. Needs costing: "truck". |
arrive_at | string or object | Where the session ends. point (the default): the destination's own coordinates. entrance: the best door of the place at the destination. An object {place_id?, entrance_kind?, wheelchair?}: a door of that place, of that kind, step-free when wheelchair is true. See Ending at a door. |
options.landmarks | boolean | Landmark phrasing on turns ("Turn left just after the Co-op"), on the first route and on every reroute. Default false. |
options.language | string | Instruction language, for example en-GB or de-DE. |
options.units | string | kilometers (default) or miles: the units used inside the instruction text. Every distance field in this API is in metres whatever this says. |
Reroutes inherit the session's costing, vehicle, language, units and landmark setting, so a lorry session stays a lorry session after it leaves the route.
Ending at a door
A session can end at a building's door rather than at the middle of it,
with the same choice of door POST /route
makes:
"arrive_at": "entrance"ends at the best door of the place at the destination. Adestinationgiven as{place_id}names the place; given as coordinates, the place is the one with mapped doors within 25 m of them."arrive_at": {"place_id": "...", "entrance_kind": "main", "wheelchair": true}names the place and the door wanted. Every key is optional; withoutplace_idthe destination's ownplace_idis used.entrance_kindis one ofmain,yes,entry,service,staircase,homeorgarage. Withwheelchair: true, or pedestrian costing withcosting_options.pedestrian.type: "wheelchair", a door mappedwheelchair=yesis taken where one exists and a door mappedwheelchair=nonever is. When driving, the door nearest a road the vehicle can use wins.- A
destinationgiven as{place_id}withoutarrive_atends at the place's own position, not at a door: on sessions the door is only used whenarrive_atasks for it.
Only doors mapped in OpenStreetMap are chosen; none is estimated. The
answer carries an arrival block saying which door and why, exactly as
on POST /route. When no door suits (none is tied to the place, the
deployment has no entrance data, or none fits what was asked for), the
session still opens, ends at the destination as given, and arrival is
applied: false with the reason. Every reroute heads for the same door.
curl -fsS -X POST "$BASE/v1/navigation/sessions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"origin": {"lat": 51.5246, "lon": -0.1340},
"destination": {"place_id": "osm:w56441629:poi"},
"costing": "pedestrian",
"arrive_at": {"wheelchair": true}
}'
Response
{
"session_id": "nav_3f2c...",
"costing": "truck",
"route": {"version": 0, "distance_m": 1100.0, "duration_s": 91.7,
"geometry_polyline6": "...", "steps": 3},
"first_instruction": {"step_index": 1, "text": "Turn left onto East Road.",
"verbal": "Turn left onto East Road.",
"landmark": "Turn left just after the Co-op.",
"maneuver_type": 15, "street_names": ["East Road"],
"location": {"lat": 52.2, "lon": 0.1388}},
"expires_at": "2026-11-20T18:04:05Z",
"idle_ttl_s": 7200,
"privacy": "the session keeps the route and the last accepted fix only, ...",
"landmarks": {"annotated": 1},
"arrival": {"applied": true, "place_id": "osm:w56441629:poi",
"entrance": {"lon": -0.0789, "lat": 51.5122, "kind": "main", "...": "..."},
"reason": "...", "eligible_entrances": 2, "mapped_entrances": 2,
"moved_m": 14.6, "original_destination": {"lat": 51.51214, "lon": -0.07877},
"entrances_index": "loaded"},
"adr": {"dimensions": {"...": "..."}, "tunnel_code": "C/E", "hazmat": true},
"adr_tunnel_enforcement": {"basis": "...", "route_certified": false, "caveat": "..."}
}
| Field | Meaning |
|---|---|
session_id | The id to post progress to. Ids start nav_; anything else is a 404. |
costing | The costing the session routes with. |
route | version (0 for the first route, one higher after each reroute), distance_m, duration_s, geometry_polyline6 (an encoded polyline at six-digit precision), steps and, when time was added, eta_calibration: the same GB typical-delay block as on POST /route (applied, method, period, engine_time_s, added_s, alternates_added_s, bands, traffic_network_m, note, sources, and truck_note on trucks). duration_s includes that calibration. |
first_instruction | The first manoeuvre: step_index, text, verbal (the spoken form), landmark (when one was found), maneuver_type, street_names and location. |
expires_at | When the session expires if nothing else arrives (RFC 3339, UTC). |
idle_ttl_s | The idle time in seconds: 7200. |
privacy | What the session keeps, in one sentence, so a client can show it. |
landmarks | Only when landmarks were asked for: how many turns were annotated. |
arrival | Only when arrive_at asked for a door: applied, place_id, the entrance chosen (an entrance object), reason, eligible_entrances, mapped_entrances, moved_m, original_destination and entrances_index; or applied: false with the reason. |
adr, adr_tunnel_enforcement | Only with an ADR profile: the profile as applied, and what the route does and does not prove about tunnels, as on POST /route. route_certified is always false. |
Posting a fix: POST /v1/navigation/sessions/{id}/progress
Answers 200.
Request fields
| Field | Type | Meaning |
|---|---|---|
lat, lon | number, required | The position, WGS84. |
timestamp | string or number, required | When the fix was taken: RFC 3339, or milliseconds since the Unix epoch. |
heading_deg | number | Direction of travel, degrees clockwise from true north (0 to under 360). With it, the next instruction carries a direction phrased from where the traveller is facing, and a reroute starts facing the same way. |
speed_mps | number | Speed in metres per second. |
accuracy_m | number | The fix's horizontal accuracy in metres, as the device reports it. A fix that is too inaccurate is refused as lost_position rather than allowed to move guidance on. |
Response
{
"session_id": "nav_3f2c...",
"state": "on_route",
"fix": {"accepted": true},
"snapped": {"lat": 52.2, "lon": 0.1342, "course_deg": 90.0},
"next_instruction": {"step_index": 1, "text": "Turn left onto East Road.",
"landmark": "Turn left just after the Co-op.",
"maneuver_type": 15, "street_names": ["East Road"],
"location": {"lat": 52.2, "lon": 0.1388},
"direction": "directly ahead, about 310 metres"},
"instruction_changed": false,
"distance_to_next_m": 309.6,
"remaining_m": 809.2,
"remaining_s": 67.4,
"eta": "2026-11-20T16:05:13Z",
"numbers_current": true,
"reroutes": 0,
"expires_at": "2026-11-20T18:04:05Z"
}
| Field | Meaning |
|---|---|
state | One of the five states below. |
fix | {accepted: true}, or {accepted: false, reason} when the fix was not used (see "Fixes that are not used"). |
snapped | Only when this fix was placed on the route: the snapped position and the route's course there. |
next_instruction | The next manoeuvre, in the same shape as first_instruction. direction is present only when the fix carried heading_deg and was used, in the same wording the MCP place tools use ("directly ahead", "ahead and slightly to your left", "behind you and to your right"; "a few steps away" when it is very close). |
current_instruction | The manoeuvre that began the step being travelled. Guidance moves on to a step shortly before its manoeuvre, so while a turn is being made this is that turn and next_instruction is the one after it. Absent once arrived. |
instruction_changed | true when next_instruction is new since the last fix: read it out. |
distance_to_next_m | Metres to the next manoeuvre. |
remaining_m, remaining_s, eta | Distance, time and arrival still to go. On GB routes the time and arrival include the typical-delay calibration the route's eta_calibration describes. |
numbers_current | false when the distances above are the last accepted fix's, because this fix was not used. |
off_route | Only in off_route: deviation_m (how far the fix is from the route), consecutive_fixes (off-route fixes in a row so far) and, when a confirmed departure did not reroute, reroute_skipped. |
route | Only in rerouted: the new route, in the same shape as on opening, with a higher version. |
reroutes | Reroutes so far in this session. |
expires_at | The new expiry: this request reset the idle clock. |
The five states
state | Meaning | What a client does |
|---|---|---|
on_route | The fix is on the route. | Read out next_instruction when instruction_changed is true. |
off_route | The fix has left the route, and either the departure is not confirmed yet or it was confirmed but not rerouted (see off_route.reroute_skipped). | Keep posting fixes. Say nothing yet, or "recalculating" if you prefer. |
rerouted | A new route was computed from this fix. route carries it. | Replace any drawn route and read out the new next_instruction. |
arrived | The traveller has reached the destination. | Say so, then DELETE the session. |
lost_position | The fix was not used (fix.accepted: false, with fix.reason). Guidance did not move. | Keep posting fixes. |
GET on a session that has had no fix yet answers state: "created".
Rerouting
A departure from the route is confirmed by 3 consecutive off-route fixes spanning at least 5 seconds, so one stray fix never reroutes. At most one reroute every 10 seconds is computed, and a session computes at most 50 reroutes in all. The new route starts at the confirming fix, facing the way the traveller is heading, so it carries on forward rather than sending them back the way they came.
When a confirmed departure does not reroute, off_route.reroute_skipped
says why:
reroute_skipped | Meaning |
|---|---|
cooling_down | A reroute was computed less than 10 seconds ago. |
reroute_cap | This session has used its 50 reroutes. Open a new session. |
no_waypoint_left | There is nothing left to route to. |
span_exceeded | The new route would be longer than this deployment's route span cap. |
not_reserved | The request was not priced for a reroute (see Pricing). The next fix tries again. |
engine_found_no_route | The routing engine found no route from here. |
Fixes that are not used
A fix that fails a check is answered lost_position and never reaches
guidance, so it cannot move the session on to the next step or count
towards a reroute.
fix.reason | Meaning |
|---|---|
low_accuracy | The fix's accuracy_m is too large to trust. |
implausible_jump | The fix is further from the last accepted one than any vehicle of this costing could travel in the time between them. After two such refusals in a row the next one is believed, so a session recovers from a genuine jump. |
far_from_route | The fix is too far from the route to belong to this journey. |
out_of_order | Its timestamp is not after the last accepted fix's. |
after_arrival | The journey has already arrived; the state stays arrived. |
Reading a session: GET /v1/navigation/sessions/{id}
Answers 200 with the session as it stands, without posting a fix, and
resets the idle clock:
{"session_id": "nav_...", "costing": "auto", "state": "created",
"route": {"...": "..."}, "next_instruction": {"...": "..."},
"remaining_m": 809.2, "remaining_s": 67.4, "reroutes": 0,
"expires_at": "...", "privacy": "..."}
state is created before the first fix, then the last state reported.
Ending a session: DELETE /v1/navigation/sessions/{id}
Answers 204 No Content. The route and the last fix are dropped at once.
Errors
Every error is an RFC 9457 application/problem+json document (see
Conventions).
| Status | When |
|---|---|
400 | A malformed body; a waypoint with both coordinates and a place_id, or neither; adr without costing: "truck"; a malformed arrive_at (not point, entrance or an object, an unknown key, or an entrance_kind that is not a way in); a route larger than a session allows. No door to end at is never an error: see arrival. |
401 | Missing or invalid API key. |
404 | On opening: an unknown place_id, or a place with no position. On any session path: an unknown, expired or malformed session id, or a session another account opened. Not billed. |
429 | nav-session-limit: the account already has 100 live sessions, or the gateway holds its own limit across every account. The body carries cap, the limit that was hit. Not billed. Also the usual quota and rate-limit answers. |
502 | The routing engine failed or found no route. |
Pricing
Reading and ending a session are free. Opening a session and posting
progress are metered; the units are on the pricing page and in
/pricing.json. An ADR profile or truck costing makes the
session Premium, as it does on POST /route. A 404 for a gone session
and a 429 at the session cap are never billed.
If you only need to know where a vehicle is against a route you already
hold, without the gateway keeping anything, the stateless
POST /route/progress
answers that per request.
Over MCP
Three tools on the MCP server wrap the session routes, so an assistant can guide someone through a conversation:
| Tool | Wraps | What it returns |
|---|---|---|
start_navigation | POST /v1/navigation/sessions | The session_id, the route summary and the first instruction. |
check_navigation_progress | POST /v1/navigation/sessions/{id}/progress | The state, the next instruction and what is left to go. |
end_navigation | DELETE /v1/navigation/sessions/{id} | Confirmation that the session has ended. |
{"name": "start_navigation",
"arguments": {"origin": {"lat": 51.5136, "lon": -0.0800},
"destination": {"place_id": "osm:w56441629:poi"},
"costing": "pedestrian",
"landmarks": true,
"arrive_at": "entrance"}}
On MCP landmarks, language and units are top-level arguments, not an
options object. arrive_at takes the same values as on the REST route
("point", "entrance" or {place_id, entrance_kind, wheelchair}), and
the answer's arrival says which door the session ends at, or why none.
{"name": "check_navigation_progress",
"arguments": {"session_id": "nav_3f2c...",
"lat": 51.5131, "lon": -0.0796, "heading_deg": 140,
"timestamp": "2026-11-20T16:04:05Z"}}
An assistant should read next_instruction aloud when
instruction_changed is true, say nothing new on off_route, read the
new instruction on rerouted, and call end_navigation on arrived.
Sessions expire after two hours idle and do not survive a gateway restart,
so an assistant that gets "session not found" should start a new one from
the traveller's current position. When arrival.applied is false, it
should say the trip ends at the place itself and pass on the reason. Every input and output field is in the
MCP tool reference.
In the SDKs
Web, @mapmap/maps. startNavigationSession,
sendNavigationProgress, getNavigationSession and
endNavigationSession wrap the four routes; arriveAt takes "point",
"entrance" or { placeId, entranceKind, wheelchair } and the session
carries arrival. They are not in a published
@mapmap/maps release yet; until they are, call the routes directly as
above.
The web SDK's session surface, for reference:
- Calls:
startNavigationSession(client, request)takes aStartNavigationSessionRequest(NavigationWaypointorigin and destination, aNavigationCosting, an optionalNavigationAdrProfile,arriveAt, andNavigationRequestOptionsfor landmarks, language and units) and returns aNavigationSession;sendNavigationProgress(client, id, fix)takes aNavigationFixand returns aNavigationProgress;getNavigationSessionreturns aNavigationSessionView;endNavigationSessionresolves once the session is gone.clientis a map orGatewayClientOptions(baseUrl,apiKey). - Parts of the answers:
NavigationRouteSummary(withetaCalibrationon GB routes),NavigationInstruction,NavigationLatLon,NavigationFixReason(why a fix was not used) andNavigationRerouteSkipped(why a confirmed departure did not reroute).ArriveAtEntranceandArrivalEntranceKindtype the door form ofarriveAt;EntranceArrivalis thearrivalblock. - Wire helpers, for clients that send their own requests:
buildNavigationSessionBody,buildNavigationProgressBodyandbuildArriveAtWirewrite the request bodies;parseNavigationSession,parseNavigationProgress,parseNavigationSessionView,parseNavigationRoute,parseNavigationInstructionandparseEntranceArrivalread the answers. - Errors are a
GatewayErrorcarrying the status and the problem fields, withsessionGone(404: start a new session),sessionLimit(429) andentrancesNotEnabled(501).
Generated API clients. The routes are in the gateway's OpenAPI document
under the routing tag, as the operations create_navigation_session,
send_navigation_progress, get_navigation_session and
delete_navigation_session, so a client generated from it gets them as
methods. With the TypeScript client (@mapmap/api-client):
import { Configuration, RoutingApi } from "@mapmap/api-client";
const routing = new RoutingApi(
new Configuration({ basePath: "https://api.mapmap.ai", accessToken: "snk_..." }),
);
const session = await routing.createNavigationSession({
createSessionRequest: {
origin: { lat: 52.2, lon: 0.13 },
destination: { lat: 52.204, lon: 0.142 },
costing: "pedestrian",
},
});
const answer = await routing.sendNavigationProgress({
id: session.sessionId,
progressRequest: {
lat: 52.2001,
lon: 0.1342,
headingDeg: 91,
timestamp: new Date().toISOString(),
},
});
console.log(answer.state, answer.nextInstruction?.text);
await routing.deleteNavigationSession({ id: session.sessionId });
With the Python client (mapmap-client):
import mapmap_client
from mapmap_client.api.routing_api import RoutingApi
from mapmap_client.models.create_session_request import CreateSessionRequest
from mapmap_client.models.progress_request import ProgressRequest
config = mapmap_client.Configuration(host="https://api.mapmap.ai", access_token="snk_...")
with mapmap_client.ApiClient(config) as api:
routing = RoutingApi(api)
session = routing.create_navigation_session(CreateSessionRequest.from_dict({
"origin": {"lat": 52.2, "lon": 0.13},
"destination": {"lat": 52.204, "lon": 0.142},
"costing": "pedestrian",
}))
answer = routing.send_navigation_progress(session.session_id, ProgressRequest.from_dict({
"lat": 52.2001, "lon": 0.1342, "heading_deg": 91,
"timestamp": "2026-11-20T16:04:05Z",
}))
print(answer.state)
routing.delete_navigation_session(session.session_id)
Mobile, React Native, Android and iOS. No session methods: these SDKs run guidance on the device already (see SDKs), which needs no request per position and keeps working with no signal.
Next steps
- Place entrances: end a journey at a building's mapped door
- Analysis APIs: the stateless
POST /route/progress, matrices and isochrones - API reference:
POST /routeand the options a session inherits - MCP server: connect an assistant to these tools