Reusable resources
Upload a fleet, depot or plan once and reference it by id.
platform.resources
Stable
free
How to call it
REST
POST
/v1/plan/matrix
DELETE
/v1/plan/matrix/{matrixId}
POST
/v1/plan/matrix/{matrixId}/points
GraphQL
mutation
openPlanMatrixOpen
mutation
openPlanMatrixClose
mutation
openPlanMatrixPoints
MCP
open_plan_matrix_close
Close a distance snapshot opened with open_plan_matrix_open once the plan is no longer edited. `closed` is false when it was already gone. Free; needs any plan capability.
open_plan_matrix_open
Open a distance snapshot for editing one plan, for a region (NA default) and a vehicle profile (car default). Pass its id as `matrix` to open_plan_recost, open_plan_validate, open_plan_resequence, open_plan_move, open_plan_remove, open_plan_insert, open_plan_refine and open_plan_what_if: road legs measured once are then read from it, and the searches rank their candidates on its road matrix; every number answered is still measured on the road. It is removed after an hour without use and after eight hours at most. Free; needs any plan capability.
open_plan_matrix_points
Name new points of a distance snapshot opened with open_plan_matrix_open (a stop dropped on the map, an address picked to insert): their road legs are measured into it at once, so the next open_plan_insert or open_plan_move finds them held. Answers at once with `queued`; with `wait_ms` (at most 1000) it waits until the legs are held and says so in `ready`. Entries that are not a coordinate are left out; at most 50 points a call. Free; needs any plan capability.
Request schema
Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.
POST /v1/plan/matrix
{
"type": "object",
"properties": {
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Required when points is present."
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Required when points is present."
}
}
}
},
"profile": {
"type": [
"string",
"null"
],
"enum": [
"car",
"van",
"truck",
"bike",
"foot",
"motorcycle"
]
},
"region": {
"type": [
"string",
"null"
],
"enum": [
"NA",
"EU",
"AU",
"ASIA",
"na",
"eu",
"au",
"asia"
]
}
},
"additionalProperties": false
}Request example
{
"region": "NA",
"profile": "car",
"points": [
{
"lat": 45.5017,
"lng": -73.5673
},
{
"lat": 45.5088,
"lng": -73.554
},
{
"lat": 45.4972,
"lng": -73.5786
}
]
}POST /v1/plan/matrix/{matrixId}/points
{
"type": "object",
"properties": {
"points": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"lat",
"lng"
]
}
},
"wait_ms": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false,
"required": [
"points"
]
}Request example
{
"points": [
{
"lat": 45.5231,
"lng": -73.5817
}
],
"wait_ms": 1000
}Response
What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.
POST /v1/plan/matrix
Response schema
{
"description": "A distance snapshot for editing one plan. Name it as `matrix` in plan calls of the same region and profile. Free.",
"data": {
"type": "object",
"properties": {
"matrix": {
"type": "string",
"description": "The snapshot id, `<node>.<random>`: send it as `matrix`."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it is removed if it is not used again: an hour after its last use, and never later than eight hours after it was opened (UTC)."
},
"node": {
"type": "string",
"description": "The server that holds the snapshot."
}
},
"required": [
"matrix",
"expires_at",
"node"
]
},
"meta": {
"type": "object",
"properties": {
"region": {
"type": "string"
},
"profile": {
"type": "string"
}
}
}
}Response example
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "platform.resources",
"billing": {
"unit": "free",
"quantity": 0,
"counted": false
},
"data": {
"matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910",
"expires_at": "2026-10-23T14:30:00Z",
"node": "tile2"
},
"meta": {
"region": "NA",
"profile": "car"
}
}DELETE /v1/plan/matrix/{matrixId}
Response schema
{
"description": "The snapshot is removed at once. `closed` is false when it was already gone (expired, removed or never opened by this account). Free.",
"data": {
"type": "object",
"properties": {
"matrix": {
"type": "string"
},
"closed": {
"type": "boolean",
"description": "True when this call removed it."
}
},
"required": [
"matrix",
"closed"
]
}
}Response example
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "platform.resources",
"billing": {
"unit": "free",
"quantity": 0,
"counted": false
},
"data": {
"matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910",
"closed": true
}
}POST /v1/plan/matrix/{matrixId}/points
Response schema
{
"description": "The points are queued on the fast lane and their road legs measured into the snapshot. Without `wait_ms` the answer is sent at once; with it, once the legs are held or the time ran out. Refused with RESOURCE_EXPIRED (410) when the snapshot is unknown, expired or another account's. Free.",
"data": {
"type": "object",
"properties": {
"matrix": {
"type": "string"
},
"queued": {
"type": "integer",
"description": "Points queued on the fast lane by this call: new points, and points still waiting in the background. A point already held, already on the fast lane, named twice or not a coordinate is not counted."
},
"ready": {
"type": "boolean",
"description": "True when the legs of every point named were held in the snapshot when the answer was sent. Without `wait_ms` usually false for a new point."
}
},
"required": [
"matrix",
"queued",
"ready"
]
}
}Response example
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "platform.resources",
"billing": {
"unit": "free",
"quantity": 0,
"counted": false
},
"data": {
"matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910",
"queued": 1,
"ready": true
}
}What it costs
Never billed, and never disable-able.
Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.
Errors it can return
| Status | Code | Description |
|---|---|---|
| 401 | SESSION_EXPIRED |
The session token is invalid or has expired. |
| 401 | TOKEN_INVALID |
Unknown or revoked API token. |
| 401 | TOKEN_MISSING |
No API token. Send Authorization: Bearer <your token>. |
| 403 | CAPABILITY_NOT_ENABLED |
This capability is not enabled for your account. See :doc to enable it. |
| 403 | CAPABILITY_NOT_GRANTED_TO_KEY |
Your account has this capability, but this API key was not granted it. |
| 403 | OPEN_API_DISABLED |
Open Platform access is not enabled for this account. |
| 404 | JOB_NOT_FOUND |
No such job, or it belongs to another account. |
| 409 | JOB_NOT_FINISHED |
The job has not finished yet. Poll the job, or wait for the callback. |
| 410 | JOB_RESULT_EXPIRED |
The result has expired and is no longer available. Submit the request again. |
| 422 | UNSUPPORTED_REGION |
That routing region is not available. Use NA, EU, AU or ASIA. |
| 422 | VALIDATION_FAILED |
The request failed validation. See details. |
| 429 | RATE_LIMITED |
Too many requests. Please retry after the indicated delay. |
| 429 | SNAPSHOT_LIMIT_REACHED |
A distance snapshot cannot be opened: a limit is reached (see `limit`). Close a snapshot no longer in use, or call without `matrix`. |
| 500 | INTERNAL_ERROR |
An unexpected error occurred. Quote the request_id when contacting support. |
| 502 | ENGINE_UNAVAILABLE |
The routing engine is temporarily unreachable. Please retry. |