Skip to content
Documentation menu
docs / api / post-v1-jobs-matrix
Matrix

POST/v1/jobs/matrix

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

bash
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

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

202Accepted and queued. Poll result_url, or wait for the signed webhook
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 matrix request, 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

422More than SN_MATRIX_MAX_ELEMENTS_ASYNC elements, or a matrix spanning further than the engine's max_matrix_distance

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

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 Matrix

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