Skip to content
Documentation menu
docs / api / post-route-progress
Routing

POST/route/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.
PriceA flat 5 calls. Class: standard, or premium for truck and ADR work. Published as unit_rules.route_progress in /pricing.json.
PremiumWhen 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

bash
curl -fsS -X POST "https://api.mapmap.ai/route/progress" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Request 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

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

200{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
FieldTypeRequiredDescription
arrivedbooleannoWhether the position is at the end of the plan.
costingstringnoThe costing the remaining time was computed with.
etaobjectnoArrival estimate: arrival_estimate_utc, duration_s, and the traffic annotation it used, with its attribution and caveats.
off_routebooleannoWhether the position is further from the plan than the threshold.
off_route_mnumbernoDistance from the plan, in metres.
off_route_threshold_mnumbernoThe off-route threshold applied, in metres.
planobjectnoThe plan that was read: length_m and its source.
positionobjectnoThe input position, where it snapped onto the plan, along_m and the method used.
privacystringnoWhat is kept: nothing, the request is answered and discarded.
progressobjectnofraction of the plan done, travelled_m and plan_remaining_m.
remainingobjectnoHow long and how far is left, and how that was computed.
statelessbooleannoAlways 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

json
{
  "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
}
400Invalid request: no plan or both plan forms, a bad coordinate, an over-long recent_trace, or a plan geometry with fewer than two points

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

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

502Upstream routing engine failed, including a trace the matcher could not match; never a silent fall back to geometric projection

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-12 · operationId post_route_progress