Documentation menu
POST/v1/jobs/coverage
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 | 20 calls per started square kilometre of the area. Class: standard, or premium for truck and ADR work. Published as unit_rules.async_jobs in /pricing.json. |
| Premium | When the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true |
What it does
Submit a drive-every-street coverage plan to the asynchronous lane.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: 20 calls per started square kilometre of the area.
Call it
curl -fsS -X POST "https://api.mapmap.ai/v1/jobs/coverage" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d '{"bbox":[-0.143,50.8205,-0.136,50.8245],"chunk_km":5,"costing":"auto","exclude":{"areas":{"coordinates":[[[-0.1415,50.823],[-0.1395,50.823],[-0.1395,50.824],[-0.1415,50.824],[-0.1415,50.823]]],"type":"Polygon"},"way_ids":[330714667]},"optimise":"distance","start":{"lat":50.8222,"lon":-0.1405},"turn_penalties":{"avoid_right":30,"avoid_u_turn":200}}'Request body
application/json · CoverageRequest
An area (bbox or a GeoJSON polygon) and how to drive it: costing (auto or truck), road_classes, include_private, optimise (distance, the default, time or balanced), turn_penalties (avoid_left, avoid_right, avoid_u_turn, metres of equivalent driving per turn, in the same unit every objective uses), chunk_km or instead chunk_time_s (outings by trip time, 900 to 21,600 s; both is a 400), chunk_tolerance, time_factor (0.5 to 3, multiplies every time), start, return_to_start, chunk_loops (every outing a closed loop, with the drive between outings planned as a separate route in each chunk's transfer_from_previous; walk_km excludes those transfers, summary.transfer_km has them), loop_radius_m (0 to 2,000 m, only with chunk_loops: how far from its start an outing may end when that saves driving), exclude (need not cover, may still drive), avoid (never drive, deadhead and transfers included: way_ids, and locations with optional radius_m, heading, heading_tolerance; streets to cover it closes or cuts off are listed in summary.dropped_ways with why), plus an optional webhook_url. Turns the graph forbids, and U-turns where a street merely continues, on a bridge or on a tertiary or bigger road, are replaced by the cheapest legal way round unless none exists; other U-turns not at a dead end are replaced when that costs less than avoid_u_turn. Transfers between chunk_loops outings are not checked for U-turns. Charged per started square kilometre of the area's bounding box at submission (the most a plan can cost); on success billed on the larger of the polygon's own area and the street floor (street length asked for over 20 km per km2), the difference handed back (billing in the result); refunded in full if the job fails. The result, once the job succeeds, is a CoverageResponse
| Field | Type | Required | Description |
|---|---|---|---|
| avoid | CoverageAvoid | no | |
| bbox | number[] | no | [min_lon, min_lat, max_lon, max_lat]. Exactly one of bbox and
polygon. |
| boundary | CoverageBoundary | no | Which streets crossing the area's edge must be covered: touching
(the default: every street any part of which is inside, covered to
its far end outside), mostly_inside (more than half its length
inside, the rule exclude.areas uses) or inside (wholly inside).
Streets it leaves out may still be driven to connect others, as
deadhead. |
| chunk_km | number | no | Target outing length, km (default 15, 1 to 150). Outings are made
as close to it as the streets allow: the drive is shared into the
whole number of outings whose even share is nearest chunk_km.
Not with chunk_time_s (both is a 400). |
| chunk_loops | boolean | no | Make every outing a closed loop (default false): each one starts
and ends at the same junction, its way back made of streets it
covers, and the drive from one outing's end to the next one's start
is planned as a separate route (transfer_from_previous), not part
of any outing. Outings are grouped as close to chunk_km as the
streets allow; summary.outings_outside_target names any outside
chunk_km * (1 +/- chunk_tolerance), and why. |
| chunk_time_s | number | no | Target outing time instead of a length, seconds (900 to 21,600: 15
minutes to 6 hours). Not with chunk_km (both is a 400); with
neither, outings aim at the default chunk_km. The planner aims at
it as it aims at chunk_km: the whole number of outings whose even
share of time is nearest it, grouped by time. What counts is each
outing's trip_time_s: its own drive_time_s and, with
chunk_loops, the transfer into it (for the first outing, the
drive from where the car is with start.snap: exact) and for the
last the drive back to the start with return_to_start. Times are
the routing graph's edge speeds plus the engine's own junction time,
times time_factor; summary.outing_time_s says how close the
outings came. |
| chunk_tolerance | number | no | How far either way of the target (chunk_km, or chunk_time_s) an
outing may land and still count as on target, as a share of it
(default 0.25, 0.05 to 0.5). The planner always aims at the target
itself, never at the edge of this band. With chunk_loops, every
outing outside target * (1 +/- chunk_tolerance) is listed in
summary.outings_outside_target with why; in both modes
summary.outing_km.within_tolerance and
summary.outing_time_s.within_tolerance count the outings inside
it, and the drive is never shared into outings longer than its top
when one more outing would bring them inside. |
| costing | CoverageCosting | no | auto (default) or truck. |
| exclude | CoverageExclude | no | |
| include_private | boolean | no | Drive and cover private and destination-only roads too (default
false). The graph records OSM access=private and
access=destination alike as destination-only. |
| loop_radius_m | number | no | With chunk_loops: how far from its start an outing may end, metres
(0 to 2,000, default 0: at its own start junction). Above 0, an
outing leaves off the connecting drive at its end when it still ends
within this distance (straight line) of where it started and that
saves driving, the transfer to the next outing included. Refused
without chunk_loops. |
| optimise | CoverageObjective | no | What to minimise: distance (default), time or balanced. |
| polygon | object | no | A GeoJSON Polygon or MultiPolygon geometry (longitude, latitude),
at most 10,000 vertices and 50 polygons. Polygons that overlap or
share an edge are merged into one area; a polygon that is invalid on
its own (a ring that crosses itself, a hole outside its outer ring)
is refused, naming the polygon, the ring and the fault. |
| required | CoverageRequired | no | |
| return_to_start | boolean | no | End where the drive started (default true). With false the plan
ends wherever leaves the least driving: without start, its
longest run of connecting drive is left off the end of the closed
drive; with start, it starts there and its end is chosen with the
rest of the plan (often at the far end of a dead end). With
chunk_loops, whether a final transfer from the last outing back to
the start is planned (transfer_to_start). |
| road_classes | RoadClassFilter | no | |
| start | CoverageStart | no | |
| time_factor | number | no | Multiplies every time the plan uses and reports (default 1, 0.5 to
3): each drive_time_s, trip_time_s, summary.outing_time_s, and
the planning against chunk_time_s. It is the caller's own pace
correction, for a vehicle that drives slower (above 1) or faster
(below 1) than the routing graph's speeds, a survey car for one;
the routing engine knows nothing of it, so a /route or guidance
time for the same drive is the engine's own, unscaled. What is
driven never changes with it. |
| turn_penalties | TurnPenalties | no | Turn penalties. |
| webhook_url | string | no | Job lane: where to POST the signed completion notice. |
Example: From website/public/docs/api-reference.md:3275
{
"bbox": [
-0.143,
50.8205,
-0.136,
50.8245
],
"chunk_km": 5,
"costing": "auto",
"exclude": {
"areas": {
"coordinates": [
[
[
-0.1415,
50.823
],
[
-0.1395,
50.823
],
[
-0.1395,
50.824
],
[
-0.1415,
50.824
],
[
-0.1415,
50.823
]
]
],
"type": "Polygon"
},
"way_ids": [
330714667
]
},
"optimise": "distance",
"start": {
"lat": 50.8222,
"lon": -0.1405
},
"turn_penalties": {
"avoid_right": 30,
"avoid_u_turn": 200
}
}Responses
result_url, or wait for the signed webhook; the job's result is a CoverageResponse| Field | Type | Required | Description |
|---|---|---|---|
| id | string | yes | The job id to poll. |
| kind | string | yes | optimise, replan, matrix or coverage. |
| result_url | string | yes | Where to fetch it. The same URL the webhook will carry. |
| status | string | yes | Always queued, the worker has not looked at it yet. |
| units_charged | integer | yes | Quota units this submission drew. Charged now, refunded in full if the job fails. |
Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call
{
"id": "string",
"kind": "string",
"result_url": "string",
"status": "string",
"units_charged": 0
}webhook_urlapplication/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
webhook_url was given but the key has no webhook signing secretapplication/problem+json · Problem
text/plain
coverage-too-large: the area is over SN_COVERAGE_MAX_AREA_KM2 (100 km2 by default), or the drivable edges in it over SN_COVERAGE_MAX_EDGES; the body names limit, max, got and limit_envapplication/problem+json · Problem
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 Optimisation and jobs
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_coverage_job