POST/v1/jobs/territory

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/territory" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Request body

application/json · TerritoryJobRequest

Exactly one of a bbox ([west, south, east, north]), a GeoJSON polygon and a boundary_id (from GET /v1/boundaries; its stored polygon is the area, limited and priced exactly as that polygon), optional layers (any of valhalla-tiles, pmtiles, geocode-index, style; default all), optional source territory and webhook_url. The area is cut out of ONE published country package, at most SN_REGION_MAX_AREA_KM2 (2,500 km² by default) and SN_REGION_MAX_MIB installed (2,048 MiB by default). The result is a signed territory (region-… id, versioned by the source package version) a device installs from index_url like any other; its layer downloads count against the download allowance exactly as a country download does. A repeat request for an area already cut from the current source version costs nothing

Field	Type	Required	Description
bbox	number[]	no	`[west, south, east, north]` in WGS84 degrees. Exactly one of `bbox`, `polygon` and `boundary_id`.
boundary_id	string	no	An administrative boundary from `GET /v1/boundaries`, e.g. `osm-r51827`: its stored polygon (the one `GET /v1/boundaries/{id}` returns) is the area, limited and priced exactly as that polygon would be.
layers	string[]	no	Layer kinds to carry: any of `valhalla-tiles`, `pmtiles`, `geocode-index`, `style` (default: all four). `style` needs `pmtiles`.
polygon	object	no	A GeoJSON `Polygon` or `MultiPolygon` (or a `Feature` wrapping one).
source	string	no	Territory to cut from, e.g. `uk`. Default: the smallest published territory whose bounding box contains the area.
webhook_url	string	no	Signed completion notification target (the ordinary job lane field).

Responses

202Accepted and queued (or already cut, in which case the submission is not billed and the job finishes at once). Poll result_url

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.

400Malformed area, boundary id or layer list, more than one of bbox, polygon and boundary_id, or an unusable webhook_url

401Missing or invalid API key

403Provisional or email-less key: territory downloads require a verified account

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

422region-area-too-large (over SN_REGION_MAX_AREA_KM2, with limit and value), region-crosses-territories (not inside one published territory; the detail names the territories it touches), region-not-covered, region-unknown-source, region-unknown-boundary (no such boundary_id here) or region-no-data

429Quota, rate limit, or too many jobs already queued or running

501A boundary_id on a deployment without boundaries data (SN_BOUNDARIES_DIR unset)

503Custom regions are not enabled on this deployment

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

Also under territories

GET /territories GET /territories/{id}/{version}/layers/{addr}/{file}GET /territories/{id}/{version}/manifest GET /territories/{id}/{version}/manifest.sig GET /territories/index.sig GET /v1/territories/{id}/index.json GET /v1/territories/{id}/index.json.sig

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