# 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](/docs/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

| 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](#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`](/docs/entrances#ending-a-route-at-the-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": "..."}
}
```

| 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`](/docs/api-reference) (`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](/docs/entrances)), `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

```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"
}
```

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

```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](/docs/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](/pricing) and in
[`/pricing.json`](/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`](/docs/analysis#progress-against-a-plan-post-routeprogress)
answers that per request.

## Over MCP

Three tools on the [MCP server](/docs/mcp) 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. |

```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](/docs/mcp-tools).

## 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](/docs/sdks)), which needs no
request per position and keeps working with no signal.

## Next steps

- [Place entrances](/docs/entrances): end a journey at a building's mapped door
- [Analysis APIs](/docs/analysis): the stateless `POST /route/progress`, matrices and isochrones
- [API reference](/docs/api-reference): `POST /route` and the options a session inherits
- [MCP server](/docs/mcp): connect an assistant to these tools
