Documentation menu
POST/v1/navigation/sessions/{id}/progress
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 started block of 30 progress requests in the session, plus 1 call for each reroute the session made, billed on its next progress request; a progress request between blocks draws no units. A 404 for a session this key does not hold is not billed. Class: standard, or premium for truck and ADR work. Published as unit_rules.navigation_session in /pricing.json. |
| Premium | When the session is: its costing is truck or it carries an adr profile |
What it does
Report one position and get the state, the next instruction and what is left to go.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per started block of 30 progress requests in the session, plus 1 call for each reroute the session made, billed on its next progress request; a progress request between blocks draws no units. A 404 for a session this key does not hold is not billed.
Call it
curl -fsS -X POST "https://api.mapmap.ai/v1/navigation/sessions/{id}/progress" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d '{"lat":0,"lon":0,"timestamp":{}}'Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes | The session id POST /v1/navigation/sessions returned |
Request body
application/json · ProgressRequest
One fix: lat, lon, timestamp (RFC 3339 or epoch milliseconds), and optionally heading_deg, speed_mps and accuracy_m. A fix stated worse than 50 m, or one implying an impossible speed, is lost_position and never counts towards a reroute. A reroute needs three off-route fixes over at least five seconds, and at most one fires every ten seconds. Metered per session: one call for every started block of 30 progress requests, plus one call for a reroute, reserved on a request that could confirm one and returned if none is computed; Premium when the session is. A fix over 5 km from the route is lost_position, and a reroute over the route span cap is skipped
| Field | Type | Required | Description |
|---|---|---|---|
| accuracy_m | number | no | Horizontal accuracy the receiver states, metres. |
| heading_deg | number | no | Direction of travel (or facing, on foot), degrees clockwise from
true north, 0 <= heading_deg < 360. |
| lat | number | yes | Latitude, WGS84. |
| lon | number | yes | Longitude, WGS84. |
| speed_mps | number | no | Speed over ground, metres per second. |
| timestamp | object | yes | When the fix was taken: RFC 3339 (2026-11-20T16:04:05Z) or
milliseconds since the Unix epoch. |
Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call
{
"lat": 0,
"lon": 0,
"timestamp": {}
}Responses
state (on_route, off_route, rerouted, arrived or lost_position), whether the fix was used, the snapped position, the next instruction with its landmark and a phrase from the given heading, instruction_changed, distance_to_next_m, remaining_m, remaining_s and eta. On rerouted the new route is included| Field | Type | Required | Description |
|---|---|---|---|
| current_instruction | Instruction | no | |
| distance_to_next_m | number | no | Metres to the next manoeuvre, along the route. |
| eta | string | no | Arrival estimate, the gateway's clock plus remaining_s (RFC 3339 UTC). |
| expires_at | string | yes | When the session expires if left idle from now. |
| fix | FixVerdict | yes | Whether guidance used this fix. |
| instruction_changed | boolean | yes | Whether next_instruction differs from the one last reported:
read it out when true. |
| next_instruction | Instruction | no | |
| numbers_current | boolean | yes | Whether the numbers above are from this fix (true) or the last
accepted one (false, when this fix was not used). |
| off_route | OffRoute | no | |
| remaining_m | number | no | Metres still to go, along the route. |
| remaining_s | number | no | Seconds still to go. |
| reroutes | integer | yes | Reroutes so far. |
| route | RouteSummary | no | |
| session_id | string | yes | The session. |
| snapped | Snapped | no | |
| state | string | yes | on_route, off_route, rerouted, arrived or lost_position. |
Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call
{
"expires_at": "string",
"fix": {
"accepted": false
},
"instruction_changed": false,
"numbers_current": false,
"reroutes": 0,
"session_id": "string",
"state": "string"
}application/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
application/problem+json · Problem
text/plain
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)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 post_progress