Documentation menu
POST/route/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 | A flat 5 calls. Class: standard, or premium for truck and ADR work. Published as unit_rules.route_progress in /pricing.json. |
| Premium | When the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true |
What it does
Where a vehicle is against its plan, computed statelessly: nothing about the position is stored.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: A flat 5 calls.
Call it
curl -fsS -X POST "https://api.mapmap.ai/route/progress" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonRequest body
application/json
Where a vehicle is against its plan, statelessly. The plan as geometry_polyline6, or origin + destination + costing (the route-input contract POST /v1/fuel/along accepts), plus current_position {lat, lon}; optional recent_trace (up to 100 points, oldest first: switches snapping from geometric projection to engine map matching), off_route_threshold_m (default 50), Valhalla costing_options and a top-level adr profile. NO POSITIONS ARE STORED: the request is answered and forgotten
Example: From website/public/docs/analysis.md:813, with a polyline6 recorded from GET /route/v1 on 2026-11-05
{
"costing": "auto",
"current_position": {
"lat": 51.5045,
"lon": -0.1262
},
"geometry_polyline6": "{swfaBl_yF[gJWuBSsBM_D@sCLuBXyA^}Ap@cBb@aAb@m@^]PGb@CfANnA\\x@\\x@r@~AlCxAh@pAHfAArPsAvBs@`H}BbIwCfLsFnCmAxAsDn@[pAi@~C_BnH}CvM}ElFgBtEsBhHwCtHeCvAa@dBe@xGyBzFeB|@YdEmAdHaBrJaBbCa@`Hg@|AK|Ls@vUqAjBKpIs@vAKdFS~BKtFWpDKbE@|JNdCD`DHfA@hB@fGNvDb@b[hC`GV|BhAzI^|AHh@BpFKbBE~@AnCCfCE`BHtFRD{IBqBFgGSGe@[_@c@We@Se@Qc@Me@Ig@Eg@Cg@Ag@FkGAi@Cc@E_@I]K[K_@I[C[AYRaSBm@Hq@Nm@Ri@Vg@Xa@ZYNG",
"off_route_threshold_m": 60
}Responses
{costing, stateless: true, plan: {length_m, source, duration_s, distance_m}, position: {input, snapped, method, along_m}, progress: {fraction, travelled_m, plan_remaining_m}, off_route, off_route_m, off_route_threshold_m, arrived, remaining: {distance_m, duration_s, method}, eta: {duration_s, arrival_estimate_utc, traffic}}. method is projection (single fix, geometric) or map_matched (a recent_trace was matched through the engine). remaining is a fresh engine search from where the vehicle is to the plan's final point, so it can differ from progress.plan_remaining_m; eta.traffic carries the same coverage/confidence provenance POST /route reports| Field | Type | Required | Description |
|---|---|---|---|
| arrived | boolean | no | Whether the position is at the end of the plan. |
| costing | string | no | The costing the remaining time was computed with. |
| eta | object | no | Arrival estimate: arrival_estimate_utc, duration_s, and the
traffic annotation it used, with its attribution and caveats. |
| off_route | boolean | no | Whether the position is further from the plan than the threshold. |
| off_route_m | number | no | Distance from the plan, in metres. |
| off_route_threshold_m | number | no | The off-route threshold applied, in metres. |
| plan | object | no | The plan that was read: length_m and its source. |
| position | object | no | The input position, where it snapped onto the plan, along_m
and the method used. |
| privacy | string | no | What is kept: nothing, the request is answered and discarded. |
| progress | object | no | fraction of the plan done, travelled_m and
plan_remaining_m. |
| remaining | object | no | How long and how far is left, and how that was computed. |
| stateless | boolean | no | Always true: no session is kept between calls. |
Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /route/progress with the request example; lists trimmed to their first items
{
"arrived": false,
"costing": "auto",
"eta": {
"arrival_estimate_utc": "2026-11-05T20:43:17.378368575Z",
"duration_s": 103,
"traffic": {
"attribution": [
"Powered by National Highways' Transport Data Feeds"
],
"available": true,
"caveats": "covered_pct is measured geometrically: the leg's shape is matched against the traffic network's own link geometry (within 30 m) and credited by distance, because the routing engine's turn-by-turn response exposes no per-edge speed source and deriving one would cost a second engine call. It states that a record existed for that road at request time, not that the engine's blend used that exact value, and not the direction of travel (both carriageways of a link match). confidence is a distance-weighted data-quality score in HERE's published bands (>0.7 live-dominated, 0.5-0.7 historical, <0.5 default speeds); it is not a probability that the ETA is correct, and it is never raised above what the request's own date_time/speed_types permit.",
"coverage_note": "Traffic records cover the National Highways strategic road network in England. Local roads, Scotland and Wales carry no record, so distance off that network is reported as `default`: an absence of data, never a claim that the road is clear.",
"legs": [
{
"band": "default",
"confidence": 0.25,
"covered_pct": 0,
"distance_m": 537.2,
"shares": {
"default": 1,
"live": 0,
"predicted": 0,
"profile": 0
},
"sources": [
"default"
]
}
],
"method": "link_coverage_v1",
"network": "UK strategic road network (National Highways NTIS links)",
"note": "this request carries no `date_time`, so the engine costs it with default speeds: no live or typical-speed claim is made. Send `date_time: {\"type\": 0, \"value\": …}` for live-aware costing.",
"route": {
"band": "default",
"confidence": 0.25,
"covered_pct": 0,
"distance_m": 537.2,
"shares": {
"default": 1,
"live": 0,
"predicted": 0,
"profile": 0
},
"sources": [
"default"
]
},
"snapshot": {
"links_live": 57193,
"links_predicted": 9061,
"links_profile": 0,
"source_ts": "2026-11-05T20:40:30Z",
"stale": false
},
"speed_layers": {
"live_claimable": false,
"profile_claimable": false
}
}
},
"off_route": false,
"off_route_m": 1.4,
"off_route_threshold_m": 60,
"plan": {
"length_m": 934.5,
"source": "geometry_polyline6"
},
"position": {
"along_m": 401.9,
"input": {
"lat": 51.5045,
"lon": -0.1262
},
"method": "projection",
"snapped": {
"lat": 51.5045,
"lon": -0.1262
}
},
"privacy": "no positions are stored: the plan and the position are read from this request, answered, and discarded",
"progress": {
"fraction": 0.4301,
"plan_remaining_m": 532.5,
"travelled_m": 401.9
},
"remaining": {
"distance_m": 540,
"duration_s": 103,
"method": "engine"
},
"stateless": true
}recent_trace, or a plan geometry with fewer than two pointsapplication/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
text/plain
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
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-12 · operationId post_route_progress