Skip to content
Documentation menu
docs / api / post-v1-jobs-coverage
Optimisation and jobs

POST/v1/jobs/coverage

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.
Price20 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.
PremiumWhen 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

bash
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

FieldTypeRequiredDescription
avoidCoverageAvoidno
bboxnumber[]no[min_lon, min_lat, max_lon, max_lat]. Exactly one of bbox and polygon.
boundaryCoverageBoundarynoWhich 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_kmnumbernoTarget 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_loopsbooleannoMake 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_snumbernoTarget 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_tolerancenumbernoHow 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.
costingCoverageCostingnoauto (default) or truck.
excludeCoverageExcludeno
include_privatebooleannoDrive 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_mnumbernoWith 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.
optimiseCoverageObjectivenoWhat to minimise: distance (default), time or balanced.
polygonobjectnoA 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.
requiredCoverageRequiredno
return_to_startbooleannoEnd 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_classesRoadClassFilterno
startCoverageStartno
time_factornumbernoMultiplies 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_penaltiesTurnPenaltiesnoTurn penalties.
webhook_urlstringnoJob lane: where to POST the signed completion notice.

Example: From website/public/docs/api-reference.md:3275

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

202Accepted and queued. Poll result_url, or wait for the signed webhook; the job's result is a CoverageResponse
FieldTypeRequiredDescription
idstringyesThe job id to poll.
kindstringyesoptimise, replan, matrix or coverage.
result_urlstringyesWhere to fetch it. The same URL the webhook will carry.
statusstringyesAlways queued, the worker has not looked at it yet.
units_chargedintegeryesQuota 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

json
{
  "id": "string",
  "kind": "string",
  "result_url": "string",
  "status": "string",
  "units_charged": 0
}
400Invalid area or options, or an unusable webhook_url

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

409A webhook_url was given but the key has no webhook signing secret

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

422coverage-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_env

application/problem+json · Problem

429Quota, rate limit, or too many jobs already queued or running. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

501Coverage planning is not enabled on this deployment (no readable routing graph extract at SN_GRAPH_TILES_TAR)

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 Optimisation and jobs

Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_coverage_job