Documentation menu
POST/v1/jobs/matrix
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 | As POST /matrix: 1 call per started block of 25 elements, at the asynchronous element cap. 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 matrix to the asynchronous lane.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: As POST /matrix: 1 call per started block of 25 elements, at the asynchronous element cap.
Call it
curl -fsS -X POST "https://api.mapmap.ai/v1/jobs/matrix" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d '{"costing":"truck","costing_options":{"truck":{"height":4,"weight":40}},"sources":[{"lat":51.5074,"lon":-0.1278}],"targets":[{"lat":52.4862,"lon":-1.8904},{"lat":53.4808,"lon":-2.2426}]}'Request body
application/json
Exactly the POST /matrix body: sources, targets, costing, optional units, costing_options, exclude_polygons, exclude_locations and snap_retry (the result carries the same snap_retry block when the widened-snap retry filled a cell), plus an optional webhook_url. The element cap here is SN_MATRIX_MAX_ELEMENTS_ASYNC (40,000 by default), four times the synchronous 10,000
Example: From website/public/docs/analysis.md:255
{
"costing": "truck",
"costing_options": {
"truck": {
"height": 4,
"weight": 40
}
},
"sources": [
{
"lat": 51.5074,
"lon": -0.1278
}
],
"targets": [
{
"lat": 52.4862,
"lon": -1.8904
},
{
"lat": 53.4808,
"lon": -2.2426
}
]
}Responses
result_url, or wait for the signed webhook| 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
SN_MATRIX_MAX_ELEMENTS_ASYNC elements, or a matrix spanning further than the engine's max_matrix_distanceapplication/problem+json · Problem
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Also under Matrix
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_matrix_job