POST/v1/coverage/guidance

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 50 shape points walked (every piece's points, each join counted once), and never less than 1 call per piece, at most 400 pieces. A refused piece keeps its quota units and takes no credit, as a `/trace_route` engine refusal does; a walk past the route's own deadline is not billed. Class: standard, or premium for truck and ADR work. Published as `unit_rules.coverage_guidance` in /pricing.json.
Premium	When the plan guided is a truck plan (its pieces carry `"costing": "truck"`)

What it does

Turn-by-turn guidance for one drive of a coverage plan.

An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 1 call per started block of 50 shape points walked (every piece's points, each join counted once), and never less than 1 call per piece, at most 400 pieces. A refused piece keeps its quota units and takes no credit, as a /trace_route engine refusal does; a walk past the route's own deadline is not billed.

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/coverage/guidance" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chunk":{},"chunk_id":0,"drive":"outing","job_id":"string"}'

Request body

application/json · CoverageGuidanceRequest

The drive to guide: job_id (your own succeeded POST /v1/jobs/coverage job) with chunk_id (an outing's id), or chunk (an outing or transfer object exactly as the job returned it); drive is outing (the default), transfer (the outing's transfer_from_previous) or transfer_to_start. Every piece of the drive's trace_route_parts is walked with shape_match: edge_walk, never map matching. Metered as one call: one call per started 50 shape points walked (the pieces' points, each join counted once), and never less than one call per piece; premium for a truck plan. The pieces must be one drive, each starting where the one before ends

Field	Type	Required	Description
chunk	object	no	Instead of `job_id`: the object exactly as the job returned it. An outing (`result.chunks[i]`), whose `transfer_from_previous` is used with `drive: transfer`; or a transfer object itself (`transfer_from_previous`, `transfer_to_start`). Only its `trace_route_parts` are read.
chunk_id	integer	no	The outing's `id` in that job's `chunks` (from 1).
drive	CoverageGuidanceDrive	no	`outing` (the default), `transfer` or `transfer_to_start`.
job_id	string	no	A coverage job's id (`POST /v1/jobs/coverage`): the caller's own job (any key of the same account), succeeded. With `chunk_id`, unless `drive` is `transfer_to_start`.

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

json

{
  "chunk": {},
  "chunk_id": 0,
  "drive": "outing",
  "job_id": "string"
}

Responses

200One trip with one leg per piece, in driving order

Field	Type	Required	Description
chunk_id	integer	no	The outing's `id`, when the request named one.
drive	string	yes	The drive guided: `outing`, `transfer` or `transfer_to_start`.
job_id	string	no	The job it came from, for a job-id request.
pieces	integer	yes	Pieces walked: the trip has one leg per piece, in driving order.
trip	object	yes	The guidance: a Valhalla trip, as `/trace_route` answers one, with one leg per piece. Each leg is the engine's own answer for its piece (maneuvers, polyline6 `shape`, `summary`); `summary` is the whole drive's. Legs join exactly where one piece ends and the next begins, mid-street wherever the plan allowed: a leg's closing arrival and the next leg's opening departure there mean carry straight on.

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

json

{
  "drive": "string",
  "pieces": 0,
  "trip": {}
}

400No drive named, a drive with no usable trace_route_parts (a plan made before they existed), or a job that is not a succeeded coverage plan