POST/v1/coverage/reroute

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 request, as a two-point `/route`. Any refusal once the network round the drive has been read (`coverage-reroute-refused`, with a `reason`) keeps its quota unit and takes no credit; a refusal decided before that read (the request's own shape, steps that do not join, a drive planned on another graph (409), a box over the area or edge ceiling) and a `503` `coverage-reroute-busy` are not billed. Class: standard, or premium for truck and ADR work. Published as `unit_rules.coverage_reroute` in /pricing.json.
Premium	When the drive re-planned is a truck plan's (`"costing": "truck"`, a `trace_route` body carrying it, or a `job_id` naming a truck plan)

What it does

Re-plan the rest of a coverage drive in progress round a block.

An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per request, as a two-point /route. Any refusal once the network round the drive has been read (coverage-reroute-refused, with a reason) keeps its quota unit and takes no credit; a refusal decided before that read (the request's own shape, steps that do not join, a drive planned on another graph (409), a box over the area or edge ceiling) and a 503 coverage-reroute-busy are not billed.

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/coverage/reroute" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position":{"lat":-90,"lon":-180}}'

Request body

application/json · CoverageRerouteRequest

The drive (job_id with chunk_id and drive, or the plan's steps or trace_route with its graph_osm_timestamp), where the car is (position, with heading), what is closed (avoid, as for a plan) and optionally step_index (the step the car is on) and skip_weight (0 to 100, default 1.5). Synchronous and stateless: nothing is stored. Metered as one call, like a two-point route; premium for a truck plan

Field	Type	Required	Description
avoid	CoverageAvoid	no
chunk_id	integer	no	The outing's `id` in that job's `chunks` (from 1).
costing	CoverageCosting	no
drive	CoverageGuidanceDrive	no	Which drive: `outing` (the default), `transfer` (the outing's `transfer_from_previous`) or `transfer_to_start`. With `job_id`, or with `trace_route` (a transfer's steps are all deadhead).
graph_osm_timestamp	string	no	With `steps` or `trace_route`: the plan's `graph.osm_timestamp`. It must be the served graph's (edge ids change with every rebuild): otherwise the answer is a 409. Leave it out only when the plan had none.
include_private	boolean	no	Drive private and destination-only roads too. With `job_id`, the plan's own setting unless this is sent; otherwise `false` unless sent (send `true` when the plan was made with it).
job_id	string	no	A coverage job's id: the caller's own succeeded `POST /v1/jobs/coverage` job. With `chunk_id` (unless `drive` is `transfer_to_start`). The drive, the costing and the graph's timestamp are read from the stored plan.
position	CoverageReroutePosition	yes	Where the car is, and which way it faces.
skip_weight	number	no	What leaving a metre of street uncovered is worth, in metres driven (0 to 100, default 1.5). The rest of the drive rejoins at the step where the drive there plus `skip_weight` times the covering metres left out is least: higher drives further to cover more; 0 rejoins wherever is nearest.
step_index	integer	no	The step (from 0) the car is on or about to drive: the steps before it are driven already. Without it, the step the car is found on when it is on exactly one step of the drive (on a street the drive passes twice the way the car faces, send it), else the first step.
steps	CoverageRerouteStep[]	no	Instead of `job_id`: the drive's steps as the plan returned them (`chunks[].steps`), in order, at most 10,000. Each step must start where the one before ends.
trace_route	object	no	Instead of `job_id` or `steps`: the drive's `trace_route` body as the plan returned it (its `encoded_polyline` and `costing` are read). Its steps are found by matching it edge for edge to the served graph; with `drive: outing` the first pass along each street covers it.
turn_penalties	TurnPenalties	no

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json

{
  "position": {
    "lat": -90,
    "lon": -180
  }
}

Responses

200The rest of the drive from the car, round the blocks, as a chunk, with the covering steps left out (skipped) and the driving added (detour_km)

Field	Type	Required	Description
avoid_unmatched	CoverageAvoidUnmatched	no
avoided_edges	integer	yes	Directed edges `avoid` closed.
blocks_spliced	integer	yes	Later runs of closed steps spliced round, each with its own cheapest way round.
chunk	CoverageChunk	yes	The new rest of the drive, from where the car is to the drive's end, as a plan's outing: `steps`, `geometry`, `trace_route` and `trace_route_parts` (for `POST /v1/coverage/guidance` with `chunk`). Its covering steps are the drive's own still to drive; the ways round are deadhead, except a pass along a street left out elsewhere, which covers it. Its first step starts where the car is, mid-street if need be.
chunk_id	integer	no	The outing's `id`, when the request named one.
detour_km	number	yes	Driving the new drive adds that is not the drive's own steps: the way from the car to where it rejoins, the ways round later blocks and round turns, km.
drive	string	yes	The drive re-planned: `outing`, `transfer` or `transfer_to_start`.
ends_before_step	integer	no	When a later block leaves no legal way on: the closed step the new drive ends before (everything from it is in `skipped`).
graph_osm_timestamp	string	no	The served graph's OpenStreetMap snapshot.
job_id	string	no	The job it came from, for a job-id request.
notes	string[]	yes	What the answer does not know or promise.
rejoin_step	integer	no	The step (index in the drive sent) the new drive rejoins the drive at; `null` when it goes straight to the drive's end.
remaining_km	number	yes	The drive as sent from `step_index` on, km.
skipped	CoverageRerouteSkipped[]	yes	Covering steps from `step_index` on that the new drive does not drive, in order: exactly what is left uncovered.
skipped_km	number	yes	Their length, km.
step_index	integer	yes	The step the re-plan started from: the car is on it or about to drive it.
step_index_from	string	yes	Where `step_index` came from: `sent`, `car` (the car was found on that step) or `first_step` (the car is on no step of the drive).
turned_round	boolean	yes	The way ahead of the car was closed, so the new drive starts by turning round in its street.
turns	CoverageRerouteTurns	yes	What the turn repair pass did.

Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json

{
  "avoided_edges": 0,
  "blocks_spliced": 0,
  "chunk": {
    "covered_edge_ids": [
      0
    ],
    "deadhead_km": 0,
    "drive_time_s": 0,
    "end": {
      "lat": -90,
      "lon": -180
    },
    "geometry": "string",
    "id": 0,
    "km": 0,
    "start": {
      "lat": -90,
      "lon": -180
    },
    "steps": [
      {}
    ],
    "trace_route": {}
  },
  "detour_km": 0,
  "drive": "string",
  "notes": [
    "string"
  ],
  "remaining_km": 0,
  "skipped": [
    {
      "edge_id": 0,
      "length_m": 0,
      "step": 0,
      "way_id": 0
    }
  ],
  "skipped_km": 0,
  "step_index": 0,
  "step_index_from": "string",
  "turned_round": false,
  "turns": {
    "refused_turns_left": 0,
    "repair_km": 0,
    "restricted_turns_repaired": 0,
    "u_turns_replaced": 0
  }
}

400Decided before the network round the drive is read, and not billed: no drive named, a malformed body, a step whose edge id is not an edge of the served graph or whose way id is not the edge's, steps that do not join, steps whose tiles lie too far apart for one drive, a trace_route costing that disagrees with costing, or a job that is not a succeeded coverage plan