Skip to content
Log inGet an API key
Documentation menu
docs / api / post-v1-jobs-coverage
routing

POST/v1/jobs/coverage

API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….

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 @request.json

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, start, return_to_start, plus an optional webhook_url. Billed per started square kilometre of area at submission, refunded in full if the job fails. The result, once the job succeeds, is a CoverageResponse

FieldTypeRequiredDescription
bboxnumber[]no[min_lon, min_lat, max_lon, max_lat]. Exactly one of bbox and polygon.
chunk_kmnumbernoTarget outing length, km (default 15, 1 to 150).
costingCoverageCostingnoauto (default) or truck.
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.
optimiseCoverageObjectivenoWhat to minimise: distance (default), time or balanced.
polygonobjectnoA GeoJSON Polygon or MultiPolygon geometry (longitude, latitude).
return_to_startbooleannoEnd where the drive started (default true). With false the final connecting drive back to the start is left off.
road_classesRoadClassFilterno
startCoveragePointno
turn_penaltiesTurnPenaltiesnoTurn penalties.
webhook_urlstringnoJob lane: where to POST the signed completion notice.

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.
400Invalid area or options, or an unusable webhook_url
401Missing or invalid API key
409A webhook_url was given but the key has no webhook signing secret
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
429Quota, rate limit, or too many jobs already queued or running
501Coverage planning is not enabled on this deployment (no readable routing graph extract at SN_GRAPH_TILES_TAR)

Error bodies follow the shared problem model documented on API conventions.

Also under routing

POST /centroidPOST /isochronePOST /locatePOST /matrixPOST /optimisePOST /optimise/replanPOST /routePOST /route/alongPOST /route/progressPOST /route/reportGET /route/v1/{profile}/{coordinates}POST /trace_attributesPOST /trace_routePOST /v1/cameras/alongPOST /v1/charging/alongPOST /v1/clusterPOST /v1/errands/planPOST /v1/ev/planPOST /v1/fuel/alongPOST /v1/incidents/alongPOST /v1/jobs/matrixPOST /v1/jobs/optimisePOST /v1/jobs/replanPOST /v1/route/heritagePOST /v1/route/observationsPOST /v1/weather/alongGET /v1/zones

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