Skip to content
Documentation menu
docs / navigation-sessions · raw .md

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

  1. POST /v1/navigation/sessions computes the route and opens a session over it. The answer carries the session_id, the route summary and the first instruction.
  2. POST /v1/navigation/sessions/{id}/progress takes one position fix and answers with a state and the next instruction. Post one fix per update from the device's location source; there is no need to resend the route.
  3. 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".
  4. DELETE /v1/navigation/sessions/{id} ends the session. GET on the same path reads it back without posting a fix.
bash
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 GET resets the clock. expires_at in 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 404 and 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 429 with the problem type nav-session-limit; end sessions you no longer need with DELETE rather than waiting for them to expire.

Opening a session: POST /v1/navigation/sessions

Answers 201 Created.

Request fields

FieldTypeMeaning
originobject, requiredWhere the journey starts: {lat, lon}, or {place_id} with a place id from GET /geocode/suggest or GET /geocode. Never both.
destinationobject, requiredWhere it ends, in the same shape as origin.
costingstringauto (default), truck, bus, motorcycle, motor_scooter, bicycle or pedestrian, as on POST /route.
costing_optionsobjectPer-costing options, exactly as on POST /route.
truckobjectThe vehicle's dimensions, as the top-level truck object POST /route accepts.
adrobjectA dangerous-goods profile (dimensions, tunnel_code, hazmat), as on POST /route. Needs costing: "truck".
arrive_atstring or objectWhere 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.landmarksbooleanLandmark phrasing on turns ("Turn left just after the Co-op"), on the first route and on every reroute. Default false.
options.languagestringInstruction language, for example en-GB or de-DE.
options.unitsstringkilometers (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. A destination given 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; without place_id the destination's own place_id is used. entrance_kind is one of main, yes, entry, service, staircase, home or garage. With wheelchair: true, or pedestrian costing with costing_options.pedestrian.type: "wheelchair", a door mapped wheelchair=yes is taken where one exists and a door mapped wheelchair=no never is. When driving, the door nearest a road the vehicle can use wins.
  • A destination given as {place_id} without arrive_at ends at the place's own position, not at a door: on sessions the door is only used when arrive_at asks 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.

bash
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

json
{
  "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": "..."}
}
FieldMeaning
session_idThe id to post progress to. Ids start nav_; anything else is a 404.
costingThe costing the session routes with.
routeversion (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_instructionThe first manoeuvre: step_index, text, verbal (the spoken form), landmark (when one was found), maneuver_type, street_names and location.
expires_atWhen the session expires if nothing else arrives (RFC 3339, UTC).
idle_ttl_sThe idle time in seconds: 7200.
privacyWhat the session keeps, in one sentence, so a client can show it.
landmarksOnly when landmarks were asked for: how many turns were annotated.
arrivalOnly 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_enforcementOnly 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

FieldTypeMeaning
lat, lonnumber, requiredThe position, WGS84.
timestampstring or number, requiredWhen the fix was taken: RFC 3339, or milliseconds since the Unix epoch.
heading_degnumberDirection 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_mpsnumberSpeed in metres per second.
accuracy_mnumberThe 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

json
{
  "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"
}
FieldMeaning
stateOne of the five states below.
fix{accepted: true}, or {accepted: false, reason} when the fix was not used (see "Fixes that are not used").
snappedOnly when this fix was placed on the route: the snapped position and the route's course there.
next_instructionThe 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_instructionThe 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_changedtrue when next_instruction is new since the last fix: read it out.
distance_to_next_mMetres to the next manoeuvre.
remaining_m, remaining_s, etaDistance, 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_currentfalse when the distances above are the last accepted fix's, because this fix was not used.
off_routeOnly 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.
routeOnly in rerouted: the new route, in the same shape as on opening, with a higher version.
reroutesReroutes so far in this session.
expires_atThe new expiry: this request reset the idle clock.

The five states

stateMeaningWhat a client does
on_routeThe fix is on the route.Read out next_instruction when instruction_changed is true.
off_routeThe 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.
reroutedA new route was computed from this fix. route carries it.Replace any drawn route and read out the new next_instruction.
arrivedThe traveller has reached the destination.Say so, then DELETE the session.
lost_positionThe 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_skippedMeaning
cooling_downA reroute was computed less than 10 seconds ago.
reroute_capThis session has used its 50 reroutes. Open a new session.
no_waypoint_leftThere is nothing left to route to.
span_exceededThe new route would be longer than this deployment's route span cap.
not_reservedThe request was not priced for a reroute (see Pricing). The next fix tries again.
engine_found_no_routeThe 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.reasonMeaning
low_accuracyThe fix's accuracy_m is too large to trust.
implausible_jumpThe 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_routeThe fix is too far from the route to belong to this journey.
out_of_orderIts timestamp is not after the last accepted fix's.
after_arrivalThe 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:

json
{"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).

StatusWhen
400A 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.
401Missing or invalid API key.
404On 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.
429nav-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.
502The 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:

ToolWrapsWhat it returns
start_navigationPOST /v1/navigation/sessionsThe session_id, the route summary and the first instruction.
check_navigation_progressPOST /v1/navigation/sessions/{id}/progressThe state, the next instruction and what is left to go.
end_navigationDELETE /v1/navigation/sessions/{id}Confirmation that the session has ended.
json
{"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.

json
{"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 a StartNavigationSessionRequest (NavigationWaypoint origin and destination, a NavigationCosting, an optional NavigationAdrProfile, arriveAt, and NavigationRequestOptions for landmarks, language and units) and returns a NavigationSession; sendNavigationProgress(client, id, fix) takes a NavigationFix and returns a NavigationProgress; getNavigationSession returns a NavigationSessionView; endNavigationSession resolves once the session is gone. client is a map or GatewayClientOptions (baseUrl, apiKey).
  • Parts of the answers: NavigationRouteSummary (with etaCalibration on GB routes), NavigationInstruction, NavigationLatLon, NavigationFixReason (why a fix was not used) and NavigationRerouteSkipped (why a confirmed departure did not reroute). ArriveAtEntrance and ArrivalEntranceKind type the door form of arriveAt; EntranceArrival is the arrival block.
  • Wire helpers, for clients that send their own requests: buildNavigationSessionBody, buildNavigationProgressBody and buildArriveAtWire write the request bodies; parseNavigationSession, parseNavigationProgress, parseNavigationSessionView, parseNavigationRoute, parseNavigationInstruction and parseEntranceArrival read the answers.
  • Errors are a GatewayError carrying the status and the problem fields, with sessionGone (404: start a new session), sessionLimit (429) and entrancesNotEnabled (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):

ts
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):

python
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