Skip to content
Documentation menu
docs / api / post-v1-navigation-sessions-id-progress
Routing

POST/v1/navigation/sessions/{id}/progress

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 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.
PremiumWhen 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

bash
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

NameInTypeRequiredDescription
idpathstringyesThe 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

FieldTypeRequiredDescription
accuracy_mnumbernoHorizontal accuracy the receiver states, metres.
heading_degnumbernoDirection of travel (or facing, on foot), degrees clockwise from true north, 0 <= heading_deg < 360.
latnumberyesLatitude, WGS84.
lonnumberyesLongitude, WGS84.
speed_mpsnumbernoSpeed over ground, metres per second.
timestampobjectyesWhen 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

json
{
  "lat": 0,
  "lon": 0,
  "timestamp": {}
}

Responses

200state (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
FieldTypeRequiredDescription
current_instructionInstructionno
distance_to_next_mnumbernoMetres to the next manoeuvre, along the route.
etastringnoArrival estimate, the gateway's clock plus remaining_s (RFC 3339 UTC).
expires_atstringyesWhen the session expires if left idle from now.
fixFixVerdictyesWhether guidance used this fix.
instruction_changedbooleanyesWhether next_instruction differs from the one last reported: read it out when true.
next_instructionInstructionno
numbers_currentbooleanyesWhether the numbers above are from this fix (true) or the last accepted one (false, when this fix was not used).
off_routeOffRouteno
remaining_mnumbernoMetres still to go, along the route.
remaining_snumbernoSeconds still to go.
reroutesintegeryesReroutes so far.
routeRouteSummaryno
session_idstringyesThe session.
snappedSnappedno
statestringyeson_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

json
{
  "expires_at": "string",
  "fix": {
    "accepted": false
  },
  "instruction_changed": false,
  "numbers_current": false,
  "reroutes": 0,
  "session_id": "string",
  "state": "string"
}
400A bad coordinate, heading, speed, accuracy or timestamp

application/problem+json · Problem

401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)

application/problem+json · Problem

404No such session for this key: never created, another key's, deleted, expired, or lost to a gateway restart. Not billed

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (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