{ "openapi": "3.1.0", "info": { "title": "Superroute Open Platform", "description": "Stateless logistics computation. Nothing you send is stored: there are no orders, no shipments and no history here. Every request carries an HMAC signature or a short-lived session token, and every billable response reports what it cost.", "version": "1.0.0" }, "servers": [ { "url": "https://open.superroute.ca" } ], "tags": [ { "name": "routing", "description": "Route optimization" }, { "name": "plan", "description": "Dispatch" }, { "name": "slots", "description": "Delivery slots" }, { "name": "geo", "description": "Geocoding" }, { "name": "matrix", "description": "Distance matrix" }, { "name": "directions", "description": "Directions" }, { "name": "isochrone", "description": "Reach areas" }, { "name": "trace", "description": "Map matching" }, { "name": "weight", "description": "Chargeable weight" }, { "name": "label", "description": "Barcodes" }, { "name": "document", "description": "Document checks" }, { "name": "eta", "description": "Arrival estimates" }, { "name": "map", "description": "Maps" }, { "name": "packing", "description": "Carton selection" }, { "name": "loading", "description": "Load planning" }, { "name": "picking", "description": "Pick batching" }, { "name": "territory", "description": "Territory design" }, { "name": "network", "description": "Network scenarios" }, { "name": "platform", "description": "Platform" } ], "security": [ { "openToken": [] } ], "components": { "securitySchemes": { "openToken": { "type": "http", "scheme": "bearer", "description": "Your API token, sent as `Authorization: Bearer `. That is the whole of authentication — the same shape as the rest of the Superroute API. The token is the secret shown once when the key was created. A short-lived session token from POST /v1/auth/session is accepted in the same header, for MCP clients and the docs console. The plan endpoints also accept a plan editor token from POST /v1/plan/token and a map key with plan editing switched on, for a plan editor in a browser or an app." } }, "schemas": { "OpenError": { "type": "object", "properties": { "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string", "description": "Always localized. Never branch on this." }, "status": { "type": "integer" }, "capability": { "type": "string" }, "retry_after_seconds": { "type": [ "integer", "null" ] }, "details": { "type": "array", "items": { "type": "object" } }, "doc_url": { "type": "string" } }, "required": [ "code", "message", "status" ] } }, "required": [ "request_id", "error" ] } } }, "paths": { "/v1/auth/session": { "delete": { "operationId": "authSessionRevokeDelete", "tags": [ "platform" ], "summary": "Revoke a session token", "description": "Invalidates a session token before its expiry. Revoking the key invalidates all sessions issued from it; this endpoint withdraws a single session.\n\nExchange an API token for a short-lived session token.", "x-superroute-capability": "platform.auth", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.auth", "responses": { "200": { "description": "The session token sent in `Authorization` is revoked at once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean", "description": "True once the token is revoked." } }, "required": [ "revoked" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "revoked": true } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } } }, "post": { "operationId": "authSession", "tags": [ "platform" ], "summary": "Get a session token", "description": "Exchanges an API token for a short-lived bearer token, for clients that should not hold the key secret itself: MCP clients and the documentation console. A session may only narrow the scopes held by the key.\n\nExchange an API token for a short-lived session token.", "x-superroute-capability": "platform.auth", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.auth", "responses": { "200": { "description": "A short-lived session token. Send it as `Authorization: Bearer ` until `expires_at`. It can do only what the key that minted it can do, narrowed to `scopes` when given.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The session token, `sr_sess_...`. Shown once." }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds until it expires." }, "expires_at": { "type": "string", "description": "ISO 8601 with offset." }, "audience": { "type": "string", "enum": [ "mcp", "console" ], "description": "Who the token is for, as requested." }, "scopes": { "type": [ "array", "null" ], "description": "The capabilities it is limited to; null when it carries everything the key may call.", "items": { "type": "string" } } }, "required": [ "access_token", "token_type", "expires_in" ] }, "meta": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The API key that minted the session." } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "access_token": "sr_sess_01k8zq3m5n7p9r1t3v5x7z9b2d.Xq7bN2kLm9Pz4Rt8Wv1Yc5Hd3Jf6Gs0Aa2Ee4Uu", "token_type": "Bearer", "expires_in": 900, "expires_at": "2026-10-23T09:42:39-04:00", "audience": "mcp", "scopes": null }, "meta": { "key_id": "sr_live_7Hq2LmX9pR4sT1vW8yZ3nB6c" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": [ "string", "null" ], "enum": [ "mcp", "console" ] }, "capabilities": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "ttl_seconds": { "type": [ "integer", "null" ], "minimum": 60 } }, "additionalProperties": false }, "example": { "audience": "mcp", "ttl_seconds": 900 } } } } } }, "/v1/capabilities": { "get": { "operationId": "capabilitiesIndex", "tags": [ "platform" ], "summary": "List capabilities", "description": "Reports which capabilities the presented credential may call, the unit each is billed in, and its price. Capabilities the account has not subscribed to are included, so that \"not enabled\" can be distinguished from \"not available\".\n\nList what this key can call, at what price, against which quota.", "x-superroute-capability": "platform.capabilities", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.capabilities", "responses": { "200": { "description": "Every capability, whether this key may call it, what it is billed in and its limits. The example is shortened to two capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The key that made the call." }, "grant_mode": { "type": "string", "enum": [ "all", "subset" ], "description": "`all`: the key inherits every capability the client holds; `subset`: it was narrowed when issued." } } }, "platform": { "type": "object", "properties": { "base_url": { "type": "string", "description": "The API host." }, "docs_url": { "type": "string", "description": "The documentation centre." } } }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The capability code. Also the billing SKU, the auth scope and the docs anchor." }, "family": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "ga", "beta", "alpha", "deprecated" ], "description": "Release stage. A beta capability needs a beta entitlement." }, "enabled": { "type": "boolean", "description": "The client subscribes to it." }, "granted": { "type": "boolean", "description": "This key may use it. A key can be narrowed to fewer capabilities than the client holds." }, "callable": { "type": "boolean", "description": "A call would be accepted now: enabled, granted and inside its limits." }, "reason": { "type": [ "string", "null" ], "description": "Why `callable` is false, as an error code such as CAPABILITY_NOT_ENABLED; null when callable." }, "billing": { "type": "object", "description": "A free capability carries `unit` only.", "properties": { "unit": { "type": "string", "description": "What is counted (node, point, point_1k, element_1k, call, job, free)." }, "per": { "type": "integer", "description": "How many of the unit one billed quantity stands for: 1000 for `point_1k` and `element_1k`, otherwise 1." }, "included_units": { "type": "integer", "description": "Units included before overage starts." }, "unit_price": { "type": [ "number", "null" ], "description": "Price per billed quantity; null when not priced." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217." }, "overage_policy": { "type": [ "string", "null" ], "enum": [ "block", "bill", "require_confirm", null ], "description": "`block` refuses calls past the limits; `bill` bills them as overage; `require_confirm` refuses them until overage is confirmed." } } }, "limits": { "type": "object", "description": "Null means no limit of that kind.", "properties": { "daily_calls": { "type": [ "integer", "null" ] }, "monthly_calls": { "type": [ "integer", "null" ] }, "daily_units": { "type": [ "integer", "null" ] }, "monthly_units": { "type": [ "integer", "null" ] }, "requests_per_minute": { "type": [ "integer", "null" ] }, "concurrent": { "type": [ "integer", "null" ] } } }, "docs_url": { "type": "string", "description": "This capability's documentation page." } } } }, "totals": { "type": "object", "properties": { "capabilities": { "type": "integer", "description": "Capabilities in the catalog." }, "enabled": { "type": "integer", "description": "Capabilities the client subscribes to." }, "granted": { "type": "integer", "description": "Capabilities this key may use." } } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "key": { "key_id": "sr_live_7Hq2LmX9pR4sT1vW8yZ3nB6c", "grant_mode": "all" }, "platform": { "base_url": "https://open.superroute.ca", "docs_url": "https://open.superroute.ca/developer" }, "capabilities": [ { "code": "routing.optimize", "family": "routing", "title": "Route optimization", "description": "Plan routes across a fleet from jobs, vehicles and constraints you supply.", "status": "ga", "enabled": true, "granted": true, "callable": true, "reason": null, "billing": { "unit": "node", "per": 1, "included_units": 0, "unit_price": null, "currency": "CAD", "overage_policy": "block" }, "limits": { "daily_calls": null, "monthly_calls": null, "daily_units": null, "monthly_units": null, "requests_per_minute": 300, "concurrent": null }, "docs_url": "/developer/capabilities/routing.optimize" }, { "code": "geo.forward", "family": "geo", "title": "Forward geocoding", "description": "Turn an address into coordinates through a per-country provider chain.", "status": "ga", "enabled": true, "granted": true, "callable": true, "reason": null, "billing": { "unit": "point", "per": 1, "included_units": 0, "unit_price": null, "currency": "CAD", "overage_policy": "block" }, "limits": { "daily_calls": null, "monthly_calls": null, "daily_units": null, "monthly_units": null, "requests_per_minute": 300, "concurrent": null }, "docs_url": "/developer/capabilities/geo.forward" } ], "totals": { "capabilities": 20, "enabled": 20, "granted": 20 } } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } } } }, "/v1/capabilities/{code}": { "get": { "operationId": "capabilitiesShow", "tags": [ "platform" ], "summary": "Get one capability", "description": "The same report for a single capability, including the reason for refusal where one applies.\n\nList what this key can call, at what price, against which quota.", "x-superroute-capability": "platform.capabilities", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.capabilities", "responses": { "200": { "description": "One capability, in the same shape as an entry of GET /v1/capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "code": { "type": "string", "description": "The capability code. Also the billing SKU, the auth scope and the docs anchor." }, "family": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "ga", "beta", "alpha", "deprecated" ], "description": "Release stage. A beta capability needs a beta entitlement." }, "enabled": { "type": "boolean", "description": "The client subscribes to it." }, "granted": { "type": "boolean", "description": "This key may use it. A key can be narrowed to fewer capabilities than the client holds." }, "callable": { "type": "boolean", "description": "A call would be accepted now: enabled, granted and inside its limits." }, "reason": { "type": [ "string", "null" ], "description": "Why `callable` is false, as an error code such as CAPABILITY_NOT_ENABLED; null when callable." }, "billing": { "type": "object", "description": "A free capability carries `unit` only.", "properties": { "unit": { "type": "string", "description": "What is counted (node, point, point_1k, element_1k, call, job, free)." }, "per": { "type": "integer", "description": "How many of the unit one billed quantity stands for: 1000 for `point_1k` and `element_1k`, otherwise 1." }, "included_units": { "type": "integer", "description": "Units included before overage starts." }, "unit_price": { "type": [ "number", "null" ], "description": "Price per billed quantity; null when not priced." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217." }, "overage_policy": { "type": [ "string", "null" ], "enum": [ "block", "bill", "require_confirm", null ], "description": "`block` refuses calls past the limits; `bill` bills them as overage; `require_confirm` refuses them until overage is confirmed." } } }, "limits": { "type": "object", "description": "Null means no limit of that kind.", "properties": { "daily_calls": { "type": [ "integer", "null" ] }, "monthly_calls": { "type": [ "integer", "null" ] }, "daily_units": { "type": [ "integer", "null" ] }, "monthly_units": { "type": [ "integer", "null" ] }, "requests_per_minute": { "type": [ "integer", "null" ] }, "concurrent": { "type": [ "integer", "null" ] } } }, "docs_url": { "type": "string", "description": "This capability's documentation page." } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "code": "routing.optimize", "family": "routing", "title": "Route optimization", "description": "Plan routes across a fleet from jobs, vehicles and constraints you supply.", "status": "ga", "enabled": true, "granted": true, "callable": true, "reason": null, "billing": { "unit": "node", "per": 1, "included_units": 0, "unit_price": null, "currency": "CAD", "overage_policy": "block" }, "limits": { "daily_calls": null, "monthly_calls": null, "daily_units": null, "monthly_units": null, "requests_per_minute": 300, "concurrent": null }, "docs_url": "/developer/capabilities/routing.optimize" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/directions": { "post": { "operationId": "directionsCompute", "tags": [ "directions" ], "summary": "Compute directions", "description": "Computes road distance, duration and geometry along the supplied waypoints in the order given. It renders a route that has already been determined; routing.optimize determines one.\n\nRoad geometry, distance and duration between waypoints.", "x-superroute-capability": "directions.compute", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/directions.compute", "responses": { "200": { "description": "Distance, driving time and geometry of every leg between consecutive waypoints, in the order given. A leg that cannot be routed is reported with `reachable: false` and nulls; the other legs are still answered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "directions.compute" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "legs": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "Waypoint id the leg starts at." }, "to": { "type": "string", "description": "Waypoint id it ends at." }, "reachable": { "type": "boolean" }, "distance_meters": { "type": [ "integer", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5). Null when `options.geometry` is false or the leg is unreachable." } } } }, "totals": { "type": "object", "properties": { "distance_meters": { "type": "integer", "description": "Sum of the reachable legs." }, "duration_seconds": { "type": "integer", "description": "Sum of the reachable legs." }, "legs": { "type": "integer" }, "unreachable_legs": { "type": "integer" } } } } }, "meta": { "type": "object", "properties": { "region": { "type": "string" }, "profile": { "type": "string" }, "geometry": { "type": "boolean" }, "geometry_format": { "type": [ "string", "null" ] }, "mode": { "type": "string" } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "directions.compute", "billing": { "unit": "call", "quantity": 1, "counted": true, "breakdown": { "waypoints": 3, "legs": 2 } }, "data": { "legs": [ { "from": "depot", "to": "order-1001", "reachable": true, "distance_meters": 1840, "duration_seconds": 245, "geometry": "y`vtGjr_`MJUNYL[h@gAHOFQBIHOc@g@MOa@]s@q@EGEEk@g@k@k@CCMMDO@EDMBMBOBQBO@KBM?G@OBQ?G@MBQ@MBMBMBOBOBMFSDSBGBIBGHOvAkE@EHQGEECa@_@ECMKKIwAiA_CmBq@m@ECIIOKoAcAs@i@KIIIOMgA{@QMCCGGGE_@[m@g@a@[kA_ACCECKGKGWSQOwAkAGEGEu@o@CCMIMKGEYSeAq@OKa@WGG[Sy@g@w@k@s@e@GEGE??YQgAu@c@[QKc@YMKKG@EBK@EVo@@EDKDM@Cb@cAFOBIt@oBBEDUJFBBFDx@l@??" }, { "from": "order-1001", "to": "order-1002", "reachable": true, "distance_meters": 3108, "duration_seconds": 390, "geometry": "elwtGl}|_Mx@n@BBFD\\ZDDDBz@l@`@\\~BdB~AjAf@\\DDBBLDEPEJe@zAADENGNCFW|@Y|@CFA@ELCHGRq@jBABu@tBCHAFEJGNADg@vAKXq@lBABEHAHgA|C_@fASf@ADGPO^JHbAt@`CrBBBJHLJhCzBJL~BvBFDJJHF~@r@zAdABBHFLHdDfCBBFFFDJHvDlCRJDBRHXPx@f@D@HHJFVV|@x@BBLJTRJJTTlBdBLL`@\\h@f@ZXNLr@p@BBB@JJJHv@r@j@h@DDNLJJp@l@HHj@j@DBLLRRfB`BBBJJHFv@r@x@t@B@HHJJz@v@RRl@j@BBHHJHhAfAj@j@BBNLHHLLVT|@z@HFIPw@tBmAbDy@vBe@pACDIPIRg@pAO\\{A`ECDAFEJHHp@p@??" } ], "totals": { "distance_meters": 4948, "duration_seconds": 635, "legs": 2, "unreachable_legs": 0 } }, "meta": { "region": "NA", "profile": "car", "geometry": true, "geometry_format": "polyline", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ] } } }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "waypoints": { "type": "array", "minItems": 2, "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] } } }, "additionalProperties": false, "required": [ "waypoints" ] }, "example": { "waypoints": [ { "id": "depot", "lat": 45.5017, "lng": -73.5673 }, { "id": "order-1001", "lat": 45.5088, "lng": -73.554 }, { "id": "order-1002", "lat": 45.4972, "lng": -73.5786 } ], "options": { "geometry": true } } } } } } }, "/v1/document/verify": { "post": { "operationId": "documentVerify", "tags": [ "document" ], "summary": "Verify a document", "description": "Reads the PDF in `pdf_base64` and returns its `status`: `authentic` (issued by Superroute and unchanged), `tampered` (issued by Superroute and changed since), `unknown` (not issued by Superroute, or its mark was removed) or `not_pdf`; with `issued_by_us`, `intact`, the file's SHA-256 and size. Who issued the document and for which record is never told. The request body may be at most 1 MB, so the PDF at most about 750 KB. Nothing is stored. Billed one call.\n\nCheck whether a PDF was issued by Superroute and is unchanged since.", "x-superroute-capability": "document.verify", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/document.verify", "responses": { "200": { "description": "The document's verdict. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "document.verify" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "authentic", "tampered", "unknown", "not_pdf" ], "description": "`authentic`: issued by Superroute and unchanged; `tampered`: issued by Superroute and changed since; `unknown`: no Superroute mark; `not_pdf`: not a PDF." }, "issued_by_us": { "type": "boolean", "description": "Whether Superroute issued it (authentic or tampered)." }, "intact": { "type": "boolean", "description": "Whether it is unchanged since (authentic)." }, "sha256": { "type": "string", "description": "The SHA-256 of the file sent." }, "byte_size": { "type": "integer", "description": "The size of the file sent." } }, "required": [ "status", "issued_by_us", "intact" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "document.verify", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "status": "authentic", "issued_by_us": true, "intact": true, "sha256": "6c709056353a1b5376791c8dd949243dcf9e7327eae864d4fe476ff435e40d76", "byte_size": 1736 }, "meta": [] } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "413": { "description": "The request body is too large. Upload large payloads as a reusable resource instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body is too large. Upload large payloads as a reusable resource instead.", "status": 413, "doc_url": "/developer/errors/REQUEST_TOO_LARGE" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pdf_base64": { "type": "string" } }, "additionalProperties": false, "required": [ "pdf_base64" ] }, "example": { "pdf_base64": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZwovT3V0bGluZXMgMiAwIFIKL1BhZ2VzIDMgMCBSID4+CmVuZG9iagoyIDAgb2JqCjw8IC9UeXBlIC9PdXRsaW5lcyAvQ291bnQgMCA+PgplbmRvYmoKMyAwIG9iago8PCAvVHlwZSAvUGFnZXMKL0tpZHMgWzYgMCBSCl0KL0NvdW50IDEKL1Jlc291cmNlcyA8PAovUHJvY1NldCA0IDAgUgovRm9udCA8PCAKL0YxIDggMCBSCi9GMiA5IDAgUgo+Pgo+PgovTWVkaWFCb3ggWzAuMDAwIDAuMDAwIDU5NS4yODAgODQxLjg5MF0KID4+CmVuZG9iago0IDAgb2JqClsvUERGIC9UZXh0IF0KZW5kb2JqCjUgMCBvYmoKPDwKL1Byb2R1Y2VyICj+/wBkAG8AbQBwAGQAZgAgADMALgAxAC4ANgAgACsAIABDAFAARABGKQovQ3JlYXRpb25EYXRlIChEOjIwMjYxMDIzMTY1NDU4LTA0JzAwJykKL01vZERhdGUgKEQ6MjAyNjEwMjMxNjU0NTgtMDQnMDAnKQo+PgplbmRvYmoKNiAwIG9iago8PCAvVHlwZSAvUGFnZQovTWVkaWFCb3ggWzAuMDAwIDAuMDAwIDU5NS4yODAgODQxLjg5MF0KL1BhcmVudCAzIDAgUgovQ29udGVudHMgNyAwIFIKPj4KZW5kb2JqCjcgMCBvYmoKPDwgL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxMDQgPj4Kc3RyZWFtCnic4zLQMzAwUEAmi9K5nEIUjE30DAzNFMzNLPSMTQ0VQlIU9N0MFYyAogohaQoK0RoBicnZmXnpCsU5mQWasQohXgquIcgagbSZhSVEo5GCoRFco39RSmqRQrC/rqGBgSFMJwAMfh99CmVuZHN0cmVhbQplbmRvYmoKOCAwIG9iago8PCAvVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTEKL05hbWUgL0YxCi9CYXNlRm9udCAvSGVsdmV0aWNhLUJvbGQKL0VuY29kaW5nIC9XaW5BbnNpRW5jb2RpbmcKPj4KZW5kb2JqCjkgMCBvYmoKPDwgL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9OYW1lIC9GMgovQmFzZUZvbnQgL0hlbHZldGljYQovRW5jb2RpbmcgL1dpbkFuc2lFbmNvZGluZwo+PgplbmRvYmoKeHJlZgowIDEwCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDc0IDAwMDAwIG4gCjAwMDAwMDAxMjAgMDAwMDAgbiAKMDAwMDAwMDI4NCAwMDAwMCBuIAowMDAwMDAwMzEzIDAwMDAwIG4gCjAwMDAwMDA0NjIgMDAwMDAgbiAKMDAwMDAwMDU2NSAwMDAwMCBuIAowMDAwMDAwNzQxIDAwMDAwIG4gCjAwMDAwMDA4NTMgMDAwMDAgbiAKdHJhaWxlcgo8PAovU2l6ZSAxMAovUm9vdCAxIDAgUgovSW5mbyA1IDAgUgovSURbPDNjZTEyNGMwNjIzMjg1MDYxZDYxMzAxMjZhZmJjZmU4PjwzY2UxMjRjMDYyMzI4NTA2MWQ2MTMwMTI2YWZiY2ZlOD5dCj4+CnN0YXJ0eHJlZgo5NjAKJSVFT0YKMTAgMCBvYmoKPDwgL0ZpbHRlciAvRmxhdGVEZWNvZGUgL0xlbmd0aCAxNjkgPj4Kc3RyZWFtCnicAZ4AYf8A4x/3nkBmRqmXV0RDMMBRFe/SEzSdOBG9uhuZ/s5UtPf0AVy6btZQhdivf2xZDn8ZG6/7JUWH10MgDgpD7tG6T8IRsm9CbWX9+IZUHlaWr2qHhiwvOrwmtizWU+8F4CIaIKFqoNJw0WB9z9ptHaaWc/DeEdaaTWTyBJunkbNAai8jofoq5K4XRvpJ371P2xkEkWiyYabenbwK9ruywG3WTiIKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjEwIDEKMDAwMDAwMTMxMSAwMDAwMCBuIAp0cmFpbGVyCjw8IC9TaXplIDExIC9Sb290IDEgMCBSIC9JbmZvIDUgMCBSIC9JRCBbPDNjZTEyNGMwNjIzMjg1MDYxZDYxMzAxMjZhZmJjZmU4PjwzY2UxMjRjMDYyMzI4NTA2MWQ2MTMwMTI2YWZiY2ZlOD5dIC9QcmV2IDk2MCA+PgpzdGFydHhyZWYKMTU1MwolJUVPRgo=" } } } } } }, "/v1/eta": { "post": { "operationId": "etaEstimate", "tags": [ "eta" ], "summary": "Estimate arrival times", "description": "Projects the remaining arrival times of a route from the most recent completed event. This is a projection of the submitted plan, not a traffic forecast: no pace correction is applied and no traffic service is consulted.\n\nRecompute arrival times along a route from progress so far.", "x-superroute-capability": "eta.estimate", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/eta.estimate", "responses": { "200": { "description": "Arrival times for the stops not yet completed, projected from the last observation (the latest completed stop, else `departed_at`, else `now`). A projection of the caller's plan, not a traffic forecast. Times are in UTC.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "eta.estimate" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in_progress", "not_started", "complete" ], "description": "`not_started`: no completed stop and no departure, so nothing is projected; `complete`: every stop is done." }, "anchor": { "type": [ "object", "null" ], "description": "Null unless `status` is in_progress.", "properties": { "at": { "type": "string", "description": "The observation projected from, UTC." }, "at_epoch": { "type": "integer" }, "source": { "type": "string", "enum": [ "completion", "departure", "now" ], "description": "What the anchor is: the latest completed stop, `departed_at`, or `now`." }, "stop_id": { "type": [ "string", "null" ], "description": "The completed stop anchored on." }, "age_seconds": { "type": "integer", "description": "How old the observation is at `now`. Past 45 minutes an ANCHOR_STALE warning is added." } } }, "finish_eta": { "type": [ "string", "null" ], "description": "When the last stop is finished, UTC." }, "finish_eta_epoch": { "type": "integer" }, "remaining": { "type": "object", "description": "What is left of the route.", "properties": { "stops": { "type": "integer" }, "travel_seconds": { "type": "integer" }, "service_seconds": { "type": "integer" } } }, "stops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eta": { "type": "string", "description": "Arrival, UTC." }, "eta_epoch": { "type": "integer" }, "departure_eta": { "type": "string", "description": "Departure after service, UTC." }, "window_status": { "type": [ "string", "null" ], "enum": [ "early", "on_time", "late", null ], "description": "Against the stop's `time_window`; null when it has none." }, "minutes_late": { "type": [ "integer", "null" ], "description": "Minutes past the end of the window; null when not late." } } }, "description": "The next `horizon` stops (default 3). Beyond that a HORIZON_TRUNCATED warning is added; use `finish_eta`." }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "`high` from two or more completed stops, `medium` from one, `low` when the anchor is a departure, `now` or stale." } } }, "meta": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "anchored_plan_projection" ] }, "pace_correction": { "type": "boolean", "description": "Always false: no pace correction is applied." }, "traffic_aware": { "type": "boolean", "description": "Always false: no traffic service is called." }, "stops": { "type": "integer", "description": "Stops sent." }, "mode": { "type": "string" } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "eta.estimate", "billing": { "unit": "call", "quantity": 1, "counted": true, "breakdown": { "stops": 3 } }, "data": { "status": "in_progress", "anchor": { "at": "2026-11-02T14:15:00Z", "at_epoch": 1793628900, "source": "completion", "stop_id": "order-1001", "age_seconds": 300 }, "finish_eta": "2026-11-02T14:45:00Z", "finish_eta_epoch": 1793630700, "remaining": { "stops": 2, "travel_seconds": 1260, "service_seconds": 540 }, "stops": [ { "id": "order-1002", "eta": "2026-11-02T14:27:00Z", "eta_epoch": 1793629620, "departure_eta": "2026-11-02T14:32:00Z", "window_status": "late", "minutes_late": 2 }, { "id": "order-1003", "eta": "2026-11-02T14:41:00Z", "eta_epoch": 1793630460, "departure_eta": "2026-11-02T14:45:00Z", "window_status": null, "minutes_late": null } ], "confidence": "medium" }, "meta": { "model": "anchored_plan_projection", "pace_correction": false, "traffic_aware": false, "stops": 3, "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": [], "horizon": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "now": [], "stops": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "completed_at": [], "id": { "type": [ "string", "null" ], "maxLength": 128 }, "sequence": { "type": [ "integer", "null" ] }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "time_window": { "type": [ "array", "null" ] }, "travel_seconds": { "type": [ "integer", "null" ], "minimum": 0 } } } } }, "additionalProperties": false, "required": [ "stops" ] }, "example": { "departed_at": "2026-11-02T09:00:00-05:00", "now": "2026-11-02T09:20:00-05:00", "stops": [ { "id": "order-1001", "travel_seconds": 600, "service_seconds": 300, "completed_at": "2026-11-02T09:15:00-05:00" }, { "id": "order-1002", "travel_seconds": 720, "service_seconds": 300, "time_window": { "from": "2026-11-02T09:00:00-05:00", "to": "2026-11-02T09:25:00-05:00" } }, { "id": "order-1003", "travel_seconds": 540, "service_seconds": 240 } ] } } } } } }, "/v1/geo/autocomplete": { "post": { "operationId": "geoAutocomplete", "tags": [ "geo" ], "summary": "Suggest addresses", "description": "Returns up to five address suggestions for `input` (at least 3 characters), each with a `place_id`, its full `description` and its `main_text` and `secondary_text`. `countries` (up to five ISO codes) limits the suggestions, `near` with `radius_meters` prefers those around a point, `types` is `address` (default), `geocode` or `establishment`, and `language` sets the language of the text. Generate a `session_token` when typing starts and send it with every suggestion request and the final place lookup, so the session is one search. Nothing is stored. Billed one call.\n\nSuggest addresses while they are typed, then give the chosen one as a structured address with coordinates.", "x-superroute-capability": "geo.autocomplete", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.autocomplete", "responses": { "200": { "description": "The suggestions for the text typed so far. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.autocomplete" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "suggestions": { "type": "array", "description": "Up to five suggestions, best first.", "items": { "type": "object", "properties": { "place_id": { "type": "string", "description": "Pass to POST /v1/geo/place for the address and coordinates." }, "description": { "type": "string", "description": "The whole suggestion on one line." }, "main_text": { "type": "string", "description": "The street part." }, "secondary_text": { "type": "string", "description": "The city, province and country part." }, "types": { "type": "array", "items": { "type": "string" }, "description": "What the suggestion is (address, premise, subpremise, route ...)." } } } } }, "required": [ "suggestions" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.autocomplete", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "suggestions": [ { "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww", "description": "1000 Rue De la Gauchetière Ouest, Montreal, QC, Canada", "main_text": "1000 Rue De la Gauchetière Ouest", "secondary_text": "Montreal, QC, Canada", "types": [ "geocode", "subpremise" ] }, { "place_id": "ChIJybX38KwbyUwRuUlJnrlZOAk", "description": "1000 Rue de la Gauchetière Est, Montreal, QC, Canada", "main_text": "1000 Rue de la Gauchetière Est", "secondary_text": "Montreal, QC, Canada", "types": [ "geocode", "subpremise" ] }, { "place_id": "ChIJq6qqH10ayUwRDKm5QlrmM2g", "description": "1000 Rue de la Gauchetière E, Montreal, QC, Canada", "main_text": "1000 Rue de la Gauchetière E", "secondary_text": "Montreal, QC, Canada", "types": [ "geocode", "subpremise" ] }, { "place_id": "EjExMDAwIFJ1ZSBkZSBsYSBHYXVjaGV0acOocmUsIE1vbnRyZWFsLCBRQywgQ2FuYWRhIjESLwoUChIJGz5nxFwayUwRxfGQnpCySKkQ6AcqFAoSCZVv0iVdGslMEUpWKOwLwBz0", "description": "1000 Rue de la Gauchetière, Montreal, QC, Canada", "main_text": "1000 Rue de la Gauchetière", "secondary_text": "Montreal, QC, Canada", "types": [ "geocode", "street_address" ] }, { "place_id": "EjYxMDAwIFJ1ZSBkZSBsYSBHYXVjaGV0acOocmUsIE1vbnRyw6lhbC1Fc3QsIFFDLCBDYW5hZGEiLiosChQKEgk5hd5QFeLITBFVgO8QJcFsCBIUChIJndvyLgHiyEwREdLOpOC4H6k", "description": "1000 Rue de la Gauchetière, Montréal-Est, QC, Canada", "main_text": "1000 Rue de la Gauchetière", "secondary_text": "Montréal-Est, QC, Canada", "types": [ "geocode", "route" ] } ] }, "meta": { "provider": "google" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "input": { "type": "string", "minLength": 3, "maxLength": 200 }, "language": { "type": [ "string", "null" ], "maxLength": 16 }, "near": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Required when near is present." }, "lng": { "type": "number", "minimum": -180, "maximum": 180, "description": "Required when near is present." }, "radius_meters": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50000 } } }, "session_token": { "type": [ "string", "null" ], "maxLength": 64 }, "types": { "type": [ "string", "null" ], "enum": [ "address", "geocode", "establishment" ] } }, "additionalProperties": false, "required": [ "input" ] }, "example": { "input": "1000 rue de la Gauchetiere", "countries": [ "ca" ], "session_token": "6f1c2a8e-4b1d-4a39-9d0e-5b8f3c7a21de" } } } } } }, "/v1/geo/coverage": { "get": { "operationId": "geoCoverage", "tags": [ "platform" ], "summary": "Geocoding coverage", "description": "Reports the countries covered by the geocoding chain and the quality of coverage in each. Free of charge, so that market coverage can be established before purchase.\n\nList what this key can call, at what price, against which quota.", "x-superroute-capability": "platform.capabilities", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.capabilities", "responses": { "200": { "description": "Which providers answer for which country, in the order they are tried. Free. The example is shortened to two countries and two providers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "platform.capabilities" }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "forward_chain": { "type": "array", "items": { "type": "string" }, "description": "Providers tried for forward geocoding, first to last." }, "reverse_chain": { "type": "array", "items": { "type": "string" }, "description": "Providers tried for reverse geocoding, first to last." }, "postcode_pattern": { "type": [ "string", "null" ], "description": "The regular expression geo.validate checks postcodes against." } } } }, "providers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "What the provider can do: forward, forward_text, reverse and so on." }, "available": { "type": "boolean", "description": "Configured and answering." } } } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "platform.capabilities", "data": { "countries": [ { "country": "CA", "forward_chain": [ "internal", "qcaddress", "bcaddress", "geolocator", "google" ], "reverse_chain": [ "internal", "bcaddress", "google" ], "postcode_pattern": "/^[A-Z][0-9][A-Z][- ]?[0-9][A-Z][0-9]$/i" }, { "country": "US", "forward_chain": [ "internal", "census", "google" ], "reverse_chain": [ "internal", "google" ], "postcode_pattern": "/^[0-9]{5}([- ]?[0-9]{4})?$/" } ], "providers": [ { "code": "internal", "name": "SuperRoute Geocoding", "capabilities": [ "forward", "forward_text", "reverse" ], "available": true }, { "code": "google", "name": "Google Maps", "capabilities": [ "forward", "forward_text", "reverse", "places", "forward_within_postcode" ], "available": true } ] } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } } } }, "/v1/geo/forward": { "post": { "operationId": "geoForward", "tags": [ "geo" ], "summary": "Geocode an address", "description": "Resolves a street address to coordinates, with the matched address components and the provider that answered.\n\nTurn an address into coordinates through a per-country provider chain.", "x-superroute-capability": "geo.forward", "x-superroute-billing-unit": "point", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.forward", "responses": { "200": { "description": "The location of one address. A miss answers 200 with `matched: false` and is billed like a hit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.forward" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "matched": { "type": "boolean", "description": "Whether a location was found. A miss is not an error and is still billed." }, "reason": { "type": "string", "description": "Why nothing matched. Present only when `matched` is false." }, "location": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, WGS84." }, "lng": { "type": "number", "description": "Longitude, WGS84." } }, "required": [ "lat", "lng" ] }, "address": { "type": "object", "description": "The matched address as the provider parsed it. Only the parts the provider returned are present; may be empty.", "properties": { "number": { "type": "string", "description": "House number." }, "street": { "type": "string", "description": "Street name, normalized." }, "city": { "type": "string" }, "province": { "type": "string", "description": "Province or state." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "postcode": { "type": "string" }, "unit": { "type": "string", "description": "Unit, suite or apartment." } } }, "confidence": { "type": [ "number", "null" ], "description": "0-1, as the provider reports it; null when the provider gives none." }, "provider": { "type": "string", "description": "The provider that answered (see GET /v1/geo/coverage)." } }, "required": [ "matched" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.forward", "billing": { "unit": "point", "quantity": 1, "counted": true }, "data": { "matched": true, "location": { "lat": 45.498174, "lng": -73.566218 }, "address": { "number": "1000", "street": "rue de la gauchetière o", "city": "Montreal", "province": "QC", "country": "CA", "postcode": "h3b 4w5" }, "confidence": 1, "provider": "internal" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address1": { "type": [ "string", "null" ], "maxLength": 255, "description": "Required unless one of city,postcode is supplied." }, "address2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "country": { "type": [ "string", "null" ], "maxLength": 120 }, "postcode": { "type": [ "string", "null" ], "maxLength": 32 }, "province": { "type": [ "string", "null" ], "maxLength": 120 } }, "additionalProperties": false }, "example": { "address1": "1000 Rue De La Gauchetière O", "city": "Montreal", "province": "QC", "country": "CA", "postcode": "H3B 4W5" } } } } } }, "/v1/geo/forward/batch": { "post": { "operationId": "geoForwardBatch", "tags": [ "geo" ], "summary": "Geocode many addresses", "description": "Resolves up to one thousand addresses in a single request. Billed on addresses submitted: an unmatched address still consumes a provider lookup.\n\nGeocode many addresses in one call, billed per thousand points.", "x-superroute-capability": "geo.batch", "x-superroute-billing-unit": "point_1k", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.batch", "responses": { "200": { "description": "One result per address, in request order. Billed per thousand addresses sent, matched or not.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.batch" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position of the address in the request, from 0." }, "matched": { "type": "boolean", "description": "Whether a location was found. A miss is not an error and is still billed." }, "reason": { "type": "string", "description": "Why nothing matched. Present only when `matched` is false." }, "location": { "type": "object", "properties": { "lat": { "type": "number", "description": "Latitude, WGS84." }, "lng": { "type": "number", "description": "Longitude, WGS84." } }, "required": [ "lat", "lng" ] }, "address": { "type": "object", "description": "The matched address as the provider parsed it. Only the parts the provider returned are present; may be empty.", "properties": { "number": { "type": "string", "description": "House number." }, "street": { "type": "string", "description": "Street name, normalized." }, "city": { "type": "string" }, "province": { "type": "string", "description": "Province or state." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "postcode": { "type": "string" }, "unit": { "type": "string", "description": "Unit, suite or apartment." } } }, "confidence": { "type": [ "number", "null" ], "description": "0-1, as the provider reports it; null when the provider gives none." }, "provider": { "type": "string", "description": "The provider that answered (see GET /v1/geo/coverage)." } } }, "description": "One result per address, in request order." }, "matched": { "type": "integer", "description": "Results with `matched: true`." }, "total": { "type": "integer", "description": "Addresses sent." } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.batch", "billing": { "unit": "point_1k", "quantity": 0.002, "counted": true }, "data": { "results": [ { "index": 0, "matched": true, "location": { "lat": 45.4981126, "lng": -73.56598129999999 }, "address": [], "confidence": null, "provider": "google" }, { "index": 1, "matched": true, "location": { "lat": 43.642596, "lng": -79.387089 }, "address": { "number": "290", "street": "bremner blvd", "city": "Toronto", "country": "CA" }, "confidence": 1, "provider": "internal" } ], "matched": 2, "total": 2 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "address1": { "type": [ "string", "null" ], "maxLength": 255 }, "address2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "country": { "type": [ "string", "null" ], "maxLength": 120 }, "postcode": { "type": [ "string", "null" ], "maxLength": 32 }, "province": { "type": [ "string", "null" ], "maxLength": 120 } } } } }, "additionalProperties": false, "required": [ "addresses" ] }, "example": { "addresses": [ { "address1": "1000 Rue De La Gauchetière O", "city": "Montreal", "country": "CA" }, { "address1": "290 Bremner Blvd", "city": "Toronto", "country": "CA" } ] } } } } } }, "/v1/geo/place": { "post": { "operationId": "geoPlace", "tags": [ "geo" ], "summary": "Get a suggestion's address", "description": "Returns the address of a suggestion's `place_id` as `formatted_address`, structured `address` (number, street, `address_1`, `address_2`, city, province code, ISO country code, postcode) and `location` coordinates. Send the `session_token` used while typing. Nothing is stored. Billed one call, under address autocomplete.\n\nSuggest addresses while they are typed, then give the chosen one as a structured address with coordinates.", "x-superroute-capability": "geo.autocomplete", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.autocomplete", "responses": { "200": { "description": "The suggestion's address and coordinates. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.autocomplete" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "place_id": { "type": "string", "description": "The place id." }, "formatted_address": { "type": "string", "description": "The address on one line." }, "address": { "type": "object", "properties": { "number": { "type": [ "string", "null" ], "description": "Civic number." }, "street": { "type": [ "string", "null" ], "description": "Street name." }, "address_1": { "type": [ "string", "null" ], "description": "Number and street." }, "address_2": { "type": [ "string", "null" ], "description": "Unit or suite, when the place has one." }, "city": { "type": [ "string", "null" ], "description": "City." }, "province": { "type": [ "string", "null" ], "description": "Province or state code." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "postcode": { "type": [ "string", "null" ], "description": "Postcode." } } }, "location": { "type": [ "object", "null" ], "description": "The coordinates, `{lat, lng}`." } }, "required": [ "place_id", "address", "location" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.autocomplete", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww", "formatted_address": "1000 Rue De la Gauchetière O, Montréal, QC H3B 4W5, Canada", "address": { "number": "1000", "street": "Rue De la Gauchetière Ouest", "address_1": "1000 Rue De la Gauchetière Ouest", "address_2": null, "city": "Montréal", "province": "QC", "country": "CA", "postcode": "H3B 4W5" }, "location": { "lat": 45.4981354, "lng": -73.5659122 } }, "meta": { "provider": "google" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": [ "string", "null" ], "maxLength": 16 }, "place_id": { "type": "string", "maxLength": 512 }, "session_token": { "type": [ "string", "null" ], "maxLength": 64 } }, "additionalProperties": false, "required": [ "place_id" ] }, "example": { "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww", "session_token": "6f1c2a8e-4b1d-4a39-9d0e-5b8f3c7a21de" } } } } } }, "/v1/geo/reverse": { "post": { "operationId": "geoReverse", "tags": [ "geo" ], "summary": "Reverse geocode a coordinate", "description": "Resolves a coordinate to a structured address.\n\nTurn coordinates into a structured address.", "x-superroute-capability": "geo.reverse", "x-superroute-billing-unit": "point", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.reverse", "responses": { "200": { "description": "The address at a point.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.reverse" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "matched": { "type": "boolean", "description": "Whether an address was found." }, "reason": { "type": "string", "description": "Why nothing matched. Present only when `matched` is false." }, "address": { "type": "object", "properties": { "address_1": { "type": "string", "description": "Street address." }, "address_2": { "type": "string", "description": "Unit, suite or floor; empty when none." }, "city": { "type": "string" }, "province": { "type": "string", "description": "Province or state, as the provider names it." }, "country": { "type": "string", "description": "Country code, as the provider returns it." }, "postcode": { "type": "string" }, "full_address": { "type": "string", "description": "The whole address on one line." }, "country_code": { "type": [ "string", "null" ], "description": "The country as an ISO 3166-1 alpha-2 code, the form forward geocoding answers with. Null when the provider named no country that maps to a code." }, "province_code": { "type": [ "string", "null" ], "description": "The province or state as its short code (QC, ON, NY), the form forward geocoding answers with; upper-cased as given when the country has no list of codes. Null when the provider named none." } } }, "provider": { "type": "string", "description": "The provider that answered." } }, "required": [ "matched" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.reverse", "billing": { "unit": "point", "quantity": 1, "counted": true }, "data": { "matched": true, "address": { "address_1": "1000 Rue de La Gauchetière Ouest", "address_2": "", "city": "Montreal", "province": "Quebec", "country": "CAN", "postcode": "H3B 4W5", "full_address": "1000 Rue de La Gauchetière Ouest, Montreal, QC, Canada", "country_code": "CA", "province_code": "QC" }, "provider": "internal" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "language": { "type": [ "string", "null" ], "maxLength": 8 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "required": [ "lat", "lng" ] }, "example": { "lat": 45.4985, "lng": -73.5664 } } } } } }, "/v1/geo/reverse/batch": { "post": { "operationId": "geoReverseBatch", "tags": [ "geo" ], "summary": "Reverse geocode many coordinates", "description": "Resolves multiple coordinates in a single request.\n\nGeocode many addresses in one call, billed per thousand points.", "x-superroute-capability": "geo.batch", "x-superroute-billing-unit": "point_1k", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.batch", "responses": { "200": { "description": "One address per point, in request order. Billed per thousand points sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.batch" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position of the point in the request, from 0." }, "matched": { "type": "boolean", "description": "Whether an address was found." }, "reason": { "type": "string", "description": "Why nothing matched. Present only when `matched` is false." }, "address": { "type": "object", "properties": { "address_1": { "type": "string", "description": "Street address." }, "address_2": { "type": "string", "description": "Unit, suite or floor; empty when none." }, "city": { "type": "string" }, "province": { "type": "string", "description": "Province or state, as the provider names it." }, "country": { "type": "string", "description": "Country code, as the provider returns it." }, "postcode": { "type": "string" }, "full_address": { "type": "string", "description": "The whole address on one line." }, "country_code": { "type": [ "string", "null" ], "description": "The country as an ISO 3166-1 alpha-2 code, the form forward geocoding answers with. Null when the provider named no country that maps to a code." }, "province_code": { "type": [ "string", "null" ], "description": "The province or state as its short code (QC, ON, NY), the form forward geocoding answers with; upper-cased as given when the country has no list of codes. Null when the provider named none." } } }, "provider": { "type": "string", "description": "The provider that answered." } } } }, "matched": { "type": "integer", "description": "Results with `matched: true`." }, "total": { "type": "integer", "description": "Points sent." } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.batch", "billing": { "unit": "point_1k", "quantity": 0.002, "counted": true }, "data": { "results": [ { "index": 0, "matched": true, "address": { "address_1": "1000 Rue de La Gauchetière Ouest", "address_2": "", "city": "Montreal", "province": "Quebec", "country": "CAN", "postcode": "H3B 4W5", "full_address": "1000 Rue de La Gauchetière Ouest, Montreal, QC, Canada", "country_code": "CA", "province_code": "QC" }, "provider": "internal" }, { "index": 1, "matched": true, "address": { "address_1": "290 Bremner Boulevard", "address_2": "", "city": "Toronto", "province": "Ontario", "country": "CAN", "postcode": "M5V 3L9", "full_address": "CN Tower, Toronto, ON, Canada", "country_code": "CA", "province_code": "ON" }, "provider": "internal" } ], "matched": 2, "total": 2 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": [ "string", "null" ], "maxLength": 8 }, "points": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] } } }, "additionalProperties": false, "required": [ "points" ] }, "example": { "points": [ { "lat": 45.4985, "lng": -73.5664 }, { "lat": 43.6426, "lng": -79.3871 } ] } } } } } }, "/v1/geo/validate": { "post": { "operationId": "geoValidate", "tags": [ "geo" ], "summary": "Validate an address", "description": "Normalizes an address and validates its postcode format, PO Box status and telephone number against the rules for the specified country. No geocoding lookup is performed.\n\nNormalize an address and check its postcode, PO Box status and phone number.", "x-superroute-capability": "geo.validate", "x-superroute-billing-unit": "point", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/geo.validate", "responses": { "200": { "description": "Whether an address is deliverable as written: the postcode format of the country, PO Box detection and phone parsing, with the address normalized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "geo.validate" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True when `issues` is empty." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The request field at fault." }, "code": { "type": "string", "enum": [ "POSTCODE_FORMAT", "PO_BOX", "PHONE_UNPARSEABLE" ] }, "message": { "type": "string" } } } }, "normalized": { "type": "object", "description": "The address as sent, tidied. Fields not sent are left out.", "properties": { "address_1": { "type": "string" }, "address_2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "postcode": { "type": "string", "description": "Upper case, without spaces." }, "phone": { "type": "string", "description": "E.164, when a phone was sent and could be parsed." } } }, "checks": { "type": "object", "properties": { "postcode_format": { "type": [ "boolean", "null" ], "description": "True when the postcode matches the country's format; null when the country has no known format or no postcode was sent." }, "po_box": { "type": "boolean", "description": "True when the address is a PO Box." } } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "geo.validate", "billing": { "unit": "point", "quantity": 1, "counted": true }, "data": { "valid": true, "issues": [], "normalized": { "address_1": "1000 Rue De La Gauchetière O", "city": "Montreal", "province": "QC", "country": "CA", "postcode": "H3B4W5", "phone": "+15145550134" }, "checks": { "postcode_format": true, "po_box": false } } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address1": { "type": [ "string", "null" ], "maxLength": 255 }, "address2": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 120 }, "country": { "type": "string", "maxLength": 120 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "postcode": { "type": [ "string", "null" ], "maxLength": 32 }, "province": { "type": [ "string", "null" ], "maxLength": 120 } }, "additionalProperties": false, "required": [ "country" ] }, "example": { "address1": "1000 Rue De La Gauchetière O", "city": "Montreal", "province": "QC", "country": "CA", "postcode": "H3B 4W5", "phone": "514 555 0134" } } } } } }, "/v1/isochrone": { "post": { "operationId": "isochroneCompute", "tags": [ "isochrone" ], "summary": "Draw reach areas", "description": "Draws, for each of up to four values in `minutes` (1 to 120), the area that can be reached from `location` within that time for the vehicle `profile`, or with `direction: to` the area from which `location` is reached (one-way streets make the two differ). Each area is a GeoJSON MultiPolygon ([lng, lat]) with its surface in `area_km2`, smallest first. Times use the road network's typical speeds, not live traffic. A point too far from any road the profile may use is refused with `UNROUTABLE`. Nothing is stored. Billed one call.\n\nDraw the areas reachable from a point within given drive times.", "x-superroute-capability": "isochrone.compute", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/isochrone.compute", "responses": { "200": { "description": "The reach areas, one per drive time. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "isochrone.compute" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "location": { "type": "object", "description": "The point, `{lat, lng}`, as given." }, "direction": { "type": "string", "enum": [ "from", "to" ], "description": "`from`: reached from the point; `to`: from which the point is reached." }, "areas": { "type": "array", "description": "One area per value of `minutes`, smallest first.", "items": { "type": "object", "properties": { "minutes": { "type": "integer", "description": "The drive time." }, "area_km2": { "type": "number", "description": "The surface of the area in square kilometres." }, "geometry": { "type": "object", "description": "A GeoJSON MultiPolygon, positions as [lng, lat]." } } } } }, "required": [ "location", "direction", "areas" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "isochrone.compute", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "location": { "lat": 45.5017, "lng": -73.5673 }, "direction": "from", "areas": [ { "minutes": 5, "area_km2": 16.21, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ -73.563299, 45.530674 ], [ -73.583949, 45.515349 ], [ -73.584242, 45.513757 ], [ -73.591753, 45.494246 ], [ -73.600596, 45.467403 ], [ -73.575631, 45.482031 ], [ -73.559299, 45.476764 ], [ -73.543299, 45.48029 ], [ -73.542831, 45.475168 ], [ -73.54472, 45.4927 ], [ -73.552638, 45.4967 ], [ -73.550582, 45.507982 ], [ -73.547776, 45.516223 ], [ -73.554652, 45.527052 ], [ -73.563299, 45.530674 ] ] ] ] } }, { "minutes": 10, "area_km2": 85.45, "geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ -73.523299, 45.566736 ], [ -73.56589, 45.5577 ], [ -73.62407, 45.50747 ], [ -73.661785, 45.500214 ], [ -73.640299, 45.471298 ], [ -73.662299, 45.444574 ], [ -73.628651, 45.4447 ], [ -73.610299, 45.458262 ], [ -73.559421, 45.4547 ], [ -73.480299, 45.465887 ], [ -73.509065, 45.488465 ], [ -73.527299, 45.503088 ], [ -73.520532, 45.5297 ], [ -73.523299, 45.566736 ] ] ] ] } } ] }, "meta": { "profile": "car", "geometry_format": "geojson" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": [ "string", "null" ], "enum": [ "from", "to" ], "description": "`from` (default): the area reached from `location`. `to`: the area from which `location` is reached." }, "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] }, "minutes": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "integer", "minimum": 1, "maximum": 120 }, "description": "Up to four drive times, 1-120 minutes each; one area is drawn per value." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for: `car` (default when omitted) and `van` use the car costing; `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle. `motorcycle` avoids roads a motorcycle may not use. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." } }, "additionalProperties": false, "required": [ "location", "minutes" ] }, "example": { "location": { "lat": 45.5017, "lng": -73.5673 }, "minutes": [ 5, 10 ], "profile": "car" } } } } } }, "/v1/jobs": { "get": { "operationId": "jobsIndex", "tags": [ "platform" ], "summary": "List jobs", "description": "Lists recent asynchronous jobs for the account, most recent first.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "Recent jobs of this client, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "description": "A job. Fields without a value are left out.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ] }, "capability": { "type": "string", "description": "The capability the job runs." }, "progress": { "type": "integer", "description": "Percent complete, 0-100." }, "stage": { "type": "string", "description": "What the job is doing: `queued`, `solving`, an engine stage while it runs, then `done`, `failed` or `cancelled`." }, "created_at": { "type": "string", "description": "ISO 8601 with offset." }, "started_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job starts." }, "finished_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job ends." }, "result_url": { "type": "string", "description": "Where to collect the result. Present only once the job has succeeded." }, "result_expires_at": { "type": "string", "description": "After this the result is deleted; collect it before then. ISO 8601 with offset." }, "error": { "type": "object", "description": "Present only when the job failed.", "properties": { "code": { "type": "string", "description": "An error code from the error catalog." }, "message": { "type": [ "string", "null" ], "description": "What went wrong." } } } }, "required": [ "id", "status" ] } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "jobs": [ { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "succeeded", "capability": "routing.optimize", "progress": 100, "stage": "done", "created_at": "2026-10-23T09:27:40-04:00", "started_at": "2026-10-23T09:27:40-04:00", "finished_at": "2026-10-23T09:27:40-04:00", "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "result_expires_at": "2026-10-24T09:27:40-04:00" } ] } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } } } }, "/v1/jobs/{jobId}": { "get": { "operationId": "jobsShow", "tags": [ "platform" ], "summary": "Get job status", "description": "Reports the status and progress of a single job. Free of charge, as the work has already been billed.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "One job and where it has got to. Poll this until `status` is terminal (succeeded, failed, cancelled or expired), then collect `result_url`. `?wait=` holds the request until the job ends or the wait runs out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "description": "A job. Fields without a value are left out.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ] }, "capability": { "type": "string", "description": "The capability the job runs." }, "progress": { "type": "integer", "description": "Percent complete, 0-100." }, "stage": { "type": "string", "description": "What the job is doing: `queued`, `solving`, an engine stage while it runs, then `done`, `failed` or `cancelled`." }, "created_at": { "type": "string", "description": "ISO 8601 with offset." }, "started_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job starts." }, "finished_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job ends." }, "result_url": { "type": "string", "description": "Where to collect the result. Present only once the job has succeeded." }, "result_expires_at": { "type": "string", "description": "After this the result is deleted; collect it before then. ISO 8601 with offset." }, "error": { "type": "object", "description": "Present only when the job failed.", "properties": { "code": { "type": "string", "description": "An error code from the error catalog." }, "message": { "type": [ "string", "null" ], "description": "What went wrong." } } } }, "required": [ "id", "status" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "succeeded", "capability": "routing.optimize", "progress": 100, "stage": "done", "created_at": "2026-10-23T09:27:40-04:00", "started_at": "2026-10-23T09:27:40-04:00", "finished_at": "2026-10-23T09:27:40-04:00", "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "result_expires_at": "2026-10-24T09:27:40-04:00" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/jobs/{jobId}/cancel": { "post": { "operationId": "jobsCancel", "tags": [ "platform" ], "summary": "Cancel a job", "description": "Cancels a job that is queued or running. A completed job cannot be cancelled and remains billable.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "The job after the cancel. Cancelling a job that has already ended changes nothing and answers the job as it is.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "description": "A job. Fields without a value are left out.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ] }, "capability": { "type": "string", "description": "The capability the job runs." }, "progress": { "type": "integer", "description": "Percent complete, 0-100." }, "stage": { "type": "string", "description": "What the job is doing: `queued`, `solving`, an engine stage while it runs, then `done`, `failed` or `cancelled`." }, "created_at": { "type": "string", "description": "ISO 8601 with offset." }, "started_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job starts." }, "finished_at": { "type": "string", "description": "ISO 8601 with offset. Absent until the job ends." }, "result_url": { "type": "string", "description": "Where to collect the result. Present only once the job has succeeded." }, "result_expires_at": { "type": "string", "description": "After this the result is deleted; collect it before then. ISO 8601 with offset." }, "error": { "type": "object", "description": "Present only when the job failed.", "properties": { "code": { "type": "string", "description": "An error code from the error catalog." }, "message": { "type": [ "string", "null" ], "description": "What went wrong." } } } }, "required": [ "id", "status" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "succeeded", "capability": "routing.optimize", "progress": 100, "stage": "done", "created_at": "2026-10-23T09:27:40-04:00", "started_at": "2026-10-23T09:27:40-04:00", "finished_at": "2026-10-23T09:27:40-04:00", "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "result_expires_at": "2026-10-24T09:27:40-04:00" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/jobs/{jobId}/deliveries": { "get": { "operationId": "jobsDeliveries", "tags": [ "platform" ], "summary": "List webhook deliveries", "description": "Lists every webhook delivery attempt for a job, with endpoint, status, attempt count and error. This is the diagnostic surface for callbacks that did not arrive.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "Every callback delivery of the job, with the last attempt's outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "The delivery id, `dlv_...`. Also sent in the `X-Open-Delivery` header." }, "event": { "type": "string", "enum": [ "job.queued", "job.progress", "job.succeeded", "job.failed", "job.cancelled", "job.expired" ], "description": "The event delivered." }, "status": { "type": "string", "enum": [ "pending", "delivering", "retrying", "delivered", "dead_letter" ], "description": "`dead_letter` means every retry failed; replay it once the endpoint is fixed." }, "endpoint_host": { "type": "string", "description": "The host the callback was sent to." }, "attempt_count": { "type": "integer", "description": "Attempts made so far." }, "http_status": { "type": [ "integer", "null" ], "description": "The status your endpoint answered on the last attempt." }, "response_time_ms": { "type": [ "integer", "null" ], "description": "How long your endpoint took on the last attempt." }, "error_code": { "type": [ "string", "null" ], "description": "Why the last attempt failed, when it did." }, "error_message": { "type": [ "string", "null" ], "description": "Detail of `error_code`." }, "last_attempt_at": { "type": [ "string", "null" ], "description": "ISO 8601 with offset." }, "next_attempt_at": { "type": [ "string", "null" ], "description": "When the next retry is due. ISO 8601 with offset." }, "delivered_at": { "type": [ "string", "null" ], "description": "When your endpoint accepted it. ISO 8601 with offset." } } } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "deliveries": [ { "delivery_id": "dlv_01k8zq4h2k4m6p8r0t2w4y6a8c", "event": "job.succeeded", "status": "delivered", "endpoint_host": "hooks.example.com", "attempt_count": 1, "http_status": 200, "response_time_ms": 0, "error_code": null, "error_message": null, "last_attempt_at": "2026-10-23T09:27:40-04:00", "next_attempt_at": null, "delivered_at": "2026-10-23T09:27:40-04:00" } ] } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/jobs/{jobId}/deliveries/{deliveryId}/replay": { "post": { "operationId": "jobsDeliveriesReplay", "tags": [ "platform" ], "summary": "Replay a webhook delivery", "description": "Re-sends a webhook delivery to the registered endpoint, for cases where the receiver was unavailable and the automatic retries were exhausted.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "The delivery is queued to be sent again, with its original payload and a new attempt count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "The delivery that was queued again." }, "status": { "type": "string", "enum": [ "pending" ], "description": "The delivery is queued and is sent by the next delivery run." } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "delivery_id": "dlv_01k8zq4h2k4m6p8r0t2w4y6a8c", "status": "pending" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/jobs/{jobId}/result": { "get": { "operationId": "jobsResult", "tags": [ "platform" ], "summary": "Collect a job result", "description": "Collects the result of a completed job. Results remain available for 24 hours after completion and should be persisted by the client.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "The finished result, exactly as the synchronous call would have answered it: `data`, `warnings` and `meta` of the capability that ran (this example is a routing.optimize job). `billing.counted` is false because the call was billed when the job was accepted. A job that has not succeeded answers 409 JOB_NOT_FINISHED.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "description": "The unit of the capability that ran." }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "description": "The capability's own `data`; see that capability's reference.", "properties": [], "additionalProperties": true }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "billing": { "unit": "node", "quantity": 5, "counted": false, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2 } }, "data": { "routes": [ { "vehicle_id": "van-2", "stops": [ { "type": "start", "arrival": "2026-11-02T08:31:07-05:00", "arrival_epoch": 1793626267, "distance_meters": 0, "duration_seconds": 0, "load": [ 6 ] }, { "type": "job", "arrival": "2026-11-02T08:35:11-05:00", "arrival_epoch": 1793626511, "distance_meters": 1839, "duration_seconds": 244, "leg_distance_meters": 1839, "leg_duration_seconds": 244, "id": "order-1001", "load": [ 4 ] }, { "type": "job", "arrival": "2026-11-02T08:47:56-05:00", "arrival_epoch": 1793627276, "distance_meters": 5338, "duration_seconds": 709, "leg_distance_meters": 3499, "leg_duration_seconds": 465, "id": "order-1003", "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T09:00:00-05:00", "arrival_epoch": 1793628000, "distance_meters": 9220, "duration_seconds": 1193, "leg_distance_meters": 3882, "leg_duration_seconds": 484, "id": "order-1002", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 10687, "duration_seconds": 1390, "leg_distance_meters": 1467, "leg_duration_seconds": 197, "load": [ 0 ] } ], "stop_count": 5, "task_count": 3, "distance_meters": 10687, "duration_seconds": 1390, "service_seconds": 840, "waiting_seconds": 0, "geometry": null } ], "unassigned": [], "summary": { "routes": 1, "assigned": 3, "unassigned": 0, "distance_meters": 10687, "duration_seconds": 1390 } }, "meta": { "engine": "sroute2", "engine_version": "1.6.1", "solve_id": "e363b370-4113-44a0-8630-1579e1fbc799", "capacity_dimensions": [ "0" ] } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/label/barcode": { "post": { "operationId": "labelBarcode", "tags": [ "label" ], "summary": "Draw a barcode", "description": "Draws `value` in `symbology`: `code128` (default), `code39`, `code93`, `ean13`, `ean8`, `upca`, `upce`, `itf`, `codabar`, `code11`, or the 2D codes `qr`, `datamatrix` and `pdf417`. `format` is `png` (base64 in `image_base64`, on white with a quiet zone unless `quiet_zone` is false, with its `width` and `height` in pixels) or `svg` (the markup in `svg`). `module` is the width of the narrowest bar, or the size of a 2D module, in pixels; `height` is the bar height of a linear code; `text` prints the value under a linear code; `error_correction` (L, M, Q, H; default M) applies to QR codes. A value the symbology cannot hold is refused with `NOT_ENCODABLE`. Nothing is stored. Billed one call.\n\nDraw a barcode or a QR, Data Matrix or PDF417 code as an image.", "x-superroute-capability": "label.barcode", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/label.barcode", "responses": { "200": { "description": "The drawn code. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "label.barcode" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "symbology": { "type": "string", "description": "The symbology drawn." }, "value": { "type": "string", "description": "The value written." }, "content_type": { "type": "string", "enum": [ "image/png", "image/svg+xml" ], "description": "What was drawn." }, "width": { "type": "integer", "description": "Image width in pixels. PNG only." }, "height": { "type": "integer", "description": "Image height in pixels. PNG only." }, "image_base64": { "type": "string", "description": "The PNG, base64. PNG only." }, "svg": { "type": "string", "description": "The SVG markup. SVG only." } }, "required": [ "symbology", "value", "content_type" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "label.barcode", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "symbology": "code128", "value": "1Z999AA10123456784", "content_type": "image/png", "width": 440, "height": 100, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAbgAAABkCAIAAAB7I7IEAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAC0klEQVR4nO3d0W6yMACGYfiz+79l/gMS0ljar8icpj7P0Ya1VDbfQTDZum3bAkDbv3cvAODTCSVAIJQAgVACBEIJEAglQCCUAIFQAgRCCRAIJUAglACBUAIEQgkQCCVAIJQAgVACBEIJEAglQCCUAMHPnSev63p8vf/vnX1L+X946i31DPX4UuvRco/1+Hpka78je+zP+TkztH4K9V5Gjsn9GepXVG9vPTryW9T/fbt/tEdeXf8o9ce0ZuvP35ph5DjUq7r6Dhp/z46scOQ1tsaM77e/lxHOKAECoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAQKhBAiEEiAQSoBAKAECoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAQKhBAiEEiAQSoBAKAECoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAQKhBAiEEiAQSoBAKAECoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAQKhBAiEEiBYt2179xoAPpozSoDg590L4IXWdV2W5bho2L8t7Q+V208H/9bGekn3R7ae/jDJ+Gu/dJQ6q2UmLr2ndbyxT3/EDwUpW/CijadLujmy9fT6CJyGrP/053ZUH2om4NJ7Tuva+xP4ltOf/pKeG7ltW2tkfWK4b9yNTDV4lE5nYzIuvef0aZWMe+xf2Hae3rker6+4j1PCssUj54P7VJ3zXLmcm1B+l7qSDwm4urGcdmRja1WDralTVTarnOehev0ILo16ti78OztiSkL5RVpv7Jv3apaiIHHjqfFL8quD/4BzyW8glN8u3uXob/wz40s6vc3yRGTj4NYdeebjrvecTj/j8oqPB129FT6y9/uLP5zeSR98madRHtkR8xFKgMDHgwACoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAQKhBAiEEiAQSoBAKAECoQQIhBIgEEqAQCgBAqEECIQSIBBKgEAoAYL/0ZAf9Hxdf0cAAAAASUVORK5CYII=" }, "meta": { "format": "png" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "error_correction": { "type": [ "string", "null" ], "enum": [ "L", "M", "Q", "H" ] }, "format": { "type": [ "string", "null" ], "enum": [ "png", "svg" ] }, "height": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 600 }, "module": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 }, "quiet_zone": { "type": [ "boolean", "null" ] }, "symbology": { "type": [ "string", "null" ], "enum": [ "code128", "code39", "code93", "ean13", "ean8", "upca", "upce", "itf", "codabar", "code11", "qr", "datamatrix", "pdf417" ] }, "text": { "type": [ "boolean", "null" ] }, "value": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false, "required": [ "value" ] }, "example": { "value": "1Z999AA10123456784", "symbology": "code128", "text": true } } } } } }, "/v1/loading/solve": { "post": { "operationId": "loadingSolve", "tags": [ "loading" ], "summary": "Plan a container load", "description": "Places cargo within a trailer or container in three dimensions, accounting for centre of gravity, stacking rules and an optional unload sequence.\n\nPlace cargo in a trailer or container with centre of gravity and unload order.", "x-superroute-capability": "loading.solve", "x-superroute-billing-unit": "job", "x-superroute-release-stage": "beta", "x-superroute-async": true, "x-superroute-docs": "/developer/capabilities/loading.solve", "responses": { "200": { "description": "Ranked ways to load the items into the container, each with where every unit sits, utilization and balance. Answered in the request's units (cm and kg). The example is shortened to the first candidate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "loading.solve" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "coordinate_system": { "type": "object", "properties": { "unit": { "type": "string", "description": "Unit of every position and size." }, "origin": { "type": "string", "description": "Where x, y and z are measured from." }, "x_axis": { "type": "string" }, "y_axis": { "type": "string" }, "z_axis": { "type": "string" } } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "1 is the recommended candidate." }, "algorithm": { "type": "string", "description": "The placement heuristic that produced it." }, "score": { "type": "number", "description": "The ranking score; higher is better." }, "placements": { "type": "array", "items": { "type": "object", "properties": { "x_cm": { "type": "number", "description": "Position along the length axis, from the origin of `coordinate_system`." }, "y_cm": { "type": "number", "description": "Position along the width axis." }, "z_cm": { "type": "number", "description": "Height above the floor." }, "length_cm": { "type": "number", "description": "Footprint along x after rotation." }, "width_cm": { "type": "number", "description": "Footprint along y after rotation." }, "height_cm": { "type": "number", "description": "Extent along z after rotation." }, "rotation_key": { "type": "string", "description": "How the item was turned: the order its own length (L), width (W) and height (H) take along x, y and z." }, "stack_level": { "type": "integer", "description": "1 on the floor, 2 on top of one item, and so on." }, "container_index": { "type": "integer", "description": "Which container or package, from 1." }, "unit_sequence": { "type": "integer", "description": "Loading order within the container, from 1." }, "unit_key": { "type": "string", "description": "Identifies the unit: `item-{row}-{n}`, row and unit counted from 1." }, "item_id": { "type": "string", "description": "The caller's item id." }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "weight_kg": { "type": "number", "description": "Weight of the unit." }, "cargo_form": { "type": "string", "description": "`loose`, or `pallet` for a unit built on a pallet." }, "source_item_count": { "type": "integer", "description": "Items the unit stands for (above 1 for a built pallet)." }, "pallet_group_key": { "type": [ "string", "null" ], "description": "The pallet this unit was built into, when palletized." }, "metadata": { "type": "object", "description": "The item's handling rules as the solver applied them.", "properties": { "stackable": { "type": "boolean" }, "max_stack_layers": { "type": [ "integer", "null" ] }, "bearing_level": { "type": [ "integer", "null" ] }, "allowed_orientations": { "type": "array", "items": { "type": "string" }, "description": "The rotations this item may take." }, "stack_level": { "type": "integer" } } } } }, "description": "One entry per unit." }, "unplaced": { "type": "array", "items": { "type": "object", "properties": [], "additionalProperties": true }, "description": "Units that did not fit." }, "metrics": { "type": "object", "properties": { "container_count": { "type": "integer" }, "placed_quantity": { "type": "integer" }, "unplaced_quantity": { "type": "integer" }, "used_volume_m3": { "type": "number" }, "container_volume_m3": { "type": "number" }, "volume_utilization_percent": { "type": "number" }, "used_weight_kg": { "type": "number" }, "max_payload_kg": { "type": "number" }, "payload_utilization_percent": { "type": "number" }, "target_achieved": { "type": "boolean", "description": "Whether `target_utilization_percent` was reached." }, "gravity_max_quadrant_percent": { "type": "number", "description": "Share of the load in the heaviest floor quadrant." }, "gravity_imbalanced": { "type": "boolean" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Codes such as TARGET_UTILIZATION_NOT_REACHED or GRAVITY_IMBALANCED." }, "checksum": { "type": "string", "description": "Identifies this exact layout." } } } } } }, "meta": { "type": "object", "properties": { "solver_version": { "type": "string" }, "rules_version": { "type": "string" }, "candidate_limit": { "type": "integer" }, "input_hash": { "type": "string", "description": "Hash of the request; equal requests give equal answers." }, "units": { "type": "object", "properties": { "dimensions": { "type": "string" }, "weight": { "type": "string" } } }, "mode": { "type": "string" } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "loading.solve", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "item_rows": 1, "units": 4, "candidates": 3 } }, "data": { "coordinate_system": { "unit": "cm", "origin": "container_inner_bottom_left_rear", "x_axis": "container_length", "y_axis": "container_width", "z_axis": "up" }, "candidates": [ { "rank": 1, "algorithm": "balanced_volume", "score": 16.667, "placements": [ { "x_cm": 0, "y_cm": 0, "z_cm": 0, "length_cm": 120, "width_cm": 100, "height_cm": 120, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 1, "unit_key": "item-1-1", "item_id": "PAL-1", "name": "PAL-1", "sku": null, "weight_kg": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "LHW" ], "stack_level": 1 } }, { "x_cm": 0, "y_cm": 100, "z_cm": 0, "length_cm": 120, "width_cm": 100, "height_cm": 120, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 2, "unit_key": "item-1-2", "item_id": "PAL-1", "name": "PAL-1", "sku": null, "weight_kg": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "LHW" ], "stack_level": 1 } }, { "x_cm": 120, "y_cm": 0, "z_cm": 0, "length_cm": 120, "width_cm": 100, "height_cm": 120, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 3, "unit_key": "item-1-3", "item_id": "PAL-1", "name": "PAL-1", "sku": null, "weight_kg": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "LHW" ], "stack_level": 1 } }, { "x_cm": 120, "y_cm": 100, "z_cm": 0, "length_cm": 120, "width_cm": 100, "height_cm": 120, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 4, "unit_key": "item-1-4", "item_id": "PAL-1", "name": "PAL-1", "sku": null, "weight_kg": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "LHW" ], "stack_level": 1 } } ], "unplaced": [], "metrics": { "container_count": 1, "placed_quantity": 4, "unplaced_quantity": 0, "used_volume_m3": 5.76, "container_volume_m3": 34.56, "volume_utilization_percent": 16.667, "used_weight_kg": 1600, "max_payload_kg": 24000, "payload_utilization_percent": 6.667, "target_achieved": false, "gravity_max_quadrant_percent": 50, "gravity_imbalanced": true }, "warnings": [ "TARGET_UTILIZATION_NOT_REACHED", "GRAVITY_IMBALANCED" ], "checksum": "dfe9189f5980c2d4ca6945a426c2197d879ee85934809c80a591f4562ed9246e" } ] }, "meta": { "solver_version": "php-guillotine-3d-1.2", "rules_version": "ocean-no-sequence-1.2", "candidate_limit": 3, "input_hash": "4c4ebf12319f01e2c9bf8c1ff12eec06f9a236c9a6bc50b01adad01d18b3ad7b", "units": { "dimensions": "cm", "weight": "kg" }, "mode": "sync" } } } } }, "202": { "description": "Accepted: the work is queued as a job and billed now. Poll GET /v1/jobs/{jobId} (the `Location` header) and collect the result from `result_url`; a verified `callback` is called when it ends.", "headers": { "Location": { "description": "Where to poll for the job.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "loading.solve" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "object", "description": "The job that will produce the result.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on this answer." }, "capability": { "type": "string", "description": "The capability the job runs." }, "poll_after_ms": { "type": "integer", "description": "How long to wait before the first poll." }, "result_url": { "type": "string", "description": "Where to collect the result once the job has succeeded." }, "cancel_url": { "type": "string", "description": "Where to cancel the job." } } } }, "required": [ "job" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "loading.solve", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "item_rows": 1, "units": 4, "candidates": 3 } }, "data": { "job": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "queued", "capability": "loading.solve", "poll_after_ms": 1000, "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel" } }, "meta": { "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "candidate_limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3 }, "container": { "type": "object", "properties": { "corner_cm": { "type": [ "number", "null" ], "minimum": 0 }, "height_cm": { "type": "number", "exclusiveMinimum": 0 }, "length_cm": { "type": "number", "exclusiveMinimum": 0 }, "max_payload_kg": { "type": [ "number", "null" ], "minimum": 0 }, "preset": { "type": [ "string", "null" ], "maxLength": 64 }, "quantity_limit": { "type": [ "integer", "null" ], "minimum": 1 }, "width_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "height_cm", "length_cm", "width_cm" ] }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "auto_palletize": { "type": [ "boolean", "null" ] }, "bearing_level": { "type": [ "integer", "null" ], "minimum": 0 }, "can_rotate": { "type": [ "boolean", "null" ] }, "cargo_form": { "type": [ "string", "null" ], "enum": [ "loose", "pre_palletized" ] }, "height_cm": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "length_cm": { "type": "number", "exclusiveMinimum": 0 }, "max_stack_layers": { "type": [ "integer", "null" ], "minimum": 1 }, "name": { "type": [ "string", "null" ], "maxLength": 191 }, "orientation": { "type": [ "string", "null" ], "enum": [ "any", "upright_only", "side_only" ] }, "pallet_profile": { "type": [ "array", "null" ] }, "prohibit_mixed_pallet": { "type": [ "boolean", "null" ] }, "quantity": { "type": [ "integer", "null" ], "minimum": 1 }, "sku": { "type": [ "string", "null" ], "maxLength": 128 }, "stackable": { "type": [ "boolean", "null" ] }, "unload_priority": { "type": [ "integer", "null" ], "minimum": 0 }, "unload_stop_id": { "type": [ "string", "null" ], "maxLength": 128 }, "weight_kg": { "type": [ "number", "null" ], "minimum": 0 }, "width_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "height_cm", "length_cm", "width_cm" ] } }, "leftover_policy": { "type": [ "string", "null" ], "enum": [ "allow_loose", "keep_unloaded" ] }, "loading_method": { "type": [ "string", "null" ], "enum": [ "direct_container", "palletize_then_container" ] }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "target_utilization_percent": { "type": [ "number", "null" ], "minimum": 1, "maximum": 100 }, "unloading": { "type": [ "object", "null" ], "properties": { "direction": { "type": [ "string", "null" ], "enum": [ "rear_to_front", "front_to_rear" ] }, "mode": { "type": [ "string", "null" ], "enum": [ "none", "unload_sequence" ] }, "rehandle_penalty": { "type": [ "number", "null" ], "minimum": 0 }, "stops": { "type": [ "array", "null" ] } } } }, "additionalProperties": false, "required": [ "container", "items" ] }, "example": { "container": { "preset": "custom", "length_cm": 600, "width_cm": 240, "height_cm": 240, "max_payload_kg": 24000 }, "items": [ { "id": "PAL-1", "quantity": 4, "length_cm": 120, "width_cm": 100, "height_cm": 120, "weight_kg": 400 } ] } } } } } }, "/v1/map/static": { "post": { "operationId": "mapStatic", "tags": [ "map" ], "summary": "Draw a static map", "description": "Draws the submitted GeoJSON features — lines, points with labels of up to four characters, and areas — on the street map and returns the map as a base64-encoded PNG in `data.image_base64`, with its pixel `width` and `height` and the `zoom` used. Give `width` and `height` in CSS pixels (at most 2048) and `scale` 1 or 2; the view fits the features unless `center` and `zoom` are given. `flavor` picks one of five colour schemes and `language` the language of place and street names. Styles are read from each feature's `properties`: lines `stroke`, `stroke_width`, `dashed`, `arrows`; points `marker` (pin or circle), `fill`, `label`, `size`; areas `fill`, `fill_opacity`, `stroke`. Every image carries the OpenStreetMap credit. Nothing is stored. Billed one call.\n\nDraw your own lines, points and areas on the street map and receive a PNG image.", "x-superroute-capability": "map.static", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/map.static", "responses": { "200": { "description": "The caller's GeoJSON drawn on the street map as a PNG, returned base64-encoded. Nothing is stored. The example's `image_base64` is shortened.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "map.static" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "content_type": { "type": "string", "enum": [ "image/png" ] }, "width": { "type": "integer", "description": "Image width in pixels: `width` × `scale`." }, "height": { "type": "integer", "description": "Image height in pixels: `height` × `scale`." }, "zoom": { "type": "number", "description": "The zoom the map was drawn at: the one sent, or the one fitted to the features." }, "image_base64": { "type": "string", "description": "The PNG, base64-encoded." } }, "required": [ "content_type", "image_base64" ] }, "meta": { "type": "object", "properties": { "bytes": { "type": "integer", "description": "Size of the PNG." } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "map.static", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "content_type": "image/png", "width": 400, "height": 300, "zoom": 14.2, "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAEsCAYAAAA..." }, "meta": { "bytes": 48213 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "413": { "description": "The request body is too large. Upload large payloads as a reusable resource instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body is too large. Upload large payloads as a reusable resource instead.", "status": 413, "doc_url": "/developer/errors/REQUEST_TOO_LARGE" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "center": { "type": "array", "description": "Required when zoom is present.", "items": { "type": "number" } }, "features": { "type": [ "object", "null" ], "properties": { "features": { "type": "array", "maxItems": 20000, "description": "Required when features is present.", "items": { "type": "object", "properties": { "geometry": { "type": "array" }, "properties": { "type": [ "array", "null" ] }, "type": { "type": "string", "enum": [ "Feature" ] } }, "required": [ "geometry", "type" ] } }, "type": { "type": "string", "enum": [ "FeatureCollection" ], "description": "Required when features is present." } }, "required": [ "features" ] }, "flavor": { "type": [ "string", "null" ], "enum": [ "light", "white", "grayscale", "dark", "black" ] }, "height": { "type": "integer", "minimum": 1, "maximum": 2048 }, "language": { "type": [ "string", "null" ], "maxLength": 16 }, "max_zoom": { "type": [ "number", "null" ], "minimum": 0, "maximum": 20 }, "padding": { "type": [ "number", "null" ], "minimum": 0 }, "scale": { "type": [ "integer", "null" ], "enum": [ "1", "2" ] }, "width": { "type": "integer", "minimum": 1, "maximum": 2048 }, "zoom": { "type": [ "number", "null" ], "minimum": 0, "maximum": 22, "description": "Required when center is present." } }, "additionalProperties": false, "required": [ "features", "height", "width" ] }, "example": { "width": 400, "height": 300, "features": { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -73.5673, 45.5017 ] }, "properties": { "marker-color": "#1e88e5" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [ -73.5673, 45.5017 ], [ -73.554, 45.5088 ] ] }, "properties": { "stroke": "#1e88e5" } } ] } } } } } } }, "/v1/map/token": { "post": { "operationId": "mapToken", "tags": [ "map" ], "summary": "Issue a map token", "description": "Issues a short-lived token that your apps and pages use to load map tiles from the map service. Give `ttl_seconds` from 60 to 86400 (default 3600). The answer has the `token`, its `expires_at`, the map service address `base_url` and the `subject` under which the tiles are counted. Ask for tokens from your server: a token is the stronger alternative to a map key, which is built into an app and limited by its allowlist. Map keys are kept on the Map keys page of the Open Platform portal. Nothing is stored. The call bills nothing; tiles loaded with the token or with your map keys are billed per thousand.\n\nMap keys and short-lived tokens for your own apps and pages; tiles are billed per thousand.", "x-superroute-capability": "map.tiles", "x-superroute-billing-unit": "tile_1k", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/map.tiles", "responses": { "200": { "description": "A short-lived token for your apps and pages to load map tiles with. The call bills nothing; the tiles are billed per thousand.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "map.tiles" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "tile_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "The token. Send it as `Authorization: Bearer ` or give it to the map SDK as its token." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the token stops working (UTC)." }, "base_url": { "type": "string", "description": "The map service address the token is for." }, "subject": { "type": "string", "description": "Whom the tiles loaded with the token are counted for: `open:` and your account number." } }, "required": [ "token", "expires_at", "base_url", "subject" ] }, "meta": { "type": "object", "properties": { "ttl_seconds": { "type": "integer", "description": "How long the token is valid, in seconds." } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zr4n6p8q0s2u4w6y8a0c3e", "capability": "map.tiles", "billing": { "unit": "tile_1k", "quantity": 0, "counted": true }, "data": { "token": "sm1.eyJzdWIiOiJvcGVuOjQyMTciLCJleHAiOjE3OTMxMjQ4MDB9.Q2v8m1Xb3dKp7Rz0Yt5Wn9Lc4Hs6Fg2Ja8Ue1Oi3Pk", "expires_at": "2026-10-27T15:00:00Z", "base_url": "https://maps.example.com", "subject": "open:4217" }, "meta": { "ttl_seconds": 3600 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "413": { "description": "The request body is too large. Upload large payloads as a reusable resource instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body is too large. Upload large payloads as a reusable resource instead.", "status": 413, "doc_url": "/developer/errors/REQUEST_TOO_LARGE" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_seconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 86400 } }, "additionalProperties": false }, "example": { "ttl_seconds": 3600 } } } } } }, "/v1/matrix": { "post": { "operationId": "matrixCompute", "tags": [ "matrix" ], "summary": "Compute a distance matrix", "description": "Computes road distances and durations between multiple origins and destinations. Cost scales with the number of origin rows, each of which requires an engine round trip. Where a matrix is required in order to plan routes, routing.optimize constructs it internally and is the cheaper call.\n\nDistances and durations between many origins and destinations.", "x-superroute-capability": "matrix.compute", "x-superroute-billing-unit": "element_1k", "x-superroute-release-stage": "beta", "x-superroute-async": true, "x-superroute-docs": "/developer/capabilities/matrix.compute", "responses": { "200": { "description": "Road distance and driving time from every origin to every destination. Row i is origin i, column j is destination j. A cell that could not be routed is null in both matrices and listed in `unreachable`; it is never 0. Large matrices answer 202 with a job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "matrix.compute" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "element_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "origins": { "type": "array", "items": { "type": "string" }, "description": "Origin ids, in row order. An origin sent without an id is numbered from 0." }, "destinations": { "type": "array", "items": { "type": "string" }, "description": "Destination ids, in column order. Equal to `origins` when no destinations were sent." }, "distances_meters": { "type": "array", "items": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "description": "Present when `metrics` includes distance (the default)." }, "durations_seconds": { "type": "array", "items": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "description": "Present when `metrics` includes duration (the default)." }, "unreachable": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" } } }, "description": "Cells that could not be routed." } } }, "meta": { "type": "object", "properties": { "region": { "type": "string" }, "profile": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "origins": { "type": "integer" }, "destinations": { "type": "integer" }, "elements": { "type": "integer", "description": "Cells computed; what is billed." }, "mode": { "type": "string", "enum": [ "sync", "async" ] } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "matrix.compute", "billing": { "unit": "element_1k", "quantity": 0.002, "counted": true, "breakdown": { "origins": 1, "destinations": 2, "elements": 2, "engine_requests": 1 } }, "data": { "origins": [ "depot" ], "destinations": [ "order-1001", "order-1002" ], "distances_meters": [ [ 1840, 1611 ] ], "durations_seconds": [ [ 245, 227 ] ], "unreachable": [] }, "meta": { "region": "NA", "profile": "car", "metrics": [ "distance", "duration" ], "origins": 1, "destinations": 2, "elements": 2, "mode": "sync" } } } } }, "202": { "description": "Accepted: the work is queued as a job and billed now. Poll GET /v1/jobs/{jobId} (the `Location` header) and collect the result from `result_url`; a verified `callback` is called when it ends.", "headers": { "Location": { "description": "Where to poll for the job.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "matrix.compute" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "element_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "object", "description": "The job that will produce the result.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on this answer." }, "capability": { "type": "string", "description": "The capability the job runs." }, "poll_after_ms": { "type": "integer", "description": "How long to wait before the first poll." }, "result_url": { "type": "string", "description": "Where to collect the result once the job has succeeded." }, "cancel_url": { "type": "string", "description": "Where to cancel the job." } } } }, "required": [ "job" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "matrix.compute", "billing": { "unit": "element_1k", "quantity": 0.002, "counted": true, "breakdown": { "origins": 1, "destinations": 2, "elements": 2, "engine_requests": 1 } }, "data": { "job": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "queued", "capability": "matrix.compute", "poll_after_ms": 1000, "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel" } }, "meta": { "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "413": { "description": "The request body is too large. Upload large payloads as a reusable resource instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body is too large. Upload large payloads as a reusable resource instead.", "status": 413, "doc_url": "/developer/errors/REQUEST_TOO_LARGE" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "destinations": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] } }, "metrics": { "type": "array", "items": { "type": "string", "enum": [ "distance", "duration" ] } }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "origins": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] } }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] } }, "additionalProperties": false, "required": [ "destinations", "origins" ] }, "example": { "origins": [ { "id": "depot", "lat": 45.5017, "lng": -73.5673 } ], "destinations": [ { "id": "order-1001", "lat": 45.5088, "lng": -73.554 }, { "id": "order-1002", "lat": 45.4972, "lng": -73.5786 } ] } } } } } }, "/v1/network/site-scenario": { "post": { "operationId": "networkSite_scenario", "tags": [ "network" ], "summary": "Compare network scenarios", "description": "Routes up to seven `days` of your deliveries as they are (the base) and with each of up to three `scenarios`, and compares them. Give the `depots`, the `orders` (each with its `date`, and the `depot` that serves it, else the nearest one serves it), the `vehicles` per depot (a `count`, optionally per `date`, with shift hours and a package capacity), the `time_zone` and optionally the `driver_cost` (per hour, per km, per day, per delivery) in `currency`. A scenario holds up to three changes: `add_depot` (a new depot at `lat`, `lng` that takes the orders within `radius_km`, with its own `vehicles`), `fleet` (all depots, or one `depot`, at `factor_percent` of today's vehicles or a number of `vehicles`) and `shift` (`work_from` and `work_to`, for all depots or one). Every figure comes from a routed day: the base and each scenario give km, hours, vehicles, unassigned and late orders and a cost score (money only with `driver_cost`), and each scenario its difference from the base. Always answered as a job, usually within minutes and at most about twelve; a scenario not finished in that time comes back `routed: false`. One question of the Open Platform's runs at a time; another meanwhile is refused with CONCURRENCY_LIMIT. Nothing is applied anywhere. The planning engine keeps a question up to 24 hours. Billed one job.\n\nCompare your delivery days as they are with a new depot, a different fleet size or other shift hours.", "x-superroute-capability": "network.site_scenario", "x-superroute-billing-unit": "job", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/network.site_scenario", "responses": { "200": { "description": "The base and every scenario with their figures and their difference from the base. Collected from the job's result. Billed one job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "network.site_scenario" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "base": { "type": "object", "description": "The days routed as they are.", "properties": { "score": { "type": [ "number", "null" ], "description": "The cost score in `currency`: driver hours, distance and vehicles at the driver cost. Without `driver_cost` it holds no money." }, "km": { "type": [ "number", "null" ], "description": "Distance driven." }, "hours": { "type": [ "number", "null" ], "description": "Driver hours." }, "vehicles": { "type": [ "integer", "null" ], "description": "Vehicles used." }, "unassigned": { "type": [ "integer", "null" ], "description": "Orders left unrouted." }, "late": { "type": [ "integer", "null" ], "description": "Orders delivered after their window." } } }, "scenarios": { "type": "array", "description": "Every scenario, in the order given.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The scenario id, or its number from 1." }, "name": { "type": "string", "description": "The scenario name." }, "routed": { "type": "boolean", "description": "Whether the scenario was routed in time; false leaves its figures empty." }, "tier": { "type": [ "string", "null" ], "description": "How thoroughly it was routed: `balanced`, or `fast` when time ran short." }, "figures": { "type": "object", "description": "The days routed with the scenario's changes.", "properties": { "score": { "type": [ "number", "null" ], "description": "The cost score in `currency`: driver hours, distance and vehicles at the driver cost. Without `driver_cost` it holds no money." }, "km": { "type": [ "number", "null" ], "description": "Distance driven." }, "hours": { "type": [ "number", "null" ], "description": "Driver hours." }, "vehicles": { "type": [ "integer", "null" ], "description": "Vehicles used." }, "unassigned": { "type": [ "integer", "null" ], "description": "Orders left unrouted." }, "late": { "type": [ "integer", "null" ], "description": "Orders delivered after their window." } } }, "against_base": { "type": "object", "description": "The scenario's figures minus the base's; negative is less.", "properties": { "score": { "type": [ "number", "null" ], "description": "The cost score in `currency`: driver hours, distance and vehicles at the driver cost. Without `driver_cost` it holds no money." }, "km": { "type": [ "number", "null" ], "description": "Distance driven." }, "hours": { "type": [ "number", "null" ], "description": "Driver hours." }, "vehicles": { "type": [ "integer", "null" ], "description": "Vehicles used." }, "unassigned": { "type": [ "integer", "null" ], "description": "Orders left unrouted." }, "late": { "type": [ "integer", "null" ], "description": "Orders delivered after their window." } } } } } }, "currency": { "type": "string", "description": "The currency of every score." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "What the question lacked, e.g. `driver_cost`, `vehicle_shift`." } }, "required": [ "base", "scenarios", "currency" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "network.site_scenario", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "orders": 40, "depots": 2, "scenarios": 2 } }, "data": { "base": { "score": 260.57, "km": 153.3, "hours": 8, "vehicles": 2, "unassigned": 0, "late": 0 }, "scenarios": [ { "id": "east-depot", "name": "Depot in Anjou", "routed": true, "tier": "balanced", "figures": { "score": 267.86, "km": 161.8, "hours": 8.1, "vehicles": 3, "unassigned": 0, "late": 0 }, "against_base": { "score": 7.29, "km": 8.5, "hours": 0.1, "vehicles": 1, "unassigned": 0, "late": 0 } }, { "id": "bigger-fleet", "name": "Half as many vans again", "routed": true, "tier": "balanced", "figures": { "score": 260.57, "km": 153.3, "hours": 8, "vehicles": 2, "unassigned": 0, "late": 0 }, "against_base": { "score": 0, "km": 0, "hours": 0, "vehicles": 0, "unassigned": 0, "late": 0 } } ], "currency": "CAD", "missing": [] }, "meta": { "partial": false, "engine": "snet", "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "424": { "description": "The routing engine refused this problem. Its reason is included where available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_REJECTED", "message": "The routing engine refused this problem. Its reason is included where available.", "status": 424, "doc_url": "/developer/errors/ENGINE_REJECTED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } }, "504": { "description": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "SOLVE_TIMEOUT", "message": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "status": 504, "doc_url": "/developer/errors/SOLVE_TIMEOUT" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "days": { "type": "object", "properties": { "from": [], "to": [] }, "required": [ "from", "to" ] }, "depots": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "closes": [], "id": { "type": "string", "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "name": { "type": [ "string", "null" ], "maxLength": 128 }, "opens": [] }, "required": [ "id", "lat", "lng" ] } }, "driver_cost": { "type": [ "object", "null" ], "properties": { "fixed_daily": { "type": [ "number", "null" ], "minimum": 0 }, "per_delivery": { "type": [ "number", "null" ], "minimum": 0 }, "per_hour": { "type": [ "number", "null" ], "minimum": 0 }, "per_km": { "type": [ "number", "null" ], "minimum": 0 } } }, "orders": { "type": "array", "minItems": 1, "maxItems": 20000, "items": { "type": "object", "properties": { "date": [], "depot": { "type": [ "string", "null" ], "maxLength": 128 }, "id": { "type": "string", "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "packages": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "service_minutes": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 600 }, "window": { "type": [ "object", "null" ], "properties": { "from": { "description": "Required when orders.*.window is present." }, "to": { "description": "Required when orders.*.window is present." } } } }, "required": [ "date", "id", "lat", "lng" ] } }, "scenarios": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "properties": { "changes": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "properties": { "depot": { "type": [ "string", "null" ], "maxLength": 128 }, "factor_percent": { "type": [ "number", "null" ], "minimum": 10, "maximum": 500 }, "lat": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90 }, "lng": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180 }, "name": { "type": [ "string", "null" ], "maxLength": 128 }, "radius_km": { "type": [ "number", "null" ], "minimum": 0.1, "maximum": 200 }, "type": { "type": "string", "enum": [ "add_depot", "fleet", "shift" ] }, "vehicles": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000 }, "work_from": [], "work_to": [] }, "required": [ "type" ] } }, "id": { "type": [ "string", "null" ], "maxLength": 64 }, "name": { "type": "string", "maxLength": 128 } }, "required": [ "changes", "name" ] } }, "time_zone": [], "vehicles": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "capacity_packages": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "count": { "type": "integer", "minimum": 1, "maximum": 1000 }, "date": [], "depot": { "type": "string", "maxLength": 128 }, "work_from": [], "work_to": [] }, "required": [ "count", "depot" ] } } }, "additionalProperties": false, "required": [ "days", "depots", "orders", "scenarios", "time_zone", "vehicles" ] }, "example": { "time_zone": "America/Toronto", "currency": "CAD", "days": { "from": "2026-11-03", "to": "2026-11-03" }, "depots": [ { "id": "MTL-West", "name": "Montreal West", "lat": 45.4706, "lng": -73.7408 }, { "id": "MTL-Centre", "name": "Montreal Centre", "lat": 45.4972, "lng": -73.5786 } ], "orders": [ { "id": "SO-2001", "lat": 45.49524, "lng": -73.59163, "date": "2026-11-03", "packages": 2 }, { "id": "SO-2002", "lat": 45.49518, "lng": -73.55029, "date": "2026-11-03", "packages": 1 }, { "id": "SO-2003", "lat": 45.46847, "lng": -73.59833, "date": "2026-11-03", "packages": 3 }, { "id": "SO-2004", "lat": 45.5114, "lng": -73.64394, "date": "2026-11-03", "packages": 2 }, { "id": "SO-2005", "lat": 45.48034, "lng": -73.65731, "date": "2026-11-03", "packages": 3 }, { "id": "SO-2006", "lat": 45.51345, "lng": -73.58664, "date": "2026-11-03", "packages": 2 }, { "id": "SO-2007", "lat": 45.54648, "lng": -73.57845, "date": "2026-11-03", "packages": 3 }, { "id": "SO-2008", "lat": 45.51501, "lng": -73.58276, "date": "2026-11-03", "packages": 3 }, { "id": "SO-2009", "lat": 45.45632, "lng": -73.66501, "date": "2026-11-03", "packages": 1 }, { "id": "SO-2010", "lat": 45.50996, "lng": -73.56106, "date": "2026-11-03", "packages": 2 } ], "vehicles": [ { "depot": "MTL-West", "count": 2, "work_from": "08:00", "work_to": "17:00" }, { "depot": "MTL-Centre", "count": 2, "work_from": "08:00", "work_to": "17:00" } ], "driver_cost": { "per_hour": 24, "per_km": 0.45 }, "scenarios": [ { "id": "east-depot", "name": "Depot in Anjou", "changes": [ { "type": "add_depot", "name": "Anjou", "lat": 45.604, "lng": -73.56, "radius_km": 6, "vehicles": 1 } ] }, { "id": "bigger-fleet", "name": "Half as many vans again", "changes": [ { "type": "fleet", "factor_percent": 150 } ] } ] } } } } } }, "/v1/packing/solve": { "post": { "operationId": "packingSolve", "tags": [ "packing" ], "summary": "Choose cartons", "description": "Selects the packagings to use for a set of items and the allocation of items across them, ranked by total volume, package count and cost.\n\nChoose packaging and produce a 3D packing arrangement for a set of items.", "x-superroute-capability": "packing.solve", "x-superroute-billing-unit": "job", "x-superroute-release-stage": "beta", "x-superroute-async": true, "x-superroute-docs": "/developer/capabilities/packing.solve", "responses": { "200": { "description": "Ranked ways to pack the items into the packagings, each with the packages used, where every unit sits and the totals. Dimensions come back in millimetres and weights in grams. The example is shortened to the first candidate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "packing.solve" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "target_utilization_percent": { "type": "number", "description": "The utilization the solver aimed for." }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "1 is the recommended candidate." }, "strategy": { "type": "string", "description": "How it was built: `single:` (one packaging type) or `mixed`." }, "packages": { "type": "array", "items": { "type": "object", "properties": { "package_index": { "type": "integer", "description": "From 1." }, "packaging": { "type": "object", "properties": { "key": { "type": "string", "description": "The caller's packaging key." }, "name": { "type": [ "string", "null" ] }, "source_type": { "type": "string", "description": "Always `open` on this platform." }, "source_id": { "type": [ "integer", "null" ], "description": "Always null on this platform." }, "inner_length_mm": { "type": "integer" }, "inner_width_mm": { "type": "integer" }, "inner_height_mm": { "type": "integer" }, "outer_volume_mm3": { "type": "integer" }, "max_payload_g": { "type": "integer" }, "tare_weight_g": { "type": "integer" }, "unit_cost": { "type": [ "number", "null" ] } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" } } }, "description": "What goes in this package." }, "placements": { "type": "array", "items": { "type": "object", "properties": { "x_mm": { "type": "number", "description": "Position along the package length, from the inner rear-left-bottom corner." }, "y_mm": { "type": "number", "description": "Position along the width axis." }, "z_mm": { "type": "number", "description": "Height above the floor." }, "length_mm": { "type": "number", "description": "Footprint along x after rotation." }, "width_mm": { "type": "number", "description": "Footprint along y after rotation." }, "height_mm": { "type": "number", "description": "Extent along z after rotation." }, "rotation_key": { "type": "string", "description": "How the item was turned: the order its own length (L), width (W) and height (H) take along x, y and z." }, "stack_level": { "type": "integer", "description": "1 on the floor, 2 on top of one item, and so on." }, "container_index": { "type": "integer", "description": "Which container or package, from 1." }, "unit_sequence": { "type": "integer", "description": "Loading order within the container, from 1." }, "unit_key": { "type": "string", "description": "Identifies the unit: `item-{row}-{n}`, row and unit counted from 1." }, "item_id": { "type": "string", "description": "The caller's item id." }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "weight_g": { "type": "number", "description": "Weight of the unit." }, "cargo_form": { "type": "string", "description": "`loose`, or `pallet` for a unit built on a pallet." }, "source_item_count": { "type": "integer", "description": "Items the unit stands for (above 1 for a built pallet)." }, "pallet_group_key": { "type": [ "string", "null" ], "description": "The pallet this unit was built into, when palletized." }, "metadata": { "type": "object", "description": "The item's handling rules as the solver applied them.", "properties": { "stackable": { "type": "boolean" }, "max_stack_layers": { "type": [ "integer", "null" ] }, "bearing_level": { "type": [ "integer", "null" ] }, "allowed_orientations": { "type": "array", "items": { "type": "string" }, "description": "The rotations this item may take." }, "stack_level": { "type": "integer" } } } } }, "description": "One entry per unit." }, "metrics": { "type": "object", "properties": { "unit_count": { "type": "integer" }, "packed_volume_mm3": { "type": "integer" }, "inner_volume_mm3": { "type": "integer" }, "utilization_percent": { "type": "number" }, "net_weight_g": { "type": "integer" }, "gross_weight_g": { "type": "integer", "description": "Net weight plus tare." }, "gravity": { "type": "object", "description": "Centre of gravity of the packed contents.", "properties": { "cog_x_mm": { "type": "number" }, "cog_y_mm": { "type": "number" }, "cog_z_mm": { "type": "number" }, "offset_x_percent": { "type": "number", "description": "Centre of gravity off the middle along x, in percent of the length." }, "offset_y_percent": { "type": "number" }, "cog_height_percent": { "type": "number" }, "balanced": { "type": "boolean" } } } } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean", "description": "An independent check found no overlap and nothing outside the package." }, "version": { "type": "string" } } }, "checksum": { "type": "string", "description": "Identifies this exact package layout." } } } }, "unplaced": { "type": "array", "items": { "type": "object", "properties": [], "additionalProperties": true }, "description": "Units no package could take." }, "totals": { "type": "object", "properties": { "package_count": { "type": "integer" }, "total_outer_volume_mm3": { "type": "integer" }, "total_inner_volume_mm3": { "type": "integer" }, "packed_volume_mm3": { "type": "integer" }, "wasted_volume_mm3": { "type": "integer" }, "overall_utilization_percent": { "type": "number" }, "total_net_weight_g": { "type": "integer" }, "total_gross_weight_g": { "type": "integer" }, "total_cost": { "type": [ "number", "null" ], "description": "Sum of the packagings' `unit_cost`." }, "unplaced_quantity": { "type": "integer" } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Codes of what this candidate falls short on." } } } } } }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "packing.solve", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "packagings": 2, "item_rows": 2, "units": 5 } }, "data": { "target_utilization_percent": 85, "candidates": [ { "rank": 1, "strategy": "single:box-m", "packages": [ { "package_index": 1, "packaging": { "key": "box-m", "name": "Medium box", "source_type": "open", "source_id": null, "inner_length_mm": 400, "inner_width_mm": 300, "inner_height_mm": 300, "outer_volume_mm3": 36000000, "max_payload_g": 20000, "tare_weight_g": 0, "unit_cost": 1.2 }, "items": [ { "item_id": "SKU-2", "name": "Kettle", "sku": null, "quantity": 1 }, { "item_id": "SKU-1", "name": "Mug", "sku": null, "quantity": 4 } ], "placements": [ { "x_mm": 0, "y_mm": 0, "z_mm": 0, "length_mm": 250, "width_mm": 200, "height_mm": 250, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 1, "unit_key": "item-2-5", "item_id": "SKU-2", "name": "Kettle", "sku": null, "weight_g": 1500, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "LHW" ], "stack_level": 1 } }, { "x_mm": 0, "y_mm": 200, "z_mm": 0, "length_mm": 120, "width_mm": 100, "height_mm": 100, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 2, "unit_key": "item-1-1", "item_id": "SKU-1", "name": "Mug", "sku": null, "weight_g": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "WHL" ], "stack_level": 1 } }, { "x_mm": 120, "y_mm": 200, "z_mm": 0, "length_mm": 120, "width_mm": 100, "height_mm": 100, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 3, "unit_key": "item-1-2", "item_id": "SKU-1", "name": "Mug", "sku": null, "weight_g": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "WHL" ], "stack_level": 1 } }, { "x_mm": 250, "y_mm": 0, "z_mm": 0, "length_mm": 120, "width_mm": 100, "height_mm": 100, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 4, "unit_key": "item-1-3", "item_id": "SKU-1", "name": "Mug", "sku": null, "weight_g": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "WHL" ], "stack_level": 1 } }, { "x_mm": 250, "y_mm": 100, "z_mm": 0, "length_mm": 120, "width_mm": 100, "height_mm": 100, "rotation_key": "LWH", "stack_level": 1, "container_index": 1, "unit_sequence": 5, "unit_key": "item-1-4", "item_id": "SKU-1", "name": "Mug", "sku": null, "weight_g": 400, "cargo_form": "loose", "source_item_count": 1, "pallet_group_key": null, "metadata": { "stackable": true, "max_stack_layers": null, "bearing_level": null, "allowed_orientations": [ "LWH", "WLH", "WHL" ], "stack_level": 1 } } ], "metrics": { "unit_count": 5, "packed_volume_mm3": 17300000, "inner_volume_mm3": 36000000, "utilization_percent": 48.056, "net_weight_g": 3100, "gross_weight_g": 3100, "gravity": { "cog_x_mm": 171.5, "cog_y_mm": 138.7, "cog_z_mm": 86.3, "offset_x_percent": 14.27, "offset_y_percent": 7.53, "cog_height_percent": 28.76, "balanced": true } }, "validation": { "passed": true, "version": "independent-aabb-1.3" }, "checksum": "9fdc5c755fec1f510d77baa4a8aa726475f0545da45cd171cc9e43ff640ad0d1" } ], "unplaced": [], "totals": { "package_count": 1, "total_outer_volume_mm3": 36000000, "total_inner_volume_mm3": 36000000, "packed_volume_mm3": 17300000, "wasted_volume_mm3": 18700000, "overall_utilization_percent": 48.056, "total_net_weight_g": 3100, "total_gross_weight_g": 3100, "total_cost": 1.2, "unplaced_quantity": 0 }, "warnings": [] } ], "unpackable": [] }, "meta": { "solver_version": "packing-selection-1.0", "validator_version": "independent-aabb-1.3", "units": { "dimensions": "cm", "weight": "kg" }, "mode": "sync" } } } } }, "202": { "description": "Accepted: the work is queued as a job and billed now. Poll GET /v1/jobs/{jobId} (the `Location` header) and collect the result from `result_url`; a verified `callback` is called when it ends.", "headers": { "Location": { "description": "Where to poll for the job.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "packing.solve" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "object", "description": "The job that will produce the result.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on this answer." }, "capability": { "type": "string", "description": "The capability the job runs." }, "poll_after_ms": { "type": "integer", "description": "How long to wait before the first poll." }, "result_url": { "type": "string", "description": "Where to collect the result once the job has succeeded." }, "cancel_url": { "type": "string", "description": "Where to cancel the job." } } } }, "required": [ "job" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "packing.solve", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "packagings": 2, "item_rows": 2, "units": 5 } }, "data": { "job": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "queued", "capability": "packing.solve", "poll_after_ms": 1000, "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel" } }, "meta": { "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "can_rotate": { "type": [ "boolean", "null" ] }, "height_cm": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "length_cm": { "type": "number", "exclusiveMinimum": 0 }, "max_stack_layers": { "type": [ "integer", "null" ], "minimum": 1 }, "name": { "type": [ "string", "null" ], "maxLength": 191 }, "orientation": { "type": [ "string", "null" ], "enum": [ "any", "upright_only", "side_only" ] }, "quantity": { "type": [ "integer", "null" ], "minimum": 1 }, "sku": { "type": [ "string", "null" ], "maxLength": 128 }, "stackable": { "type": [ "boolean", "null" ] }, "weight_kg": { "type": [ "number", "null" ], "minimum": 0 }, "width_cm": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "height_cm", "length_cm", "width_cm" ] } }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "packagings": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "inner_height_cm": { "type": "number", "exclusiveMinimum": 0 }, "inner_length_cm": { "type": "number", "exclusiveMinimum": 0 }, "inner_width_cm": { "type": "number", "exclusiveMinimum": 0 }, "key": { "type": [ "string", "null" ], "maxLength": 128 }, "max_payload_kg": { "type": [ "number", "null" ], "minimum": 0 }, "name": { "type": [ "string", "null" ], "maxLength": 191 }, "outer_volume_cm3": { "type": [ "number", "null" ], "minimum": 0 }, "quantity_limit": { "type": [ "integer", "null" ], "minimum": 1 }, "tare_weight_kg": { "type": [ "number", "null" ], "minimum": 0 }, "unit_cost": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "inner_height_cm", "inner_length_cm", "inner_width_cm" ] } }, "target_utilization_percent": { "type": [ "number", "null" ], "minimum": 1, "maximum": 100 } }, "additionalProperties": false, "required": [ "items", "packagings" ] }, "example": { "packagings": [ { "key": "box-m", "name": "Medium box", "inner_length_cm": 40, "inner_width_cm": 30, "inner_height_cm": 30, "max_payload_kg": 20, "unit_cost": 1.2 }, { "key": "box-s", "name": "Small box", "inner_length_cm": 25, "inner_width_cm": 20, "inner_height_cm": 15, "max_payload_kg": 10, "unit_cost": 0.6 } ], "items": [ { "id": "SKU-1", "name": "Mug", "quantity": 4, "length_cm": 12, "width_cm": 10, "height_cm": 10, "weight_kg": 0.4 }, { "id": "SKU-2", "name": "Kettle", "quantity": 1, "length_cm": 25, "width_cm": 20, "height_cm": 25, "weight_kg": 1.5 } ] } } } } } }, "/v1/picking/batch": { "post": { "operationId": "pickingBatch", "tags": [ "picking" ], "summary": "Batch picks", "description": "Groups the submitted orders into pick batches (carts) and returns, for each batch, its orders and the stops in walking order with what to pick at each. Every order line names its bin in `location`; give the bins in `locations` with their `position` in metres along the pick path, or in `matrix` with the metres between every pair. Picking starts and ends at `start` and `end` (on a path, at position 0 when not given). `limits` caps each batch by `weight_kg`, `volume_l`, `orders`, `skus`, `units` and `slots` (the cart's order slots); `group_by` keeps orders with different values of the named attributes apart, and `rules` give orders matching a condition their own batch, their own limits, or leave them out. `objective` is `walk` (shortest total walk, the default), `batches` (fewest batches) or `balance` (even batches). `sorting` is `in_cart` (each order in its own slot) or `after_pick` (sorted after picking). `fixed_batches` evaluates batches as given: walk order, totals and `over_limits`. Orders that fit no batch are listed in `unplaced` with the reason. Nothing is stored. Billed one job.\n\nGroup warehouse orders into pick batches and receive the walk through the bins for each batch.", "x-superroute-capability": "picking.batch", "x-superroute-billing-unit": "job", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/picking.batch", "responses": { "200": { "description": "The pick batches with the walk through the bins for each, and the orders that fit no batch. Billed one job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "picking.batch" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "job" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "batches": { "type": "array", "description": "The pick batches, in the order they were made.", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "The batch's number, from 1." }, "kind": { "type": "string", "enum": [ "in_cart", "after_pick", "single_piece" ], "description": "How the batch is sorted: `in_cart` (each order in its own slot), `after_pick` (sorted after picking) or `single_piece` (orders of one unit of one SKU, grouped by SKU)." }, "orders": { "type": "array", "items": { "type": "string" }, "description": "The orders in the batch, in slot order." }, "stops": { "type": "array", "description": "The bins in walking order, with what to pick at each.", "items": { "type": "object", "properties": { "location": { "type": "string", "description": "The bin id." }, "picks": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "string", "description": "The order the units are for." }, "sku": { "type": "string", "description": "The SKU." }, "quantity": { "type": "integer", "description": "Units to pick." }, "slot": { "type": "integer", "description": "The cart slot of the order, from 1. Absent when the batch is sorted after picking." }, "package": { "type": "integer", "description": "The order's package (from 1, in the order of `packages`) the units go in. Present only when the order gave packages." } } } } } } }, "walk_meters": { "type": "number", "description": "The walk from `start` through every stop to `end`, in metres (in the matrix's unit when a matrix was given)." }, "weight_kg": { "type": "number", "description": "Total weight of the batch." }, "volume_l": { "type": "number", "description": "Total volume of the batch." }, "units": { "type": "integer", "description": "Units in the batch." }, "skus": { "type": "integer", "description": "Different SKUs in the batch." }, "group": { "type": "object", "description": "The `group_by` values the batch's orders share, and `rule` when a rule made the batch." }, "over_limits": { "type": "array", "items": { "type": "string" }, "description": "The limits a fixed batch exceeds. Present only with `fixed_batches`." } } } }, "unplaced": { "type": "array", "description": "Orders not placed in any batch.", "items": { "type": "object", "properties": { "order": { "type": "string", "description": "The order id." }, "reason": { "type": "string", "enum": [ "excluded", "too_large", "bad_location" ], "description": "`excluded`: a rule left it out; `too_large`: the order alone exceeds a limit; `bad_location`: a line could not be placed on the pick path." } } } }, "totals": { "type": "object", "properties": { "batches": { "type": "integer", "description": "Number of batches." }, "orders": { "type": "integer", "description": "Orders placed." }, "walk_meters": { "type": "number", "description": "The walks of all batches together." } } } }, "required": [ "batches", "unplaced", "totals" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "picking.batch", "billing": { "unit": "job", "quantity": 1, "counted": true, "breakdown": { "orders": 5, "lines": 7 } }, "data": { "batches": [ { "number": 1, "kind": "in_cart", "orders": [ "SO-1001", "SO-1002", "SO-1005" ], "stops": [ { "location": "A-01-02", "picks": [ { "order": "SO-1001", "sku": "MUG-BLUE", "quantity": 2, "slot": 1 } ] }, { "location": "C-04-01", "picks": [ { "order": "SO-1001", "sku": "TEA-50", "quantity": 1, "slot": 1 }, { "order": "SO-1002", "sku": "TEA-50", "quantity": 3, "slot": 2 } ] }, { "location": "D-01-01", "picks": [ { "order": "SO-1005", "sku": "SPOON-SET", "quantity": 1, "slot": 3 } ] } ], "walk_meters": 92, "weight_kg": 1.9, "volume_l": 4.2, "units": 7, "skus": 3, "group": { "carrier": "canada_post" } }, { "number": 2, "kind": "in_cart", "orders": [ "SO-1003", "SO-1004" ], "stops": [ { "location": "A-01-02", "picks": [ { "order": "SO-1003", "sku": "MUG-BLUE", "quantity": 1, "slot": 1 } ] }, { "location": "B-02-03", "picks": [ { "order": "SO-1003", "sku": "KETTLE", "quantity": 1, "slot": 1 }, { "order": "SO-1004", "sku": "KETTLE", "quantity": 2, "slot": 2 } ] } ], "walk_meters": 36, "weight_kg": 5.2, "volume_l": 18.9, "units": 4, "skus": 2, "group": { "carrier": "ups" } } ], "unplaced": [], "totals": { "batches": 2, "orders": 5, "walk_meters": 128 } }, "meta": { "distances": "path", "solve_ms": 1, "units": { "walk": "m", "weight": "kg", "volume": "L" }, "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "end": { "type": [ "string", "null" ], "maxLength": 128 }, "fixed_batches": { "type": "array", "maxItems": 5000, "items": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 128 } }, "description": "Batches to evaluate as given, each a list of order ids: no search; walk, totals and `over_limits` are returned." }, "group_by": { "type": "array", "maxItems": 5, "items": { "type": "string" }, "description": "Order attributes whose values must match within a batch (carrier, cutoff, route ...), at most 5." }, "limits": { "type": [ "object", "null" ], "properties": { "orders": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "skus": { "type": [ "integer", "null" ], "minimum": 1 }, "slots": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "units": { "type": [ "integer", "null" ], "minimum": 1 }, "volume_l": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "weight_kg": { "type": [ "number", "null" ], "exclusiveMinimum": 0 } }, "description": "Per batch: `weight_kg`, `volume_l`, `orders`, `skus`, `units`, `slots` (the cart's order slots)." }, "locations": { "type": "array", "minItems": 1, "maxItems": 20000, "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128 }, "position": { "type": "number", "minimum": 0 } }, "required": [ "id", "position" ] }, "description": "The bins, each `{id, position}`: its distance in metres along the pick path. Give these or `matrix`." }, "matrix": { "type": [ "object", "null" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 2000, "description": "Required when matrix is present.", "items": { "type": "string", "maxLength": 128 } }, "meters": { "type": "array", "description": "Required when matrix is present.", "items": { "type": "array", "items": { "type": "number", "minimum": 0 } } } }, "description": "`{ids, meters}`: the bin ids and the walking metres between every pair, one row per id. With a matrix, name `start`." }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "objective": { "type": [ "string", "null" ], "enum": [ "walk", "batches", "balance" ] }, "orders": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "type": "object", "properties": { "attributes": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "location": { "type": "string", "maxLength": 128 }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "sku": { "type": "string", "maxLength": 128 }, "volume_l": { "type": [ "number", "null" ], "minimum": 0 }, "weight_kg": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "location", "sku" ] } }, "packages": { "type": "array", "maxItems": 100, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "quantity": { "type": [ "integer", "null" ], "minimum": 1 }, "sku": { "type": "string", "maxLength": 128 } }, "required": [ "sku" ] } } } }, "required": [ "id", "lines", "packages" ] } }, "rules": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 64 }, "then": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "own_batch", "exclude", "limits" ] }, "limits": { "type": [ "object", "null" ], "properties": { "orders": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "skus": { "type": [ "integer", "null" ], "minimum": 1 }, "slots": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "units": { "type": [ "integer", "null" ], "minimum": 1 }, "volume_l": { "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "weight_kg": { "type": [ "number", "null" ], "exclusiveMinimum": 0 } } } }, "required": [ "action" ] }, "when": { "type": "array" } }, "required": [ "then", "when" ] }, "description": "Each `{name?, when, then}`: `when` is `{field, op, value}` or `{all: [...]}` / `{any: [...]}` (at most 4 deep, 30 conditions); fields are `weight_kg`, `volume_l`, `units`, `lines`, `skus` or an attribute; `op` is eq, ne, gt, ge, lt, le, in or contains; `then.action` is `own_batch`, `exclude` or `limits` with `then.limits`." }, "single_piece_batches": { "type": [ "boolean", "null" ] }, "sorting": { "type": [ "string", "null" ], "enum": [ "in_cart", "after_pick" ] }, "start": { "type": [ "string", "null" ], "maxLength": 128 }, "time_limit_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 30, "description": "How long the search may take, 1-30 seconds, default 2." } }, "additionalProperties": false, "required": [ "locations", "orders", "rules" ] }, "example": { "orders": [ { "id": "SO-1001", "lines": [ { "sku": "MUG-BLUE", "quantity": 2, "location": "A-01-02", "weight_kg": 0.4, "volume_l": 0.9 }, { "sku": "TEA-50", "location": "C-04-01", "weight_kg": 0.2, "volume_l": 0.5 } ], "attributes": { "carrier": "canada_post" } }, { "id": "SO-1002", "lines": [ { "sku": "TEA-50", "quantity": 3, "location": "C-04-01", "weight_kg": 0.2, "volume_l": 0.5 } ], "attributes": { "carrier": "canada_post" } }, { "id": "SO-1003", "lines": [ { "sku": "KETTLE", "location": "B-02-03", "weight_kg": 1.6, "volume_l": 6 }, { "sku": "MUG-BLUE", "location": "A-01-02", "weight_kg": 0.4, "volume_l": 0.9 } ], "attributes": { "carrier": "ups" } }, { "id": "SO-1004", "lines": [ { "sku": "KETTLE", "quantity": 2, "location": "B-02-03", "weight_kg": 1.6, "volume_l": 6 } ], "attributes": { "carrier": "ups" } }, { "id": "SO-1005", "lines": [ { "sku": "SPOON-SET", "location": "D-01-01", "weight_kg": 0.3, "volume_l": 0.4 } ], "attributes": { "carrier": "canada_post" } } ], "locations": [ { "id": "A-01-02", "position": 4 }, { "id": "B-02-03", "position": 18 }, { "id": "C-04-01", "position": 31 }, { "id": "D-01-01", "position": 46 } ], "limits": { "orders": 3, "weight_kg": 15, "slots": 3 }, "group_by": [ "carrier" ], "single_piece_batches": false } } } } } }, "/v1/plan/insert": { "post": { "operationId": "planInsert", "tags": [ "plan" ], "summary": "Insert jobs", "description": "Places the jobs in `insert` (1-20), in the order given, each at the position that keeps the plan within its stated rules and adds the least driver time (`objective` `duration`, driving plus waiting) or distance (`distance`); nothing else in the plan is re-ordered. The plan is given as for plan re-costing, with an `id` on every vehicle and job and a `start` on every vehicle. The plan with the jobs placed is priced exactly as plan re-costing prices it. The answer adds `plan`, the plan in the shape it is sent, and `insert`: per job, whether it was `placed`, and up to `limit` choices, best first (route, position, the stop it follows, added distance, driving and waiting time, arrival), each measured on the road. A job no position can take is left unassigned. With `matrix`, a distance snapshot, the positions are ranked on its road matrix; without one, the positions beside the `nearest` stops are measured. Nothing is stored. Billed per node: the stops of the plan plus the new jobs.\n\nPlace new jobs in a plan you hold at their cheapest positions, without re-planning the rest, and receive the plan priced with the positions to choose from.", "x-superroute-capability": "plan.insert", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.insert", "responses": { "200": { "description": "The plan with the new jobs placed, priced and judged as plan re-costing prices it, the plan itself in `plan`, and per new job the positions found, each measured on the road.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.insert" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "plan": { "type": "object", "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stops": { "type": "array", "items": { "type": "string" } } }, "required": [ "vehicle_id", "stops" ] } }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "Every job of the plan that is on no route." } }, "required": [ "routes", "unassigned" ] }, "insert": { "type": "array", "description": "One entry per new job, in the order placed.", "items": { "type": "object", "properties": { "job": { "type": "string" }, "placed": { "type": "boolean", "description": "Whether the job was placed; a job no position can take stays in `plan.unassigned`." }, "reason": { "type": "string", "enum": [ "no_vehicle", "no_feasible_position" ], "description": "Why the job was not placed. Present only when `placed` is false." }, "choices": { "type": "array", "items": { "type": "object", "properties": { "feasible": { "type": "boolean", "description": "Whether the plan keeps every stated rule with the job here." }, "vehicle_id": { "type": "string" }, "position": { "type": "integer", "description": "Where the job goes in the route, from 1, in driving order." }, "after": { "type": [ "string", "null" ], "description": "The stop the job follows; null right after the start." }, "added_distance_meters": { "type": "integer", "description": "Distance the route gains, measured on the road." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the route gains." }, "added_waiting_seconds": { "type": "integer", "description": "Waiting time the route gains." }, "arrival": { "type": [ "string", "null" ], "description": "When the job is reached. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Waiting at the job before its time window opens." }, "service_start": { "type": [ "string", "null" ], "description": "When work at the job begins: arrival plus waiting. ISO 8601 with offset." }, "violations": { "type": "array", "items": { "type": "object" }, "description": "What the plan breaks with the job here. Present only when `feasible` is false." } }, "required": [ "feasible", "vehicle_id", "position", "added_distance_meters", "added_duration_seconds" ] }, "description": "Up to `limit` positions, best first: the first is where the job was placed." } }, "required": [ "job", "placed", "choices" ] } } }, "required": [ "routes", "summary", "plan", "insert" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." }, "objective": { "type": "string", "description": "`duration` or `distance`." }, "limit": { "type": "integer", "description": "Choices returned per job." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.insert", "billing": { "unit": "node", "quantity": 4, "counted": true, "breakdown": { "planned_stops": 3, "new_jobs": 1 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 6, "task_count": 4, "distance_meters": 12865, "duration_seconds": 1664, "service_seconds": 1200, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T10:17:44-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1840, "leg_duration_seconds": 245, "leg_geometry": null, "arrival": "2026-10-23T09:34:05-04:00", "arrival_epoch": 1792762445, "distance_meters": 1840, "duration_seconds": 245 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "leg_distance_meters": 3108, "leg_duration_seconds": 390, "leg_geometry": null, "arrival": "2026-10-23T09:45:35-04:00", "arrival_epoch": 1792763135, "distance_meters": 4948, "duration_seconds": 635 }, { "type": "job", "id": "order-1003", "sequence": 3, "reachable": true, "leg_distance_meters": 4326, "leg_duration_seconds": 551, "leg_geometry": null, "arrival": "2026-10-23T09:59:46-04:00", "arrival_epoch": 1792763986, "distance_meters": 9274, "duration_seconds": 1186 }, { "type": "job", "id": "order-1005", "sequence": 4, "reachable": true, "leg_distance_meters": 1512, "leg_duration_seconds": 218, "leg_geometry": null, "arrival": "2026-10-23T10:08:24-04:00", "arrival_epoch": 1792764504, "distance_meters": 10786, "duration_seconds": 1404 }, { "type": "end", "reachable": true, "leg_distance_meters": 2079, "leg_duration_seconds": 260, "leg_geometry": null, "arrival": "2026-10-23T10:17:44-04:00", "arrival_epoch": 1792765064, "distance_meters": 12865, "duration_seconds": 1664 } ] } ], "summary": { "routes": 1, "tasks": 4, "distance_meters": 12865, "duration_seconds": 1664, "unreachable_legs": 0, "violations": 0 }, "plan": { "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1003", "order-1005" ] } ], "unassigned": [ "order-1004" ] }, "insert": [ { "job": "order-1005", "placed": true, "choices": [ { "feasible": true, "vehicle_id": "van-1", "position": 4, "after": "order-1003", "added_distance_meters": 82, "added_duration_seconds": 44, "added_waiting_seconds": 0, "arrival": "2026-10-23T10:08:24-04:00", "waiting_seconds": 0, "service_start": "2026-10-23T10:08:24-04:00" }, { "feasible": true, "vehicle_id": "van-1", "position": 3, "after": "order-1002", "added_distance_meters": 766, "added_duration_seconds": 118, "added_waiting_seconds": 0, "arrival": "2026-10-23T09:56:57-04:00", "waiting_seconds": 0, "service_start": "2026-10-23T09:56:57-04:00" } ] } ] }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "objective": "duration", "limit": 2, "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "insert": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "time_windows": { "type": [ "array", "null" ] } }, "required": [ "id", "location" ] }, "description": "The jobs to place, 1-20, in the order they are placed: each like a job of `jobs`, with an id no job of the plan has. Each is searched for in the plan with the jobs placed before it." }, "jobs": { "type": "array", "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10, "description": "How many positions to return per job, best first, 1-10, default 3." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. The candidates are ranked on its road matrix and every leg answered is read from it or measured and added; every distance and time answered is an exact road leg, with or without it, and the call is billed the same. An expired, unknown or unreachable snapshot is not an error: the call searches without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "nearest": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50, "description": "Without a usable `matrix`: the positions tried are those beside this many stops nearest to the job by straight line, 1-50, default 25, and the only position of every empty route. With a snapshot the positions are ranked on its road matrix instead." }, "objective": { "type": [ "string", "null" ], "enum": [ "duration", "distance" ], "description": "`duration` (default): the position adding the least driver time, driving plus waiting. `distance`: the position adding the least distance." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "insert", "jobs", "routes", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } }, { "id": "order-1004", "location": { "lat": 45.5302, "lng": -73.6125 }, "service_seconds": 300, "amount": { "parcels": 2 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1003" ] } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "insert": [ { "id": "order-1005", "location": { "lat": 45.5149, "lng": -73.5734 }, "service_seconds": 300, "amount": { "parcels": 1 } } ], "limit": 2 } } } } } }, "/v1/plan/matrix": { "post": { "operationId": "planMatrixOpen", "tags": [ "platform" ], "summary": "Open a distance snapshot", "description": "Opens a distance snapshot for editing one plan, for a `region` (default NA) and a vehicle `profile` (default car). Send the answered `matrix` id with plan re-costing, plan validation, route reordering, stop moves and stop removal of the same region and profile: a road leg measured once is then read from the snapshot and only new legs are measured. Every answer is the same as without the snapshot and is billed the same; the `X-Plan-Matrix` response header says whether the snapshot was used. A snapshot holds the plan's points and their legs only. It is removed one hour after its last use, and eight hours after it was opened at the latest. A refused opening answers SNAPSHOT_LIMIT_REACHED with the limit reached in `limit`. Free; available to an account with any plan capability.\n\nUpload a fleet, depot or plan once and reference it by id.", "x-superroute-capability": "platform.resources", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.resources", "responses": { "200": { "description": "A distance snapshot for editing one plan. Name it as `matrix` in plan calls of the same region and profile. Free.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "platform.resources" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "free" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "matrix": { "type": "string", "description": "The snapshot id, `.`: 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" } } } }, "required": [ "request_id", "data" ] }, "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" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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." } } }, "description": "Optional: the points of the plan (every job location and vehicle start and end), `{lat, lng}` each. The road legs between them are measured into the snapshot in the background, so the first edits find them held. Free. Only the first 2,000 points are used; an entry that is not a coordinate is left out. The opening is never refused for this field and answers the same with or without it." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply. The snapshot is for plan calls of this profile; a plan call of another region or profile does not use it." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plans the snapshot is for. Default NA." } }, "additionalProperties": false }, "example": { "region": "NA", "profile": "car", "points": [ { "lat": 45.5017, "lng": -73.5673 }, { "lat": 45.5088, "lng": -73.554 }, { "lat": 45.4972, "lng": -73.5786 } ] } } } } } }, "/v1/plan/matrix/{matrixId}": { "delete": { "operationId": "planMatrixCloseDelete", "tags": [ "platform" ], "summary": "Close a distance snapshot", "description": "Removes a distance snapshot at once. `closed` is false when it was already gone. Free; available to an account with any plan capability.\n\nUpload a fleet, depot or plan once and reference it by id.", "x-superroute-capability": "platform.resources", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.resources", "responses": { "200": { "description": "The snapshot is removed at once. `closed` is false when it was already gone (expired, removed or never opened by this account). Free.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "platform.resources" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "free" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "matrix": { "type": "string" }, "closed": { "type": "boolean", "description": "True when this call removed it." } }, "required": [ "matrix", "closed" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "platform.resources", "billing": { "unit": "free", "quantity": 0, "counted": false }, "data": { "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "closed": true } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "parameters": [ { "name": "matrixId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/plan/matrix/{matrixId}/points": { "post": { "operationId": "planMatrixPoints", "tags": [ "platform" ], "summary": "Measure new points of a distance snapshot", "description": "Names new points of a distance snapshot, such as a stop dropped on the map or an address chosen for insertion. Their road legs are measured into the snapshot at once, so the next insert or move finds them. The answer is sent at once; with `wait_ms` (up to 1000) it is sent once the legs are held or the time has run out, and `ready` says which. Entries that are not a coordinate are left out, and at most 50 points are used per call. An unknown or expired snapshot, or one of another account, answers RESOURCE_EXPIRED. Free; available to an account with any plan capability.\n\nUpload a fleet, depot or plan once and reference it by id.", "x-superroute-capability": "platform.resources", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.resources", "responses": { "200": { "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "platform.resources" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "free" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "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" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "platform.resources", "billing": { "unit": "free", "quantity": 0, "counted": false }, "data": { "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "queued": 1, "ready": true } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "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" ] }, "description": "The new points, `{lat, lng}` each: a stop dropped on the map, an address picked to insert. Their road legs to and from the snapshot's points (every point while the snapshot has at most 80, else the 30 nearest and every vehicle start and end) are measured into the snapshot at once. At most 50 a call; more are left out, as is an entry that is not a coordinate. A point already queued or held is not measured again. Free." }, "wait_ms": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000, "description": "Milliseconds to wait for the legs to be held before answering, 0 to 1000 (a larger value is held to 1000). Default 0: answer at once. `ready` says whether every point's legs were held when the answer was sent." } }, "additionalProperties": false, "required": [ "points" ] }, "example": { "points": [ { "lat": 45.5231, "lng": -73.5817 } ], "wait_ms": 1000 } } } }, "parameters": [ { "name": "matrixId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/plan/move": { "post": { "operationId": "planMove", "tags": [ "plan" ], "summary": "Move stops", "description": "Moves the jobs in `stops`, in the order given, to the route of `vehicle_id` as one block at `position` (1 = first, counted without the moved stops; omitted = after the last stop). A stop may come from any route, the target route included, or be a job on no route. The edited plan is priced exactly as plan re-costing prices it. The answer adds `plan`, the edited plan in the shape it is sent, and `move`: where each stop came from, and `feasible`, true when the routes the move touched keep every stated rule. Violations are reported, never refused. An optional `matrix`, a distance snapshot, makes repeated calls on the same plan faster; the answer is the same. Nothing is stored. Billed per node: the stops priced.\n\nMove stops of a plan you hold to a route at a chosen position and receive the edited plan priced, with whether the routes it touched keep their rules.", "x-superroute-capability": "plan.move", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.move", "responses": { "200": { "description": "The plan with the stops moved, priced and judged as plan re-costing prices it, the edited plan in `plan`, and whether the routes the move touched keep every stated rule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.move" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "plan": { "type": "object", "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stops": { "type": "array", "items": { "type": "string" } } }, "required": [ "vehicle_id", "stops" ] } }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "Every job of the plan that is on no route." } }, "required": [ "routes", "unassigned" ] }, "move": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "position": { "type": "integer", "description": "Where the first moved stop now is in its route, from 1." }, "stops": { "type": "array", "items": { "type": "string" } }, "from": { "type": "array", "description": "Where each moved stop was: its vehicle and position, both null for a job that was on no route.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "vehicle_id": { "type": [ "string", "null" ] }, "position": { "type": [ "integer", "null" ] } } } }, "feasible": { "type": "boolean", "description": "True when the routes the move touched (the target route and every route a stop came from) have no violation." }, "violations": { "type": "integer", "description": "Violations on the routes the move touched." } }, "required": [ "vehicle_id", "position", "stops", "from", "feasible", "violations" ] } }, "required": [ "routes", "summary", "plan", "move" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.move", "billing": { "unit": "node", "quantity": 3, "counted": true, "breakdown": { "tasks": 3, "routes": 2 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 4, "task_count": 2, "distance_meters": 6246, "duration_seconds": 822, "service_seconds": 600, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T09:53:42-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1759, "leg_duration_seconds": 231, "leg_geometry": null, "arrival": "2026-10-23T09:33:51-04:00", "arrival_epoch": 1792762431, "distance_meters": 1759, "duration_seconds": 231 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "leg_distance_meters": 3120, "leg_duration_seconds": 411, "leg_geometry": null, "arrival": "2026-10-23T09:45:42-04:00", "arrival_epoch": 1792763142, "distance_meters": 4879, "duration_seconds": 642 }, { "type": "end", "reachable": true, "leg_distance_meters": 1367, "leg_duration_seconds": 180, "leg_geometry": null, "arrival": "2026-10-23T09:53:42-04:00", "arrival_epoch": 1792763622, "distance_meters": 6246, "duration_seconds": 822 } ] }, { "vehicle_id": "van-2", "stop_count": 3, "task_count": 1, "distance_meters": 7104, "duration_seconds": 934, "service_seconds": 300, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T09:50:34-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1003", "sequence": 1, "reachable": true, "leg_distance_meters": 3552, "leg_duration_seconds": 467, "leg_geometry": null, "arrival": "2026-10-23T09:37:47-04:00", "arrival_epoch": 1792762667, "distance_meters": 3552, "duration_seconds": 467 }, { "type": "end", "reachable": true, "leg_distance_meters": 3552, "leg_duration_seconds": 467, "leg_geometry": null, "arrival": "2026-10-23T09:50:34-04:00", "arrival_epoch": 1792763434, "distance_meters": 7104, "duration_seconds": 934 } ] } ], "summary": { "routes": 2, "tasks": 3, "distance_meters": 13350, "duration_seconds": 1756, "unreachable_legs": 0, "violations": 0 }, "plan": { "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] }, { "vehicle_id": "van-2", "stops": [ "order-1003" ] } ], "unassigned": [] }, "move": { "vehicle_id": "van-2", "position": 1, "stops": [ "order-1003" ], "from": [ { "id": "order-1003", "vehicle_id": "van-1", "position": 3 } ], "feasible": true, "violations": 0 } }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. Road legs measured before are read from it and the legs it lacks are measured and added; the answer is the same as without it, and is billed the same. An expired, unknown or unreachable snapshot is not an error: the call is measured without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "position": { "type": [ "integer", "null" ], "minimum": 1, "description": "Where the stops go in the target route, from 1 (first), counted without the moved stops. Omitted: after the last stop." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "stops": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 128 }, "description": "The stops to move, 1-100, in the order they are to be driven. Each may be on any route, the target route included, or a job on no route." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle whose route receives the stops. A vehicle without a route gets one." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "stops", "vehicle_id", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1003" ] } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "stops": [ "order-1003" ], "vehicle_id": "van-2", "position": 1 } } } } } }, "/v1/plan/recost": { "post": { "operationId": "planRecost", "tags": [ "plan" ], "summary": "Re-cost a plan", "description": "Prices the submitted plan exactly as given and never resequences it: every leg is measured on the road network with distance, duration and geometry, and arrival times are projected from the departure instant. Use it after editing a plan — inserting a stop at a chosen position, removing one, reordering or reversing a route, or changing a start or end point. To have the engine choose where a new stop goes, call routing refine with the existing stops frozen instead. An optional `matrix`, a distance snapshot, makes repeated calls on the same plan faster; the answer is the same.\n\nPrice an edited plan exactly as given — per-leg distance, duration and road geometry, with arrival times — without resequencing it. Stated constraints (time windows, capacity, skills, vehicle ceilings) are judged and reported as violations, never refused.", "x-superroute-capability": "plan.recost", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.recost", "responses": { "200": { "description": "The caller's routes, kept exactly as given, with distance, driving time and arrival time of every stop. Breaches of the stated constraints are reported in `violations`, never refused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.recost" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } } }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } } } }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.recost", "billing": { "unit": "node", "quantity": 2, "counted": true, "breakdown": { "tasks": 2, "routes": 1 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 4, "task_count": 2, "distance_meters": 6416, "duration_seconds": 832, "service_seconds": 600, "waiting_seconds": 0, "departure": "2026-10-23T09:27:48-04:00", "completion": "2026-10-23T09:51:40-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:27:48-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1840, "leg_duration_seconds": 245, "leg_geometry": "y`vtGjr_`MJUNYL[h@gAHOFQBIHOc@g@MOa@]s@q@EGEEk@g@k@k@CCMMDO@EDMBMBOBQBO@KBM?G@OBQ?G@MBQ@MBMBMBOBOBMFSDSBGBIBGHOvAkE@EHQGEECa@_@ECMKKIwAiA_CmBq@m@ECIIOKoAcAs@i@KIIIOMgA{@QMCCGGGE_@[m@g@a@[kA_ACCECKGKGWSQOwAkAGEGEu@o@CCMIMKGEYSeAq@OKa@WGG[Sy@g@w@k@s@e@GEGE??YQgAu@c@[QKc@YMKKG@EBK@EVo@@EDKDM@Cb@cAFOBIt@oBBEDUJFBBFDx@l@??", "arrival": "2026-10-23T09:31:53-04:00", "arrival_epoch": 1792762313, "distance_meters": 1840, "duration_seconds": 245 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "leg_distance_meters": 3108, "leg_duration_seconds": 390, "leg_geometry": "elwtGl}|_Mx@n@BBFD\\ZDDDBz@l@`@\\~BdB~AjAf@\\DDBBLDEPEJe@zAADENGNCFW|@Y|@CFA@ELCHGRq@jBABu@tBCHAFEJGNADg@vAKXq@lBABEHAHgA|C_@fASf@ADGPO^JHbAt@`CrBBBJHLJhCzBJL~BvBFDJJHF~@r@zAdABBHFLHdDfCBBFFFDJHvDlCRJDBRHXPx@f@D@HHJFVV|@x@BBLJTRJJTTlBdBLL`@\\h@f@ZXNLr@p@BBB@JJJHv@r@j@h@DDNLJJp@l@HHj@j@DBLLRRfB`BBBJJHFv@r@x@t@B@HHJJz@v@RRl@j@BBHHJHhAfAj@j@BBNLHHLLVT|@z@HFIPw@tBmAbDy@vBe@pACDIPIRg@pAO\\{A`ECDAFEJHHp@p@??", "arrival": "2026-10-23T09:43:23-04:00", "arrival_epoch": 1792763003, "distance_meters": 4948, "duration_seconds": 635 }, { "type": "end", "reachable": true, "leg_distance_meters": 1468, "leg_duration_seconds": 197, "leg_geometry": "{cutG|wa`Md@f@LJFDDDFBBBFBDKBGrAkDFQBGp@eB@EFSFSBCb@mAl@}AjA{Cb@iAd@mABEFQJ[IG{ByBIGGIMKIKo@m@OMGI[Yc@a@e@c@m@m@ECIIKKaA}@EEu@q@CCIIKIq@o@{@y@ECIIII_@[[Y_@_@ECWWQOIIGE]]QO_@]CCKKYWKIu@q@MMYWCCKKKIACoAiAuAoAKIs@q@eA_AKKCCOOJO@A??", "arrival": "2026-10-23T09:51:40-04:00", "arrival_epoch": 1792763500, "distance_meters": 6416, "duration_seconds": 832 } ] } ], "summary": { "routes": 1, "tasks": 2, "distance_meters": 6416, "duration_seconds": 832, "unreachable_legs": 0, "violations": 0 } }, "meta": { "region": "NA", "profile": "car", "geometry": true, "geometry_format": "polyline", "departed_at": "2026-10-23T09:27:48-04:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. Road legs measured before are read from it and the legs it lacks are measured and added; the answer is the same as without it, and is billed the same. An expired, unknown or unreachable snapshot is not an error: the call is measured without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } } }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "vehicles" ] }, "example": { "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ] } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": [ 2 ] }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": [ 3 ] } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] } ] } } } } } }, "/v1/plan/refine": { "post": { "operationId": "planRefine", "tags": [ "plan" ], "summary": "Refine routes", "description": "Re-orders the stops of the routes of `vehicle_ids` (every route sent when omitted) within and between those routes; stops in `freeze` stay on their route in their order, and frozen stops that lead a route stay first. No other route and no unassigned job takes part. The new order is priced exactly as plan re-costing prices it and kept only when it is better than the plan as sent: fewer unreachable legs, then fewer violations, then less driver time, then less distance. The answer adds `plan` and `refine`: `changed`, `moved` (the stops whose route or place changed) and `before` (the totals of the plan as sent). With `matrix`, a distance snapshot, up to 600 stops are refined; without a usable snapshot, up to 60 stops on 5 routes are refined by the routing engine. Single jobs only: pickup and delivery pairs are refused. A refine that cannot be answered here is refused with PLAN_REFINE_REFUSED and the reason in `reason`; refine such a plan with routing refine. Nothing is stored. Billed per node: the stops priced.\n\nRe-order the stops of chosen routes of a plan you hold around stops you lock, and receive the plan priced; a new order is kept only when it is better.", "x-superroute-capability": "plan.refine", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.refine", "responses": { "200": { "description": "The plan with the refined order when it is better than the plan as sent, else the plan as sent, priced and judged as plan re-costing prices it, the plan itself in `plan`, and what the refine did.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.refine" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "plan": { "type": "object", "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stops": { "type": "array", "items": { "type": "string" } } }, "required": [ "vehicle_id", "stops" ] } }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "Every job of the plan that is on no route." } }, "required": [ "routes", "unassigned" ] }, "refine": { "type": "object", "properties": { "vehicle_ids": { "type": "array", "items": { "type": "string" }, "description": "The routes refined." }, "freeze": { "type": "array", "items": { "type": "string" }, "description": "The frozen stops." }, "changed": { "type": "boolean", "description": "Whether the answered plan has a new order. False when none was found or the order found is not better." }, "moved": { "type": "integer", "description": "Stops whose route or place in it is not what was sent." }, "before": { "type": "object", "description": "The totals of the plan as sent.", "properties": { "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "waiting_seconds": { "type": "integer" }, "violations": { "type": "integer" }, "unreachable_legs": { "type": "integer" } } } }, "required": [ "vehicle_ids", "freeze", "changed", "moved", "before" ] } }, "required": [ "routes", "summary", "plan", "refine" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.refine", "billing": { "unit": "node", "quantity": 4, "counted": true, "breakdown": { "tasks": 4, "routes": 1 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 6, "task_count": 4, "distance_meters": 17473, "duration_seconds": 2286, "service_seconds": 1200, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T10:28:06-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1002", "sequence": 1, "reachable": true, "leg_distance_meters": 1611, "leg_duration_seconds": 227, "leg_geometry": null, "arrival": "2026-10-23T09:33:47-04:00", "arrival_epoch": 1792762427, "distance_meters": 1611, "duration_seconds": 227 }, { "type": "job", "id": "order-1001", "sequence": 2, "reachable": true, "leg_distance_meters": 3355, "leg_duration_seconds": 421, "leg_geometry": null, "arrival": "2026-10-23T09:45:48-04:00", "arrival_epoch": 1792763148, "distance_meters": 4966, "duration_seconds": 648 }, { "type": "job", "id": "order-1003", "sequence": 3, "reachable": true, "leg_distance_meters": 3500, "leg_duration_seconds": 466, "leg_geometry": null, "arrival": "2026-10-23T09:58:34-04:00", "arrival_epoch": 1792763914, "distance_meters": 8466, "duration_seconds": 1114 }, { "type": "job", "id": "order-1004", "sequence": 4, "reachable": true, "leg_distance_meters": 3487, "leg_duration_seconds": 492, "leg_geometry": null, "arrival": "2026-10-23T10:11:46-04:00", "arrival_epoch": 1792764706, "distance_meters": 11953, "duration_seconds": 1606 }, { "type": "end", "reachable": true, "leg_distance_meters": 5520, "leg_duration_seconds": 680, "leg_geometry": null, "arrival": "2026-10-23T10:28:06-04:00", "arrival_epoch": 1792765686, "distance_meters": 17473, "duration_seconds": 2286 } ] } ], "summary": { "routes": 1, "tasks": 4, "distance_meters": 17473, "duration_seconds": 2286, "unreachable_legs": 0, "violations": 0 }, "plan": { "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1002", "order-1001", "order-1003", "order-1004" ] } ], "unassigned": [] }, "refine": { "vehicle_ids": [ "van-1" ], "freeze": [ "order-1002" ], "changed": true, "moved": 3, "before": { "distance_meters": 21187, "duration_seconds": 2717, "waiting_seconds": 0, "violations": 0, "unreachable_legs": 0 } } }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "freeze": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "Stops of the refined routes that stay on their route, in their order. Frozen stops that lead their route stay first." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. The candidates are ranked on its road matrix and every leg answered is read from it or measured and added; every distance and time answered is an exact road leg, with or without it, and the call is billed the same. An expired, unknown or unreachable snapshot is not an error: the call searches without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`. Without a usable snapshot, at most 60 stops on 5 routes are refined; a larger refine answers PLAN_REFINE_REFUSED." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "vehicle_ids": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "maxLength": 128 }, "description": "The vehicles whose routes are refined, 1-200; default every route sent. Stops move within and between these routes only; a vehicle without a route may receive stops. At most 600 stops are refined." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } }, { "id": "order-1004", "location": { "lat": 45.5302, "lng": -73.6125 }, "service_seconds": 300, "amount": { "parcels": 2 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1002", "order-1004", "order-1001", "order-1003" ] } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "freeze": [ "order-1002" ] } } } } } }, "/v1/plan/remove": { "post": { "operationId": "planRemove", "tags": [ "plan" ], "summary": "Remove stops", "description": "Takes the jobs in `stops` off their routes into the unassigned pool and prices the edited plan exactly as plan re-costing prices it; a route left without stops is priced from its start to its end. The answer adds `plan`, the edited plan in the shape it is sent, with the removed jobs in `unassigned`, and `removed`: the route and position each was taken from. A job on no route is refused. An optional `matrix`, a distance snapshot, makes repeated calls on the same plan faster; the answer is the same. Nothing is stored. Billed per node: the stops priced.\n\nTake stops of a plan you hold off their routes into the unassigned pool and receive the edited plan priced.", "x-superroute-capability": "plan.remove", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.remove", "responses": { "200": { "description": "The plan without the removed stops, priced and judged as plan re-costing prices it, and the edited plan in `plan` with the removed stops among `unassigned`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.remove" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "plan": { "type": "object", "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stops": { "type": "array", "items": { "type": "string" } } }, "required": [ "vehicle_id", "stops" ] } }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "Every job of the plan that is on no route." } }, "required": [ "routes", "unassigned" ] }, "removed": { "type": "array", "description": "Each removed stop with the vehicle and position it was taken from.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "vehicle_id": { "type": "string" }, "position": { "type": "integer" } } } } }, "required": [ "routes", "summary", "plan", "removed" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.remove", "billing": { "unit": "node", "quantity": 2, "counted": true, "breakdown": { "tasks": 2, "routes": 1 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 4, "task_count": 2, "distance_meters": 8931, "duration_seconds": 1174, "service_seconds": 600, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T09:59:34-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1759, "leg_duration_seconds": 231, "leg_geometry": null, "arrival": "2026-10-23T09:33:51-04:00", "arrival_epoch": 1792762431, "distance_meters": 1759, "duration_seconds": 231 }, { "type": "job", "id": "order-1003", "sequence": 2, "reachable": true, "leg_distance_meters": 3620, "leg_duration_seconds": 476, "leg_geometry": null, "arrival": "2026-10-23T09:46:47-04:00", "arrival_epoch": 1792763207, "distance_meters": 5379, "duration_seconds": 707 }, { "type": "end", "reachable": true, "leg_distance_meters": 3552, "leg_duration_seconds": 467, "leg_geometry": null, "arrival": "2026-10-23T09:59:34-04:00", "arrival_epoch": 1792763974, "distance_meters": 8931, "duration_seconds": 1174 } ] } ], "summary": { "routes": 1, "tasks": 2, "distance_meters": 8931, "duration_seconds": 1174, "unreachable_legs": 0, "violations": 0 }, "plan": { "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1003" ] } ], "unassigned": [ "order-1002" ] }, "removed": [ { "id": "order-1002", "vehicle_id": "van-1", "position": 2 } ] }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. Road legs measured before are read from it and the legs it lacks are measured and added; the answer is the same as without it, and is billed the same. An expired, unknown or unreachable snapshot is not an error: the call is measured without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "stops": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The stops to take off their routes, 1-2000. Each must be on a route." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "stops", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1003" ] } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "stops": [ "order-1002" ] } } } } } }, "/v1/plan/resequence": { "post": { "operationId": "planResequence", "tags": [ "plan" ], "summary": "Reorder a route", "description": "Gives the route of `vehicle_id` the stop order in `stops`, which must list every stop of that route once and no other, and prices the whole edited plan exactly as plan re-costing prices it: routes, summary and violations. The plan is given as for plan re-costing, with an `id` on every vehicle and job. The answer adds `plan`, the edited plan in the shape it is sent (routes with ordered stop ids, and `unassigned`: every job on no route), and `resequence.changed`. An optional `matrix`, a distance snapshot, makes repeated calls on the same plan faster; the answer is the same. Nothing is stored. Billed per node: the stops priced.\n\nGive one route of a plan you hold a new stop order and receive the edited plan priced, with every violation named.", "x-superroute-capability": "plan.resequence", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.resequence", "responses": { "200": { "description": "The plan with the route's new stop order, priced and judged as plan re-costing prices it, and the edited plan in `plan`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.resequence" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "plan": { "type": "object", "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stops": { "type": "array", "items": { "type": "string" } } }, "required": [ "vehicle_id", "stops" ] } }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "Every job of the plan that is on no route." } }, "required": [ "routes", "unassigned" ] }, "resequence": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "changed": { "type": "boolean", "description": "False when the order given is the order the route already had." } }, "required": [ "vehicle_id", "changed" ] } }, "required": [ "routes", "summary", "plan", "resequence" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.resequence", "billing": { "unit": "node", "quantity": 3, "counted": true, "breakdown": { "tasks": 3, "routes": 1 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stop_count": 5, "task_count": 3, "distance_meters": 11659, "duration_seconds": 1534, "service_seconds": 900, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T10:10:34-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1002", "sequence": 1, "reachable": true, "leg_distance_meters": 1367, "leg_duration_seconds": 180, "leg_geometry": null, "arrival": "2026-10-23T09:33:00-04:00", "arrival_epoch": 1792762380, "distance_meters": 1367, "duration_seconds": 180 }, { "type": "job", "id": "order-1001", "sequence": 2, "reachable": true, "leg_distance_meters": 3120, "leg_duration_seconds": 411, "leg_geometry": null, "arrival": "2026-10-23T09:44:51-04:00", "arrival_epoch": 1792763091, "distance_meters": 4487, "duration_seconds": 591 }, { "type": "job", "id": "order-1003", "sequence": 3, "reachable": true, "leg_distance_meters": 3620, "leg_duration_seconds": 476, "leg_geometry": null, "arrival": "2026-10-23T09:57:47-04:00", "arrival_epoch": 1792763867, "distance_meters": 8107, "duration_seconds": 1067 }, { "type": "end", "reachable": true, "leg_distance_meters": 3552, "leg_duration_seconds": 467, "leg_geometry": null, "arrival": "2026-10-23T10:10:34-04:00", "arrival_epoch": 1792764634, "distance_meters": 11659, "duration_seconds": 1534 } ] } ], "summary": { "routes": 1, "tasks": 3, "distance_meters": 11659, "duration_seconds": 1534, "unreachable_legs": 0, "violations": 0 }, "plan": { "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1002", "order-1001", "order-1003" ] } ], "unassigned": [] }, "resequence": { "vehicle_id": "van-1", "changed": true } }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. Road legs measured before are read from it and the legs it lacks are measured and added; the answer is the same as without it, and is billed the same. An expired, unknown or unreachable snapshot is not an error: the call is measured without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each leg carries its road line (encoded polyline, precision 5). Default true." } }, "description": "Answer options." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's stops in the new driving order: every stop of the route once, and no other." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle whose route is given a new order." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "vehicle_id", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1003" ] } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "vehicle_id": "van-1", "stops": [ "order-1002", "order-1001", "order-1003" ] } } } } } }, "/v1/plan/token": { "post": { "operationId": "planToken", "tags": [ "platform" ], "summary": "Get a plan editor token", "description": "Exchanges an API token for a short-lived token for a plan editor in a browser or an app. The token calls the plan endpoints only (the plan calls and distance snapshots) with the plan capabilities of the key, and its calls are billed like the key's. `ttl_seconds` sets its life (default 15 minutes, at most one hour); `origins` limits it to these web origins. Call this endpoint from your server, never from the page.\n\nExchange an API token for a short-lived session token.", "x-superroute-capability": "platform.auth", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.auth", "responses": { "200": { "description": "A plan editor token. Hand it to the plan editor in the browser or the app, which sends it as `Authorization: Bearer ` to the plan endpoints until `expires_at`, and asks your server for a new one before then. It calls the plan endpoints only, with the plan capabilities of the key; every use checks the key again, so revoking the key or removing its plan capabilities ends the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The plan editor token, `sr_pet_...`. Signed, not stored: it cannot be revoked on its own, only by revoking the key or by its expiry." }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds until it expires." }, "expires_at": { "type": "string", "description": "ISO 8601 with offset." }, "scopes": { "type": "array", "description": "The plan capabilities it may call: `plan.*` for a key that may call everything, else the key's plan entries.", "items": { "type": "string" } }, "origins": { "type": [ "array", "null" ], "description": "The web origins it may be used from, as normalised; null when it is not limited to origins.", "items": { "type": "string" } }, "fast_path": { "type": "object", "description": "Present only when the account takes the fast path for plan edits (Open Platform portal, Plan editing path: Fast). The plan editor then sends its calls to `url` (`/recost`, `/move`, ... the same paths as /v1/plan/*) with the same token and the same bodies, and gets the same answers. When the fast path answers 409 USE_STANDARD_PATH, any 5xx, or does not answer in time, the editor repeats the call on /v1/plan/*. Absent: every call goes to /v1/plan/*.", "properties": { "url": { "type": "string", "description": "The fast path base address: the map service's plan calls, mirroring /v1/plan/*." } }, "required": [ "url" ] } }, "required": [ "access_token", "token_type", "expires_in", "expires_at", "scopes" ] }, "meta": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The API key that minted the token." } } } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "access_token": "sr_pet_eyJ2IjoxLCJjaWQiOjEyLCJraWQiOiJzcl9saXZlXzdIcTJMbVg5cFI0c1QxdlcifQ.Xq7bN2kLm9Pz4Rt8Wv1Yc5Hd3Jf6Gs0Aa2Ee4Uu", "token_type": "Bearer", "expires_in": 900, "expires_at": "2026-10-28T09:42:39-04:00", "scopes": [ "plan.*" ], "origins": [ "dispatch.example.com" ] }, "meta": { "key_id": "sr_live_7Hq2LmX9pR4sT1vW8yZ3nB6c" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origins": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 255 }, "description": "The web origins the token may be used from (hosts or `*.domain`, at most 20). A call from a page of another origin, or with no `Origin` or `Referer`, is refused with NOT_AUTHORIZED, reason `origin_not_allowed`. Omit for a token used by a native app." }, "ttl_seconds": { "type": [ "integer", "null" ], "minimum": 60, "description": "Seconds the token lives: 60 to 3600, default 900. A longer life is shortened to the longest allowed, as answered in `expires_in`." } }, "additionalProperties": false }, "example": { "ttl_seconds": 900, "origins": [ "dispatch.example.com" ] } } } } } }, "/v1/plan/validate": { "post": { "operationId": "planValidate", "tags": [ "plan" ], "summary": "Validate a plan", "description": "Judges the submitted plan exactly as given, with the solver's own semantics: arriving before a window waits and shifts later arrivals, arriving after every window is late, capacity is the summed load per dimension, skills are set-containment, and the vehicle's window, distance, travel-time and stop-count ceilings are checked against the finished walk. Every violation is returned on the stop or route at fault, with arrival and waiting times — never a refusal. It is the re-costing evaluator with leg geometry and per-leg figures stripped, for callers who only want the verdict. An optional `matrix`, a distance snapshot, makes repeated calls on the same plan faster; the answer is the same.\n\nJudge a plan against its stated constraints — time windows, capacity, skills, vehicle ceilings — with every violation named. The same evaluator as re-costing, without the map payload.", "x-superroute-capability": "plan.validate", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.validate", "responses": { "200": { "description": "Whether the caller's routes keep every stated constraint, and where they do not. Same walk as plan.recost, reduced to what a violation highlighter needs. A plan with breaches answers 200 with `valid: false` and a PLAN_VIOLATIONS warning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.validate" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True when no route breaks anything." }, "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "valid": { "type": "boolean" }, "violation_count": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "waiting_seconds": { "type": "integer" }, "completion": { "type": "string", "description": "ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] }, "description": "Stops with their timing and their own violations; no geometry." } } } }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } } } }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.validate", "billing": { "unit": "node", "quantity": 2, "counted": true, "breakdown": { "tasks": 2, "routes": 1 } }, "warnings": [ { "code": "PLAN_VIOLATIONS", "message": "The plan breaks 2 stated constraint(s); see `violations` on the routes and stops." } ], "data": { "valid": false, "routes": [ { "vehicle_id": "van-1", "valid": false, "violation_count": 2, "violations": [ { "rule": "capacity", "message": "The stops load more than the vehicle carries.", "dimension": "0", "load": 11, "capacity": 10 } ], "waiting_seconds": 0, "completion": "2026-11-02T08:23:52-05:00", "unreachable_legs": 0, "stops": [ { "type": "start", "departure": "2026-11-02T08:00:00-05:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "arrival": "2026-11-02T08:04:05-05:00", "arrival_epoch": 1793624645 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "arrival": "2026-11-02T08:15:35-05:00", "arrival_epoch": 1793625335, "violations": [ { "rule": "time_window", "message": "Arrival is after every time window of this stop.", "late_seconds": 635, "window": { "from": "2026-11-02T08:00:00-05:00", "to": "2026-11-02T08:05:00-05:00" } } ] }, { "type": "end", "reachable": true, "arrival": "2026-11-02T08:23:52-05:00", "arrival_epoch": 1793625832 } ] } ], "summary": { "routes": 1, "tasks": 2, "distance_meters": 6416, "duration_seconds": 832, "unreachable_legs": 0, "violations": 2 } }, "meta": { "region": "NA", "profile": "car", "departed_at": "2026-11-02T08:00:00-05:00", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. Road legs measured before are read from it and the legs it lacks are measured and added; the answer is the same as without it, and is billed the same. An expired, unknown or unreachable snapshot is not an error: the call is measured without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ], "description": "Read `stops` in reverse order. The edit calls answer the route already reversed in `plan`." }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 }, "description": "The route's job ids in driving order." }, "vehicle_id": { "type": "string", "maxLength": 128, "description": "The vehicle that drives the route." } }, "required": [ "vehicle_id" ] }, "description": "The routes as they are driven, 1-200. A job on no route is unassigned." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } } }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "routes", "vehicles" ] }, "example": { "departed_at": "2026-11-02T08:00:00-05:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ] } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": [ 2 ] }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": [ 9 ], "time_windows": [ [ "2026-11-02T08:00:00-05:00", "2026-11-02T08:05:00-05:00" ] ] } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] } ] } } } } } }, "/v1/plan/what-if": { "post": { "operationId": "planWhat_if", "tags": [ "plan" ], "summary": "Compare plans", "description": "Prices and judges each of the `plans` (2-10, each with `routes` as plan re-costing takes them and an optional `id`) with the `vehicles` and `jobs` of the request, exactly as plan re-costing does, and ranks them: fewer unreachable legs first, then fewer violations, then the `objective`: driver time (`duration`, driving plus waiting) or distance. The answer holds `plans` (each with its rank, objective value, summary and routes), `ranking` (the plan indices, best first) and `best`. Leg geometry is returned only with `options.geometry`. With `rank_only` and `matrix`, a distance snapshot, the plans are ranked by their travel on its road matrix without being priced (`scored` is false). At most 4,000 stops over all plans. Nothing is stored. Billed per node: the stops of every plan.\n\nPrice and judge several alternative plans of the same vehicles and jobs and receive them ranked.", "x-superroute-capability": "plan.what_if", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/plan.what_if", "responses": { "200": { "description": "Every plan priced and judged as plan re-costing prices it, with its rank: fewer unreachable legs first, then fewer violations, then the objective. With `rank_only` on a usable snapshot, the ranking only (`scored` false).", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "plan.what_if" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "scored": { "type": "boolean", "description": "True when every plan was priced; false for a ranking on the snapshot's road matrix (`rank_only`)." }, "ranking": { "type": "array", "items": { "type": "integer" }, "description": "The plan indices, best first." }, "best": { "type": "integer", "description": "The index of the best plan." }, "plans": { "type": "array", "description": "The plans in the order sent.", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "id": { "type": [ "string", "null" ], "description": "The plan's `id` as sent." }, "rank": { "type": "integer", "description": "1 = best." }, "objective_value": { "type": "integer", "description": "Driver time in seconds (driving plus waiting) for `duration`, metres for `distance`. Scored plans only." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer" }, "tasks": { "type": "integer", "description": "Jobs across all routes." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time across all routes." }, "unreachable_legs": { "type": "integer", "description": "Hops that could not be routed." }, "violations": { "type": "integer", "description": "Breaches across all routes and stops." } } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "stop_count": { "type": "integer", "description": "Stops including start and end." }, "task_count": { "type": "integer", "description": "Jobs on the route." }, "distance_meters": { "type": "integer" }, "duration_seconds": { "type": "integer", "description": "Driving time." }, "service_seconds": { "type": "integer" }, "waiting_seconds": { "type": "integer" }, "departure": { "type": "string", "description": "ISO 8601 with offset." }, "completion": { "type": "string", "description": "When the last stop (or the end) is reached. ISO 8601 with offset." }, "unreachable_legs": { "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "description": "A route-level breach. Which fields are present depends on `rule`.", "properties": { "rule": { "type": "string", "enum": [ "capacity", "max_tasks", "max_distance", "max_travel_time", "vehicle_time_window" ] }, "message": { "type": "string" }, "dimension": { "type": "string", "description": "capacity: the capacity dimension that overflows." }, "load": { "type": "number", "description": "capacity: what the stops load." }, "capacity": { "type": "number", "description": "capacity: what the vehicle carries." }, "tasks": { "type": "integer", "description": "max_tasks: stops on the route." }, "distance_meters": { "type": "integer", "description": "max_distance: distance of the route." }, "duration_seconds": { "type": "integer", "description": "max_travel_time: driving time of the route." }, "limit": { "type": "integer", "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit." }, "late_seconds": { "type": "integer", "description": "vehicle_time_window: how far past the working window the route ends." }, "window_end": { "type": "string", "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset." } } }, "description": "Route-level breaches." }, "violation_count": { "type": "integer", "description": "Route and stop breaches on this route." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "end" ] }, "id": { "type": "string", "description": "The caller's job id. Jobs only." }, "sequence": { "type": "integer", "description": "Position of the job on the route, from 1." }, "reachable": { "type": "boolean", "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`." }, "departure": { "type": "string", "description": "Start only: when the vehicle leaves. ISO 8601 with offset." }, "waiting_seconds": { "type": "integer", "description": "Start only, when the vehicle must wait for its working window to open." }, "arrival": { "type": [ "string", "null" ], "description": "ISO 8601 with offset. Null after an unreachable hop." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "leg_distance_meters": { "type": [ "integer", "null" ], "description": "Distance of the hop into this stop." }, "leg_duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time of the hop into this stop." }, "leg_geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Cumulative distance from the start." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Cumulative driving time from the start." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "skills", "time_window" ] }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "skills: the skills the vehicle lacks." }, "late_seconds": { "type": "integer", "description": "time_window: how late the arrival is." }, "window": { "type": "object", "description": "time_window: the window that was missed.", "properties": { "from": { "type": "string", "description": "ISO 8601 with offset." }, "to": { "type": "string", "description": "ISO 8601 with offset." } } } } }, "description": "Constraints this stop breaks. Present only when it breaks one." } }, "required": [ "type" ] } } } }, "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them." }, "unassigned": { "type": "array", "items": { "type": "string" }, "description": "The jobs on no route in this plan. Scored plans only." }, "warnings": { "type": "array", "items": { "type": "object" }, "description": "The plan's own warnings. Scored plans only." }, "unreachable": { "type": "boolean", "description": "`rank_only`: whether the plan drives a pair the road matrix has no road for." } }, "required": [ "index", "rank" ] } } }, "required": [ "scored", "ranking", "best", "plans" ] }, "meta": { "type": "object", "properties": { "region": { "type": "string", "description": "The engine region used." }, "profile": { "type": "string", "description": "The vehicle profile used." }, "geometry": { "type": "boolean", "description": "Whether leg geometry was returned." }, "geometry_format": { "type": [ "string", "null" ], "description": "`polyline` when geometry was returned." }, "departed_at": { "type": "string", "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset." }, "objective": { "type": "string", "description": "`duration` or `distance`." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "plan.what_if", "billing": { "unit": "node", "quantity": 8, "counted": true, "breakdown": { "plans": 2, "stops": 8 } }, "data": { "scored": true, "ranking": [ 0, 1 ], "best": 0, "plans": [ { "index": 0, "id": "one-van", "rank": 1, "objective_value": 2335, "summary": { "routes": 1, "tasks": 4, "distance_meters": 18088, "duration_seconds": 2335, "unreachable_legs": 0, "violations": 0 }, "routes": [ { "vehicle_id": "van-1", "stop_count": 6, "task_count": 4, "distance_meters": 18088, "duration_seconds": 2335, "service_seconds": 1200, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T10:28:55-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1840, "leg_duration_seconds": 245, "leg_geometry": null, "arrival": "2026-10-23T09:34:05-04:00", "arrival_epoch": 1792762445, "distance_meters": 1840, "duration_seconds": 245 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "leg_distance_meters": 3108, "leg_duration_seconds": 390, "leg_geometry": null, "arrival": "2026-10-23T09:45:35-04:00", "arrival_epoch": 1792763135, "distance_meters": 4948, "duration_seconds": 635 }, { "type": "job", "id": "order-1004", "sequence": 3, "reachable": true, "leg_distance_meters": 6451, "leg_duration_seconds": 824, "leg_geometry": null, "arrival": "2026-10-23T10:04:19-04:00", "arrival_epoch": 1792764259, "distance_meters": 11399, "duration_seconds": 1459 }, { "type": "job", "id": "order-1003", "sequence": 4, "reachable": true, "leg_distance_meters": 3180, "leg_duration_seconds": 442, "leg_geometry": null, "arrival": "2026-10-23T10:16:41-04:00", "arrival_epoch": 1792765001, "distance_meters": 14579, "duration_seconds": 1901 }, { "type": "end", "reachable": true, "leg_distance_meters": 3509, "leg_duration_seconds": 434, "leg_geometry": null, "arrival": "2026-10-23T10:28:55-04:00", "arrival_epoch": 1792765735, "distance_meters": 18088, "duration_seconds": 2335 } ] } ], "unassigned": [], "warnings": [] }, { "index": 1, "id": "two-vans", "rank": 2, "objective_value": 2486, "summary": { "routes": 2, "tasks": 4, "distance_meters": 19058, "duration_seconds": 2486, "unreachable_legs": 0, "violations": 0 }, "routes": [ { "vehicle_id": "van-1", "stop_count": 4, "task_count": 2, "distance_meters": 6416, "duration_seconds": 832, "service_seconds": 600, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T09:53:52-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1840, "leg_duration_seconds": 245, "leg_geometry": null, "arrival": "2026-10-23T09:34:05-04:00", "arrival_epoch": 1792762445, "distance_meters": 1840, "duration_seconds": 245 }, { "type": "job", "id": "order-1002", "sequence": 2, "reachable": true, "leg_distance_meters": 3108, "leg_duration_seconds": 390, "leg_geometry": null, "arrival": "2026-10-23T09:45:35-04:00", "arrival_epoch": 1792763135, "distance_meters": 4948, "duration_seconds": 635 }, { "type": "end", "reachable": true, "leg_distance_meters": 1468, "leg_duration_seconds": 197, "leg_geometry": null, "arrival": "2026-10-23T09:53:52-04:00", "arrival_epoch": 1792763632, "distance_meters": 6416, "duration_seconds": 832 } ] }, { "vehicle_id": "van-2", "stop_count": 4, "task_count": 2, "distance_meters": 12642, "duration_seconds": 1654, "service_seconds": 600, "waiting_seconds": 0, "departure": "2026-10-23T09:30:00-04:00", "completion": "2026-10-23T10:07:34-04:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-10-23T09:30:00-04:00" }, { "type": "job", "id": "order-1003", "sequence": 1, "reachable": true, "leg_distance_meters": 3635, "leg_duration_seconds": 482, "leg_geometry": null, "arrival": "2026-10-23T09:38:02-04:00", "arrival_epoch": 1792762682, "distance_meters": 3635, "duration_seconds": 482 }, { "type": "job", "id": "order-1004", "sequence": 2, "reachable": true, "leg_distance_meters": 3487, "leg_duration_seconds": 492, "leg_geometry": null, "arrival": "2026-10-23T09:51:14-04:00", "arrival_epoch": 1792763474, "distance_meters": 7122, "duration_seconds": 974 }, { "type": "end", "reachable": true, "leg_distance_meters": 5520, "leg_duration_seconds": 680, "leg_geometry": null, "arrival": "2026-10-23T10:07:34-04:00", "arrival_epoch": 1792764454, "distance_meters": 12642, "duration_seconds": 1654 } ] } ], "unassigned": [], "warnings": [] } ] }, "meta": { "region": "NA", "profile": "car", "geometry": false, "geometry_format": null, "departed_at": "2026-10-23T09:30:00-04:00", "objective": "duration", "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": { "description": "When the vehicles leave their starts: ISO 8601 with a UTC offset, or Unix seconds. Default now. Arrival times are projected from it; a vehicle's `time_window` starts its day later when it opens later." }, "jobs": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ], "description": "What the job loads: a quantity per dimension of the vehicles' `capacity`, in the same shape." }, "id": { "type": "string", "maxLength": 128, "description": "The job's id, named in `routes.*.stops`. Required on every call that edits or searches the plan." }, "location": { "type": "array", "description": "Where the job is, `{lat, lng}`." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Time spent at the stop, in seconds. Default 0." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the job needs." }, "time_windows": { "type": [ "array", "null" ], "description": "When the job may be served, each `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds). Arriving early waits for the window; arriving after every window is a `time_window` violation." } }, "required": [ "id", "location" ] }, "description": "The jobs of the plan, the stops of every route and the jobs on no route." }, "matrix": { "type": [ "string", "null" ], "maxLength": 200, "description": "A distance snapshot opened with POST /v1/plan/matrix for the same region and profile. The candidates are ranked on its road matrix and every leg answered is read from it or measured and added; every distance and time answered is an exact road leg, with or without it, and the call is billed the same. An expired, unknown or unreachable snapshot is not an error: the call searches without it, and the `X-Plan-Matrix` response header says `expired` (open a new one), `unavailable` or `mismatch` instead of `used`." }, "objective": { "type": [ "string", "null" ], "enum": [ "duration", "distance" ], "description": "`duration` (default): the least driver time, driving plus waiting. `distance`: the least distance. Plans are ranked by fewer unreachable legs first, then fewer violations, then the objective." }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether each plan's legs carry road geometry. Default false." } }, "description": "Answer options." }, "plans": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "routes": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ] }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 } }, "vehicle_id": { "type": "string", "maxLength": 128 } }, "required": [ "vehicle_id" ] } } }, "required": [ "routes" ] }, "description": "The plans to compare, 2-10, each with `routes` as plan re-costing takes them and an optional `id`. Every plan uses the `vehicles` and `jobs` of the request; at most 4,000 stops over all plans." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "rank_only": { "type": [ "boolean", "null" ], "description": "With a usable `matrix`: rank the plans by their travel on the snapshot's road matrix only, without pricing them (no time windows, capacity or other rules). Without a usable snapshot every plan is priced." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ], "description": "The routing region of the plan's locations. Default NA." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ], "description": "What the vehicle carries: a quantity per dimension (a list, or an object by dimension name), compared with the summed `amount` of its jobs; reported as a `capacity` violation when exceeded." }, "end": { "type": [ "array", "null" ], "description": "Where the vehicle ends, `{lat, lng}`. Omitted: the route ends at its last stop, or at the start with `return_to_start`." }, "id": { "type": "string", "maxLength": 128, "description": "The vehicle's id, named by `routes.*.vehicle_id`. Required on every call that edits or searches the plan." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest distance of the route; more is a `max_distance` violation." }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0, "description": "The most stops of the route; more is a `max_tasks` violation." }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "The longest driving time of the route; more is a `max_travel_time` violation." }, "return_to_start": { "type": [ "boolean", "null" ], "description": "End the route at the vehicle's start when no `end` is given." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "description": "The skills the vehicle has; a job needing a skill the vehicle lacks is a `skills` violation." }, "start": { "type": [ "array", "null" ], "description": "Where the vehicle starts, `{lat, lng}`." }, "time_window": { "type": [ "array", "null" ], "description": "The vehicle's working day, `{from, to}` or `[from, to]` (ISO 8601 with an offset, or Unix seconds); finishing after `to` is a `vehicle_time_window` violation." } }, "required": [ "id" ] }, "description": "The vehicles of the plan, 1-200." } }, "additionalProperties": false, "required": [ "jobs", "plans", "vehicles" ] }, "example": { "departed_at": "2026-10-23T09:30:00-04:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 } }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 300, "amount": { "parcels": 1 } }, { "id": "order-1004", "location": { "lat": 45.5302, "lng": -73.6125 }, "service_seconds": 300, "amount": { "parcels": 2 } } ], "options": { "geometry": false }, "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910", "plans": [ { "id": "one-van", "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002", "order-1004", "order-1003" ] } ] }, { "id": "two-vans", "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] }, { "vehicle_id": "van-2", "stops": [ "order-1003", "order-1004" ] } ] } ], "objective": "duration" } } } } } }, "/v1/routing/insert": { "post": { "operationId": "routingInsert", "tags": [ "routing" ], "summary": "Insert stops", "description": "Places each job in `insert`, in the order given, at the position that adds the least driver time (driving plus waiting; `objective: distance` ranks by added distance) while the plan keeps every rule it kept before: time windows, capacity, skills and the vehicles' windows and ceilings, judged exactly as plan re-costing judges them. No other stop moves. The plan is given as for plan re-costing: `vehicles` (each with a `start`), `jobs` and `routes` with ordered stop ids; a vehicle without a route may receive stops. Positions are tried next to the `nearest` stops to each new job (25 by default) and in every empty route. Returns each placement (`vehicle_id`, `position` from 1, the stop it follows, added distance, duration and waiting, arrival and service start) with up to `alternatives` other acceptable positions, the jobs that fit nowhere with the closest position and what it would break, and the updated routes priced. Nothing is stored. Billed per node: the plan's stops plus the new jobs.\n\nPlace new jobs in a plan you hold at the positions that cost least, without resequencing the rest.", "x-superroute-capability": "routing.insert", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/routing.insert", "responses": { "200": { "description": "Each new job's position with alternatives, the jobs that fit nowhere, and the updated routes. Billed per node.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.insert" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "placements": { "type": "array", "description": "The jobs placed, in the order of `insert`.", "items": { "type": "object", "properties": { "job": { "type": "string", "description": "The job id." }, "vehicle_id": { "type": "string", "description": "The vehicle whose route takes the job." }, "position": { "type": "integer", "description": "The job's place in that route's stops, from 1." }, "after": { "type": [ "string", "null" ], "description": "The stop the job follows; null when it comes first." }, "added_distance_meters": { "type": "integer", "description": "Distance the route gains." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the route gains." }, "added_waiting_seconds": { "type": "integer", "description": "Waiting the route gains (negative when the job fills time spent waiting)." }, "arrival": { "type": [ "string", "null" ], "description": "Arrival at the job, ISO 8601." }, "waiting_seconds": { "type": "integer", "description": "Waiting at the job before its window opens." }, "service_start": { "type": [ "string", "null" ], "description": "When work at the job begins: arrival plus waiting." }, "violations": { "type": "array", "description": "What this position breaks. Present only on a position that is not acceptable (`closest`)." }, "alternatives": { "type": "array", "description": "Other acceptable positions, best first.", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "The vehicle whose route takes the job." }, "position": { "type": "integer", "description": "The job's place in that route's stops, from 1." }, "after": { "type": [ "string", "null" ], "description": "The stop the job follows; null when it comes first." }, "added_distance_meters": { "type": "integer", "description": "Distance the route gains." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the route gains." }, "added_waiting_seconds": { "type": "integer", "description": "Waiting the route gains (negative when the job fills time spent waiting)." }, "arrival": { "type": [ "string", "null" ], "description": "Arrival at the job, ISO 8601." }, "waiting_seconds": { "type": "integer", "description": "Waiting at the job before its window opens." }, "service_start": { "type": [ "string", "null" ], "description": "When work at the job begins: arrival plus waiting." }, "violations": { "type": "array", "description": "What this position breaks. Present only on a position that is not acceptable (`closest`)." } } } } } } }, "unplaced": { "type": "array", "description": "Jobs with no acceptable position.", "items": { "type": "object", "properties": { "job": { "type": "string", "description": "The job id." }, "reason": { "type": "string", "enum": [ "no_feasible_position", "no_vehicle" ], "description": "`no_feasible_position`: every tried position breaks a rule; `no_vehicle`: no position could be tried." }, "closest": { "type": [ "object", "null" ], "description": "The cheapest position tried, with its `violations`.", "properties": { "vehicle_id": { "type": "string", "description": "The vehicle whose route takes the job." }, "position": { "type": "integer", "description": "The job's place in that route's stops, from 1." }, "after": { "type": [ "string", "null" ], "description": "The stop the job follows; null when it comes first." }, "added_distance_meters": { "type": "integer", "description": "Distance the route gains." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the route gains." }, "added_waiting_seconds": { "type": "integer", "description": "Waiting the route gains (negative when the job fills time spent waiting)." }, "arrival": { "type": [ "string", "null" ], "description": "Arrival at the job, ISO 8601." }, "waiting_seconds": { "type": "integer", "description": "Waiting at the job before its window opens." }, "service_start": { "type": [ "string", "null" ], "description": "When work at the job begins: arrival plus waiting." }, "violations": { "type": "array", "description": "What this position breaks. Present only on a position that is not acceptable (`closest`)." } } } } } }, "routes": { "type": "array", "description": "The routes with the jobs in place, priced as plan re-costing prices them (without geometry)." }, "summary": { "type": "object", "properties": { "inserted": { "type": "integer", "description": "Jobs placed." }, "unplaced": { "type": "integer", "description": "Jobs not placed." }, "added_distance_meters": { "type": "integer", "description": "Distance the plan gains." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the plan gains." }, "violations": { "type": "integer", "description": "Rule violations in the updated routes (as many as before: a placement never adds one)." } } } }, "required": [ "placements", "unplaced", "routes", "summary" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.insert", "billing": { "unit": "node", "quantity": 5, "counted": true, "breakdown": { "planned_stops": 3, "new_jobs": 2 } }, "data": { "placements": [ { "job": "order-1004", "vehicle_id": "van-1", "position": 2, "after": "order-1001", "added_distance_meters": 1505, "added_duration_seconds": 213, "added_waiting_seconds": -513, "arrival": "2026-11-02T08:11:57-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:11:57-05:00", "alternatives": [ { "vehicle_id": "van-1", "position": 1, "after": null, "added_distance_meters": 2345, "added_duration_seconds": 309, "added_waiting_seconds": -609, "arrival": "2026-11-02T08:04:31-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:04:31-05:00" }, { "vehicle_id": "van-2", "position": 1, "after": null, "added_distance_meters": 849, "added_duration_seconds": 127, "added_waiting_seconds": 0, "arrival": "2026-11-02T08:04:31-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:04:31-05:00" }, { "vehicle_id": "van-2", "position": 2, "after": "order-1003", "added_distance_meters": 1402, "added_duration_seconds": 211, "added_waiting_seconds": 0, "arrival": "2026-11-02T08:17:27-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:17:27-05:00" } ] }, { "job": "order-1005", "vehicle_id": "van-2", "position": 2, "after": "order-1003", "added_distance_meters": 3080, "added_duration_seconds": 357, "added_waiting_seconds": 0, "arrival": "2026-11-02T08:21:12-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:21:12-05:00", "alternatives": [ { "vehicle_id": "van-2", "position": 1, "after": null, "added_distance_meters": 3495, "added_duration_seconds": 431, "added_waiting_seconds": 0, "arrival": "2026-11-02T08:05:14-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:05:14-05:00" } ] } ], "unplaced": [], "routes": [ { "vehicle_id": "van-1", "stop_count": 5, "task_count": 3, "distance_meters": 7921, "duration_seconds": 1045, "service_seconds": 900, "waiting_seconds": 2152, "departure": "2026-11-02T08:00:00-05:00", "completion": "2026-11-02T09:08:17-05:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-11-02T08:00:00-05:00" }, { "type": "job", "id": "order-1001", "sequence": 1, "reachable": true, "leg_distance_meters": 1840, "leg_duration_seconds": 245, "leg_geometry": null, "arrival": "2026-11-02T08:04:05-05:00", "arrival_epoch": 1793624645, "distance_meters": 1840, "duration_seconds": 245 }, { "type": "job", "id": "order-1004", "sequence": 2, "reachable": true, "leg_distance_meters": 1233, "leg_duration_seconds": 172, "leg_geometry": null, "arrival": "2026-11-02T08:11:57-05:00", "arrival_epoch": 1793625117, "distance_meters": 3073, "duration_seconds": 417 }, { "type": "job", "id": "order-1002", "sequence": 3, "reachable": true, "leg_distance_meters": 3380, "leg_duration_seconds": 431, "leg_geometry": null, "arrival": "2026-11-02T08:24:08-05:00", "arrival_epoch": 1793625848, "distance_meters": 6453, "duration_seconds": 848, "waiting_seconds": 2152 }, { "type": "end", "reachable": true, "leg_distance_meters": 1468, "leg_duration_seconds": 197, "leg_geometry": null, "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 7921, "duration_seconds": 1045 } ] }, { "vehicle_id": "van-2", "stop_count": 4, "task_count": 2, "distance_meters": 10224, "duration_seconds": 1273, "service_seconds": 420, "waiting_seconds": 0, "departure": "2026-11-02T08:00:00-05:00", "completion": "2026-11-02T08:28:13-05:00", "unreachable_legs": 0, "violations": [], "violation_count": 0, "stops": [ { "type": "start", "departure": "2026-11-02T08:00:00-05:00" }, { "type": "job", "id": "order-1003", "sequence": 1, "reachable": true, "leg_distance_meters": 3635, "leg_duration_seconds": 482, "leg_geometry": null, "arrival": "2026-11-02T08:08:02-05:00", "arrival_epoch": 1793624882, "distance_meters": 3635, "duration_seconds": 482 }, { "type": "job", "id": "order-1005", "sequence": 2, "reachable": true, "leg_distance_meters": 4567, "leg_duration_seconds": 550, "leg_geometry": null, "arrival": "2026-11-02T08:21:12-05:00", "arrival_epoch": 1793625672, "distance_meters": 8202, "duration_seconds": 1032 }, { "type": "end", "reachable": true, "leg_distance_meters": 2022, "leg_duration_seconds": 241, "leg_geometry": null, "arrival": "2026-11-02T08:28:13-05:00", "arrival_epoch": 1793626093, "distance_meters": 10224, "duration_seconds": 1273 } ] } ], "summary": { "inserted": 2, "unplaced": 0, "added_distance_meters": 4585, "added_duration_seconds": 570, "violations": 0 } }, "meta": { "region": "NA", "profile": "car", "objective": "duration", "nearest": 25, "legs_measured": 23 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "424": { "description": "The routing engine refused this problem. Its reason is included where available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_REJECTED", "message": "The routing engine refused this problem. Its reason is included where available.", "status": 424, "doc_url": "/developer/errors/ENGINE_REJECTED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } }, "504": { "description": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "SOLVE_TIMEOUT", "message": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "status": 504, "doc_url": "/developer/errors/SOLVE_TIMEOUT" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alternatives": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10, "description": "How many other acceptable positions to return per job, 0-10, default 3." }, "departed_at": [], "insert": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "time_windows": { "type": [ "array", "null" ] } }, "required": [ "id", "location" ] }, "description": "The jobs to place, in the order they are placed: each like a job of `jobs`, with an id no job of the plan has." }, "jobs": { "type": "array", "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "location": { "type": "array" }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "time_windows": { "type": [ "array", "null" ] } }, "required": [ "id", "location" ] } }, "nearest": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "description": "How many of the plan's stops nearest to the new job (straight line) to try positions next to, 1-200, default 25. Every empty route is tried as well." }, "objective": { "type": [ "string", "null" ], "enum": [ "duration", "distance" ], "description": "`duration` (default): the position adding the least driver time, driving plus waiting. `distance`: the position adding the least distance." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "routes": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ] }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 } }, "vehicle_id": { "type": "string", "maxLength": 128 } }, "required": [ "vehicle_id" ] } }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ] }, "end": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0 }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0 }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "return_to_start": { "type": [ "boolean", "null" ] }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "start": { "type": [ "array", "null" ] }, "time_window": { "type": [ "array", "null" ] } }, "required": [ "id" ] } } }, "additionalProperties": false, "required": [ "insert", "jobs", "routes", "vehicles" ] }, "example": { "departed_at": "2026-11-02T08:00:00-05:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 }, "time_window": [ "2026-11-02T08:00:00-05:00", "2026-11-02T17:00:00-05:00" ] }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 }, "time_windows": [ [ "2026-11-02T09:00:00-05:00", "2026-11-02T12:00:00-05:00" ] ] }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 240, "amount": { "parcels": 1 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] }, { "vehicle_id": "van-2", "stops": [ "order-1003" ] } ], "insert": [ { "id": "order-1004", "location": { "lat": 45.5155, "lng": -73.5605 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1005", "location": { "lat": 45.492, "lng": -73.583 }, "service_seconds": 180, "amount": { "parcels": 9 } } ] } } } } } }, "/v1/routing/optimize": { "post": { "operationId": "routingOptimize", "tags": [ "routing" ], "summary": "Optimize routes", "description": "Plans routes across a fleet from jobs, shipments and vehicles. Problems above a small size return a job reference rather than a plan, as a full solve takes minutes.\n\nPlan routes across a fleet from jobs, vehicles and constraints you supply.", "x-superroute-capability": "routing.optimize", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "ga", "x-superroute-async": true, "x-superroute-docs": "/developer/capabilities/routing.optimize", "responses": { "200": { "description": "A plan: one route per vehicle that received work, the work no vehicle could take, and totals. `arrival` is written in Eastern time (America/Toronto); use `arrival_epoch` for arithmetic. A problem above the synchronous threshold, or one sent with `\"mode\": \"async\"`, answers 202 with a job instead (see the 202 example); collect the plan from GET /v1/jobs/{jobId}/result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.optimize" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "The caller's vehicle id." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "pickup", "delivery", "break", "end" ], "description": "What happens at this stop. `start` and `end` are the vehicle's own endpoints; `pickup` and `delivery` are the two legs of a shipment." }, "id": { "type": "string", "description": "The caller's id of the job or shipment served here. Absent on start, end and break." }, "shipment_leg": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Which leg of the shipment `id` names. Present on shipment stops only." }, "arrival": { "type": [ "string", "null" ], "description": "When the vehicle arrives, ISO 8601 with offset. Null when the engine reported no time." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "arrival_offset_seconds": { "type": [ "integer", "null" ], "description": "Seconds from the route's start to this stop. Present instead of `arrival` and `arrival_epoch` only when nothing in the request carried a time: no vehicle `time_window` and no job time window." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Distance driven from the route start to this stop, cumulative." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time from the route start to this stop, cumulative." }, "leg_distance_meters": { "type": "integer", "description": "Distance of the hop into this stop from the previous one." }, "leg_duration_seconds": { "type": "integer", "description": "Driving time of the hop into this stop from the previous one." }, "load": { "type": "array", "items": { "type": "number" }, "description": "What the vehicle carries when it leaves this stop, one figure per capacity dimension, in the order of `meta.capacity_dimensions`." } }, "required": [ "type" ] }, "description": "The stops in driving order, start and end included." }, "stop_count": { "type": "integer", "description": "Number of entries in `stops`." }, "task_count": { "type": "integer", "description": "Jobs and shipment legs served on this route (start, end and breaks not counted)." }, "distance_meters": { "type": "integer", "description": "Total distance driven." }, "duration_seconds": { "type": "integer", "description": "Total driving time. Service and waiting are reported separately." }, "service_seconds": { "type": "integer", "description": "Total service time at the stops." }, "waiting_seconds": { "type": "integer", "description": "Total time spent waiting for time windows to open." }, "geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the whole route. Null unless `options.geometry` was true." } }, "required": [ "vehicle_id", "stops" ] }, "description": "One route per vehicle that received work. A vehicle left idle does not appear." }, "unassigned": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The caller's id of the job or shipment that no vehicle took." }, "shipment_leg": { "type": [ "string", "null" ], "enum": [ "pickup", "delivery", null ], "description": "For a shipment, which leg was left over." }, "reason": { "type": "string", "description": "Why it was left over, as reported by the engine; `unspecified` when the engine gave no reason." } } }, "description": "Work no vehicle could take. Empty when everything was placed." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer", "description": "Routes in the plan (vehicles with work)." }, "assigned": { "type": "integer", "description": "Tasks placed on a route." }, "unassigned": { "type": "integer", "description": "Tasks left in `unassigned`." }, "distance_meters": { "type": "integer", "description": "Sum of every route's distance." }, "duration_seconds": { "type": "integer", "description": "Sum of every route's driving time." } } } }, "required": [ "routes", "unassigned", "summary" ] }, "meta": { "type": "object", "description": "Facts about the solve: `engine`, the engine version and solve id, and — when `constraints.balance` was `tolerance`, `zone`, `hours` or `zone_hours` — a `balance` report.", "properties": { "engine": { "type": "string", "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ] }, "engine_version": { "type": "string", "description": "The version of the engine that answered." }, "solve_id": { "type": "string", "description": "The engine's id for this solve. Quote it with `request_id` when asking support about a plan." }, "capacity_dimensions": { "type": "array", "items": { "type": "string" }, "description": "The names of the capacity dimensions, in the order every `load` lists them. A list capacity is named by position (`\"0\"`, `\"1\"`, ...)." }, "rule_notices": { "type": "array", "description": "Present only when the request used a routing rule the engine approximated or applied with something left out; each entry is also a RULE_APPROXIMATED or RULE_ADJUSTED warning.", "items": { "type": "object", "properties": { "rule": { "type": "string", "description": "The rule, as named in the capability's `routing_rules`." }, "engine": { "type": "string", "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ] }, "status": { "type": "string", "enum": [ "approximated", "adjusted" ] }, "reason": { "type": "string", "enum": [ "engine_unsupported", "depot_limit", "depot_unreachable", "place_unreachable" ] }, "field": { "type": "string", "description": "The request field that carried the rule." } } } }, "balance": { "type": "object", "description": "Present only when `constraints.balance` was `tolerance`, `zone`, `hours` or `zone_hours`. `satisfied` false means the band could not be met without leaving work unassigned and the most even plan found was kept; a `BALANCE_DEGRADED` warning accompanies it. `repair_passes` counts the extra solves spent evening the plan out; they are not billed.", "properties": { "mode": { "type": "string", "enum": [ "tolerance", "zone", "hours", "zone_hours" ] }, "tolerance_percent": { "type": "integer" }, "unit": { "type": "string", "enum": [ "tasks", "seconds" ], "description": "`tasks` for tolerance and zone, `seconds` of working time per vehicle for hours and zone_hours." }, "lower_bound": { "type": "integer" }, "upper_bound": { "type": "integer" }, "min_tasks": { "type": "integer", "description": "tolerance and zone: the lightest vehicle's tasks." }, "max_tasks": { "type": "integer", "description": "tolerance and zone: the heaviest vehicle's tasks." }, "min_seconds": { "type": "integer", "description": "hours: the shortest working day." }, "max_seconds": { "type": "integer", "description": "hours: the longest working day." }, "zones": { "type": "integer", "description": "zone and zone_hours: zones cut, one per vehicle." }, "unplaced": { "type": "integer", "description": "zone and zone_hours: tasks no zone's vehicle could take." }, "release_solves": { "type": "integer", "description": "zone and zone_hours: the one extra solve spent re-homing what a zone could not fit." }, "repair_passes": { "type": "integer" }, "satisfied": { "type": "boolean" }, "groups": { "type": "array", "description": "tolerance and hours: present only when the vehicles' skills split them into groups that cannot take each other's tasks. Each group is balanced on its own work; `lower_bound` and `upper_bound` above are then the loosest of the groups' bounds, and `satisfied` is true only when every group is.", "items": { "type": "object", "properties": { "vehicles": { "type": "integer", "description": "Vehicles in the group." }, "lower_bound": { "type": "integer" }, "upper_bound": { "type": "integer", "description": "hours only." }, "min_tasks": { "type": "integer", "description": "tolerance only." }, "max_tasks": { "type": "integer", "description": "tolerance only." }, "min_seconds": { "type": "integer", "description": "hours only." }, "max_seconds": { "type": "integer", "description": "hours only." }, "satisfied": { "type": "boolean" } } } } } } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.optimize", "billing": { "unit": "node", "quantity": 5, "counted": true, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2 } }, "data": { "routes": [ { "vehicle_id": "van-2", "stops": [ { "type": "start", "arrival": "2026-11-02T08:31:07-05:00", "arrival_epoch": 1793626267, "distance_meters": 0, "duration_seconds": 0, "load": [ 6 ] }, { "type": "job", "arrival": "2026-11-02T08:35:11-05:00", "arrival_epoch": 1793626511, "distance_meters": 1839, "duration_seconds": 244, "leg_distance_meters": 1839, "leg_duration_seconds": 244, "id": "order-1001", "load": [ 4 ] }, { "type": "job", "arrival": "2026-11-02T08:47:56-05:00", "arrival_epoch": 1793627276, "distance_meters": 5338, "duration_seconds": 709, "leg_distance_meters": 3499, "leg_duration_seconds": 465, "id": "order-1003", "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T09:00:00-05:00", "arrival_epoch": 1793628000, "distance_meters": 9220, "duration_seconds": 1193, "leg_distance_meters": 3882, "leg_duration_seconds": 484, "id": "order-1002", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 10687, "duration_seconds": 1390, "leg_distance_meters": 1467, "leg_duration_seconds": 197, "load": [ 0 ] } ], "stop_count": 5, "task_count": 3, "distance_meters": 10687, "duration_seconds": 1390, "service_seconds": 840, "waiting_seconds": 0, "geometry": null } ], "unassigned": [], "summary": { "routes": 1, "assigned": 3, "unassigned": 0, "distance_meters": 10687, "duration_seconds": 1390 } }, "meta": { "engine": "sroute2", "engine_version": "1.6.1", "solve_id": "fbae5d6c-71ab-43c5-b619-6ef6fe3eaee7", "capacity_dimensions": [ "0" ] } } } } }, "202": { "description": "Accepted: the work is queued as a job and billed now. Poll GET /v1/jobs/{jobId} (the `Location` header) and collect the result from `result_url`; a verified `callback` is called when it ends.", "headers": { "Location": { "description": "Where to poll for the job.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.optimize" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "object", "description": "The job that will produce the result.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on this answer." }, "capability": { "type": "string", "description": "The capability the job runs." }, "poll_after_ms": { "type": "integer", "description": "How long to wait before the first poll." }, "result_url": { "type": "string", "description": "Where to collect the result once the job has succeeded." }, "cancel_url": { "type": "string", "description": "Where to cancel the job." } } } }, "required": [ "job" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.optimize", "billing": { "unit": "node", "quantity": 5, "counted": true, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2 } }, "data": { "job": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "queued", "capability": "routing.optimize", "poll_after_ms": 1000, "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel" } }, "meta": { "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "424": { "description": "The routing engine refused this problem. Its reason is included where available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_REJECTED", "message": "The routing engine refused this problem. Its reason is included where available.", "status": 424, "doc_url": "/developer/errors/ENGINE_REJECTED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } }, "504": { "description": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "SOLVE_TIMEOUT", "message": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "status": 504, "doc_url": "/developer/errors/SOLVE_TIMEOUT" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "constraints": { "type": [ "object", "null" ], "properties": { "balance": { "type": [ "string", "null" ], "enum": [ "none", "balanced", "min_change", "sla_protect", "tolerance", "zone", "hours", "zone_hours" ], "description": "How the work is spread across vehicles. `balanced`, `min_change` and `sla_protect` are engine presets (sroute2, sroute2t or sroute3 only). `tolerance`, `zone`, `hours` and `zone_hours` are enforced by the platform on either engine, on routing.optimize only, and reported in `meta.balance`: `tolerance` holds every vehicle's task count within `balance_tolerance` percent of the balanced share (the twin of the Superroute route builder's mode 4); `zone` first cuts the tasks into one compact, non-overlapping zone per vehicle so routes never cross (mode 5); `hours` evens out working time — driving including the leg back to an end point, setup, service and waiting — by solving from an equal split, then, while a vehicle sits outside the band, closing every vehicle's working day (its `time_window`) at the band's top and a step tighter, handing the tasks the busiest give up to the lightest by their measured time per task, and re-solving, at most twice (mode 6); `zone_hours` cuts the zones of `zone` on time instead of task counts — a slow area gets a smaller zone — and, once the routes are timed, re-cuts them from each vehicle's measured working day and re-solves, at most twice, so routes never cross and the days come out even (mode 7). `none` or omitted: no balancing." }, "balance_tolerance": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100, "description": "The band, in percent of the balanced share, for `tolerance`, `zone`, `hours` and `zone_hours`. 1-100; defaults to 15 when omitted. Ignored for the engine presets." }, "deliveries_before_pickups": { "type": [ "boolean", "null" ], "description": "Every delivery of a route before its first pickup (backhaul); unassigned reason `deliveries_first`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "incompatible_goods_classes": { "type": [ "array", "null" ], "items": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "maxItems": 500, "description": "Pairs of goods classes that may not ride in one vehicle, e.g. `[[\"food\", \"chemicals\"]]`; unassigned reason `incompatible_goods`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the vehicles are shared out between the classes of each pair before the solve, so a vehicle carries one of them." }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 86400, "description": "The ride time limit of every shipment without its own `max_ride_seconds`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "merge_stops": { "type": [ "object", "null" ], "properties": { "max_stops": { "type": [ "integer", "null" ], "minimum": 2, "maximum": 50 }, "radius_meters": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Required when constraints.merge_stops is present." }, "same_window_only": { "type": [ "boolean", "null" ] } }, "description": "Nearby jobs sent as one stop: jobs within `radius_meters` (1-1000) of one another that share skills, priority, group, goods class and amount dimensions and have at most one time window go as one stop of at most `max_stops` (2-50, default 10) jobs; the windows are intersected, or with `same_window_only` must be equal. Answered one stop per job. Jobs with alternatives are never merged. Every engine; routing.optimize only." }, "region_filter": { "type": [ "boolean", "null" ] }, "reload": { "type": [ "object", "null" ], "properties": { "depots": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Required when constraints.reload is present.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "loading_bays": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many vehicles may load at the depot in one slot of `slot_seconds` (default 1800); unassigned reason `loading_bay`. `sroute2t` 1.0.20 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "location": { "type": "array" } } } }, "loading_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 14400 }, "max_reloads": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "slot_seconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 14400 } }, "description": "Vehicles may return to a depot to load again: `depots` (1-10, each `{id?, location, loading_bays?}`), `loading_seconds` (default 900), `max_reloads` (1-5, default 1). Routes carry `reload` stops with `depot_index`, `depot_id`, `location` and `service_seconds` (and `trip` when approximated). Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is built as sequential trips: the work a trip leaves out is planned on a further trip from the nearest depot." }, "use_all_vehicles": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How strongly to put every vehicle to work: `off` (default), `low`, `normal` or `high`. Native on `sroute2t` 1.0.19 or later and on `sroute3`, and on `sroute2` as its `orders` balance (which no other balance preset may accompany). Approximated on `sroute`, on routing.optimize only, by capping every vehicle's task count." }, "waiting_cost": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How much time spent waiting for a window costs: `off` (default), `low`, `normal` or `high`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." } } }, "engine": { "type": [ "string", "null" ], "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ], "description": "Which solver serves the request. `sroute2` (default when omitted) and `sroute`, the direct solver, are available to every account; `sroute2t` is an engine of its own that speaks the same router API as sroute2 and is available only to accounts it has been enabled for — otherwise the request is refused with ENGINE_NOT_ENABLED (403). `sroute3` is another engine of its own, offered alongside sroute2t on the same terms: it answers the same router API and plans every routing rule sroute2t plans natively, each from the sroute3 version named in `routing_rules`. Refine, what-if and the engine balance presets run on sroute2, sroute2t or sroute3 only. Any other value is refused with VALIDATION_FAILED (422), detail code INVALID on `engine`, on every transport." }, "jobs": { "type": "array", "maxItems": 10000, "items": { "type": "object", "properties": { "alternatives": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array" }, "time_window": { "type": [ "array", "null" ] } } }, "maxItems": 10, "description": "Up to 10 other places the job may be served at instead of its `location`, each `{id?, location, time_window?}`; exactly one place is served. The stop reports `served_at` (`location` or `alternative`) and, at an alternative, `alternative_index` (0-based), `alternative_id` and the `location` served. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There one place is chosen before the solve: the nearest to the vehicles' starts whose time window a vehicle can meet." }, "amount": { "type": [ "array", "null" ] }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The job's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array", "description": "Required when jobs is present." }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "release_at": { "description": "When the job's goods are ready at the depot (ISO-8601 with an offset, or epoch seconds): the trip carrying the job is loaded no earlier. Unassigned reason `release_time`. Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the job only goes to a vehicle whose time window starts at or after its release." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "setup_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": [ "array", "null" ] }, "time_windows": { "type": [ "array", "null" ] } } } }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ] } } }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "shipments": { "type": "array", "maxItems": 5000, "items": { "type": "object", "properties": { "delivery": { "type": "array", "description": "Required when shipments is present." }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The shipment's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "The longest the shipment may be on board, from its pickup to its delivery, in seconds; unassigned reason `max_ride_time`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "pickup": { "type": "array", "description": "Required when shipments is present." } } } }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "breaks": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "duration_seconds": [], "places": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "location": { "type": "array" } } }, "maxItems": 10, "description": "Up to 10 places `{location}` the break must be taken at, a detour the engine plans; the break stop carries the `location` it was taken at. `sroute2t` 1.0.21 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "skip_policy": { "type": [ "string", "null" ], "enum": [ "if_no_intersection", "if_route_ends_before_window_end" ], "description": "When the break may be left out: `if_no_intersection` (the route does not overlap its window) or `if_route_ends_before_window_end` (the route ends before the window closes). The route reports `skipped_breaks` as 0-based break indexes, and break stops carry `break_index`. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is solved again without the breaks the first plan does not need, and kept only when it leaves no more work unassigned." }, "windows": [] } }, "maxItems": 10 }, "capacity": { "type": [ "array", "null" ] }, "end": { "type": [ "array", "null" ] }, "ev_range_meters": { "type": [ "integer", "null" ], "minimum": 1, "description": "An electric vehicle's range on a full charge, in metres. The vehicle starts full and never charges on the way, so its route covers at most the range less `ev_reserve_meters`; unassigned reason `range` on sroute2t and sroute3. On `sroute` and `sroute2` it is the vehicle's maximum distance (its own `max_distance_meters` when shorter), which is exact for a distance range; `sroute2t` and `sroute3` plan it natively." }, "ev_reserve_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The part of `ev_range_meters` kept in reserve, in metres. Ignored without `ev_range_meters`." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "latest_departure_at": { "description": "The latest time the vehicle may leave its start (ISO-8601 with an offset, or epoch seconds); unassigned reason `latest_departure`. Cannot be combined with `shifts`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0 }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0 }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "return_to_start": { "type": [ "boolean", "null" ] }, "shifts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "end": { "type": [ "array", "null" ] }, "from": [], "start": { "type": [ "array", "null" ] }, "to": [] } }, "maxItems": 6, "description": "Working periods of the vehicle, each `{from, to, start?, end?}` (times as ISO-8601 with an offset or epoch seconds, not overlapping; locations `{lat, lng}`), at most 6. Planned as one engine vehicle per shift with the shift as its time window, a full capacity and the shift's own start and end when given; a break goes to the first shift its window fits in. Answered as one route per vehicle with `shift_end` / `shift_start` stops (`shift_index`) between shifts. Every engine; routing.optimize only." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "start": { "type": [ "array", "null" ] }, "time_window": { "type": [ "array", "null" ] } } } } }, "additionalProperties": false, "required": [ "vehicles" ] }, "example": { "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ], "time_window": [ "2026-11-02T08:00:00-05:00", "2026-11-02T17:00:00-05:00" ] }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ] } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": [ 2 ] }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": [ 3 ], "time_windows": [ [ "2026-11-02T09:00:00-05:00", "2026-11-02T12:00:00-05:00" ] ] }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 240, "amount": [ 1 ] } ] } } } } } }, "/v1/routing/presets": { "get": { "operationId": "routingPresets", "tags": [ "platform" ], "summary": "List balance presets", "description": "Lists the engine's balance presets and the objective each optimizes for, together with the tolerance band the platform enforces itself and the percentage range it accepts. Free of charge, as it is required in order to determine the valid values of a request field.\n\nList what this key can call, at what price, against which quota.", "x-superroute-capability": "platform.capabilities", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.capabilities", "responses": { "200": { "description": "The balance presets, priorities and routing rules of one engine (`?engine=`, default sroute2). Free. The example is shortened to three presets and two routing rules.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "presets": { "type": "object", "additionalProperties": { "type": "object", "properties": { "strategies": { "type": "array", "items": { "type": "string" }, "description": "The objectives the preset optimizes, in order." }, "weights": { "type": [ "object", "array" ], "description": "Weight per strategy; an empty list when the preset has none." }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "description": "Grouping for display." }, "hidden": { "type": "boolean", "description": "Kept for compatibility; not offered in new integrations." }, "alias_of": { "type": [ "string", "null" ], "description": "The preset this one is another name for." }, "new": { "type": "boolean" } } }, "description": "Preset name => definition. Send the name as `constraints.balance`." }, "engine": { "type": "string", "description": "The engine described." }, "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines this account may use." }, "default_engine": { "type": "string", "description": "The engine used when a request names none." }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "integer", "description": "The `priority` value to send." } } }, "description": "The named priority levels." }, "priority_rule": { "type": "string" }, "routing_rules": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The request fields that carry the rule." }, "engines": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "native", "approx", "unsupported" ] }, "min_version": { "type": "string", "description": "The first engine version that plans it." } } }, "description": "Engine => support." }, "approximation": { "type": "string", "description": "How the platform approximates the rule on an engine that cannot plan it. Present for `approx` only." } } } }, "tolerance": { "type": "object", "properties": { "balance": { "type": "string", "description": "The `constraints.balance` value." }, "field": { "type": "string", "description": "The request field that sets the tolerance." }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "default": { "type": "integer" }, "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines it works on." }, "operations": { "type": "array", "items": { "type": "string" }, "description": "Capabilities it applies to." }, "measured_in": { "type": "string", "description": "What the tolerance is measured in." }, "rule": { "type": "string", "description": "How the platform enforces it." } } }, "zone": { "type": "object", "properties": { "balance": { "type": "string", "description": "The `constraints.balance` value." }, "field": { "type": "string", "description": "The request field that sets the tolerance." }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "default": { "type": "integer" }, "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines it works on." }, "operations": { "type": "array", "items": { "type": "string" }, "description": "Capabilities it applies to." }, "measured_in": { "type": "string", "description": "What the tolerance is measured in." }, "rule": { "type": "string", "description": "How the platform enforces it." } } }, "hours": { "type": "object", "properties": { "balance": { "type": "string", "description": "The `constraints.balance` value." }, "field": { "type": "string", "description": "The request field that sets the tolerance." }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "default": { "type": "integer" }, "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines it works on." }, "operations": { "type": "array", "items": { "type": "string" }, "description": "Capabilities it applies to." }, "measured_in": { "type": "string", "description": "What the tolerance is measured in." }, "rule": { "type": "string", "description": "How the platform enforces it." } } }, "zone_hours": { "type": "object", "properties": { "balance": { "type": "string", "description": "The `constraints.balance` value." }, "field": { "type": "string", "description": "The request field that sets the tolerance." }, "unit": { "type": "string" }, "min": { "type": "integer" }, "max": { "type": "integer" }, "default": { "type": "integer" }, "engines": { "type": "array", "items": { "type": "string" }, "description": "Engines it works on." }, "operations": { "type": "array", "items": { "type": "string" }, "description": "Capabilities it applies to." }, "measured_in": { "type": "string", "description": "What the tolerance is measured in." }, "rule": { "type": "string", "description": "How the platform enforces it." } } } } }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "presets": { "none": { "strategies": [], "weights": [], "title": "No balance", "description": "Cheapest plan; drivers may be uneven", "category": "balance", "hidden": false, "alias_of": null, "new": false }, "min_change": { "strategies": [ "orders" ], "weights": { "orders": 0.3 }, "title": "Minimal change", "description": "Touch as little as possible of the current plan", "category": "execution", "hidden": false, "alias_of": null, "new": false }, "balanced": { "strategies": [ "time", "distance" ], "weights": { "time": 0.5, "distance": 0.5 }, "title": "Balanced", "description": "", "category": "balance", "hidden": true, "alias_of": "time", "new": false } }, "engine": "sroute2", "engines": [ "sroute", "sroute2" ], "default_engine": "sroute2", "priorities": [ { "name": "hold", "value": 10 }, { "name": "flexible", "value": 20 }, { "name": "economy", "value": 30 }, { "name": "standard", "value": 40 }, { "name": "express", "value": 50 }, { "name": "rush", "value": 60 }, { "name": "emergency", "value": 70 }, { "name": "due", "value": 80 }, { "name": "overdue", "value": 90 } ], "priority_rule": "Priority is 0-100. When the problem is infeasible, lower-priority tasks are dropped to `unassigned` first. These named levels are the same ladder the Superroute platform plans with.", "routing_rules": [ { "rule": "max_ride", "fields": [ "shipments.*.max_ride_seconds", "constraints.max_ride_seconds" ], "engines": { "sroute": { "status": "unsupported" }, "sroute2": { "status": "unsupported" }, "sroute2t": { "status": "native", "min_version": "1.0.19" }, "sroute3": { "status": "native", "min_version": "1.0.0" } } }, { "rule": "latest_departure", "fields": [ "vehicles.*.latest_departure_at" ], "engines": { "sroute": { "status": "unsupported" }, "sroute2": { "status": "unsupported" }, "sroute2t": { "status": "native", "min_version": "1.0.19" }, "sroute3": { "status": "native", "min_version": "1.0.0" } } } ], "hours": { "balance": "hours", "field": "constraints.balance_tolerance", "unit": "percent", "min": 1, "max": 100, "default": 15, "engines": [ "sroute", "sroute2" ], "operations": [ "routing.optimize" ], "measured_in": "seconds of working time per vehicle (driving including the return to an end point, setup, service, waiting), read from the solved plan", "rule": "Solves, measures every vehicle's working time, and while a vehicle sits above the band closes every vehicle's working day at the band's top (then a step tighter), hands the tasks the busiest give up to the lightest by their measured time per task, and re-solves, at most twice. A re-solve is kept only when it evens the day out without leaving more work unassigned. Reported back in meta.balance." }, "zone_hours": { "balance": "zone_hours", "field": "constraints.balance_tolerance", "unit": "percent", "min": 1, "max": 100, "default": 15, "engines": [ "sroute", "sroute2" ], "operations": [ "routing.optimize" ], "measured_in": "seconds of working time per vehicle (driving including the return to an end point, setup, service, waiting), read from the solved plan; the zones are cut on each task's setup + service plus a travel estimate", "rule": "Cuts the tasks into one compact, non-overlapping zone per vehicle on estimated time — a slow area gets a smaller zone — pins every task to its zone's vehicle, solves, then while a vehicle's measured working time sits outside the band scales the zone targets by expected / measured, re-cuts and re-solves, at most twice. Routes never cross; a task its zone's vehicle cannot fit is offered once to the others. Reported back in meta.balance." }, "zone": { "balance": "zone", "field": "constraints.balance_tolerance", "unit": "percent", "min": 1, "max": 100, "default": 15, "engines": [ "sroute", "sroute2" ], "operations": [ "routing.optimize" ], "measured_in": "tasks (a shipment counts as two: its pickup and its delivery)", "rule": "Cuts the tasks into one compact, non-overlapping zone per vehicle, each holding that vehicle's balanced share within the tolerance, and lets the solver sequence inside each zone — routes never cross. A task its zone's vehicle cannot fit is offered once to the others. Reported back in meta.balance." }, "tolerance": { "balance": "tolerance", "field": "constraints.balance_tolerance", "unit": "percent", "min": 1, "max": 100, "default": 15, "engines": [ "sroute", "sroute2" ], "operations": [ "routing.optimize" ], "measured_in": "tasks (a shipment counts as two: its pickup and its delivery)", "rule": "Caps every vehicle at the balanced share plus the tolerance, then re-solves under a lower ceiling if a vehicle still came out below the band. Route quality stays close to no balancing at all while the gap between vehicles stays inside the tolerance. Reported back in meta.balance." } } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "parameters": [ { "name": "engine", "in": "query", "required": false, "description": "Which router-API engine answers. `sroute2` (default when omitted), or `sroute2t` / `sroute3` for accounts they have been enabled for — otherwise ENGINE_NOT_ENABLED (403). `sroute` has no presets and is refused with VALIDATION_FAILED.", "schema": { "type": "string", "enum": [ "sroute2", "sroute2t", "sroute3" ], "default": "sroute2" } } ] } }, "/v1/routing/refine": { "post": { "operationId": "routingRefine", "tags": [ "routing" ], "summary": "Refine an existing plan", "description": "Re-optimizes an existing plan, optionally freezing stops that must not move. Intended for use after a manual edit, in place of a full re-solve.\n\nRe-optimize an existing plan locally or globally, keeping chosen stops frozen.", "x-superroute-capability": "routing.refine", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "ga", "x-superroute-async": true, "x-superroute-docs": "/developer/capabilities/routing.refine", "responses": { "200": { "description": "The refined plan, in the same shape as routing.optimize. Stops listed in `freeze` keep their vehicle and order; the rest may move between vehicles. Billed on the nodes the plan holds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.refine" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "The caller's vehicle id." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "pickup", "delivery", "break", "end" ], "description": "What happens at this stop. `start` and `end` are the vehicle's own endpoints; `pickup` and `delivery` are the two legs of a shipment." }, "id": { "type": "string", "description": "The caller's id of the job or shipment served here. Absent on start, end and break." }, "shipment_leg": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Which leg of the shipment `id` names. Present on shipment stops only." }, "arrival": { "type": [ "string", "null" ], "description": "When the vehicle arrives, ISO 8601 with offset. Null when the engine reported no time." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "arrival_offset_seconds": { "type": [ "integer", "null" ], "description": "Seconds from the route's start to this stop. Present instead of `arrival` and `arrival_epoch` only when nothing in the request carried a time: no vehicle `time_window` and no job time window." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Distance driven from the route start to this stop, cumulative." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time from the route start to this stop, cumulative." }, "leg_distance_meters": { "type": "integer", "description": "Distance of the hop into this stop from the previous one." }, "leg_duration_seconds": { "type": "integer", "description": "Driving time of the hop into this stop from the previous one." }, "load": { "type": "array", "items": { "type": "number" }, "description": "What the vehicle carries when it leaves this stop, one figure per capacity dimension, in the order of `meta.capacity_dimensions`." } }, "required": [ "type" ] }, "description": "The stops in driving order, start and end included." }, "stop_count": { "type": "integer", "description": "Number of entries in `stops`." }, "task_count": { "type": "integer", "description": "Jobs and shipment legs served on this route (start, end and breaks not counted)." }, "distance_meters": { "type": "integer", "description": "Total distance driven." }, "duration_seconds": { "type": "integer", "description": "Total driving time. Service and waiting are reported separately." }, "service_seconds": { "type": "integer", "description": "Total service time at the stops." }, "waiting_seconds": { "type": "integer", "description": "Total time spent waiting for time windows to open." }, "geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the whole route. Null unless `options.geometry` was true." } }, "required": [ "vehicle_id", "stops" ] }, "description": "One route per vehicle that received work. A vehicle left idle does not appear." }, "unassigned": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The caller's id of the job or shipment that no vehicle took." }, "shipment_leg": { "type": [ "string", "null" ], "enum": [ "pickup", "delivery", null ], "description": "For a shipment, which leg was left over." }, "reason": { "type": "string", "description": "Why it was left over, as reported by the engine; `unspecified` when the engine gave no reason." } } }, "description": "Work no vehicle could take. Empty when everything was placed." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer", "description": "Routes in the plan (vehicles with work)." }, "assigned": { "type": "integer", "description": "Tasks placed on a route." }, "unassigned": { "type": "integer", "description": "Tasks left in `unassigned`." }, "distance_meters": { "type": "integer", "description": "Sum of every route's distance." }, "duration_seconds": { "type": "integer", "description": "Sum of every route's driving time." } } } }, "required": [ "routes", "unassigned", "summary" ] }, "meta": { "type": "object", "description": "Facts about the solve.", "properties": { "engine": { "type": "string", "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ], "description": "The engine that answered." }, "engine_version": { "type": "string", "description": "That engine's version." }, "solve_id": { "type": "string", "description": "The engine's id for this solve. Quote it with `request_id` when asking support about a plan." }, "capacity_dimensions": { "type": "array", "items": { "type": "string" }, "description": "The names of the capacity dimensions, in the order `load` reports them. A list capacity is named by position (`\"0\"`, `\"1\"`, ...)." }, "balance": { "type": "object", "description": "Present only when `constraints.balance` was `tolerance`, `zone`, `hours` or `zone_hours`; see the routing.optimize reference for its fields.", "properties": [] }, "rule_notices": { "type": "array", "items": { "type": "object", "properties": [] }, "description": "Present only when a routing rule was approximated or adjusted; each entry is also a RULE_APPROXIMATED or RULE_ADJUSTED warning." }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "Present on a queued answer." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.refine", "billing": { "unit": "node", "quantity": 5, "counted": true, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2, "route_stops": 0 } }, "data": { "routes": [ { "vehicle_id": "van-1", "stops": [ { "type": "start", "arrival": "2026-11-02T08:00:00-05:00", "arrival_epoch": 1793624400, "distance_meters": 0, "duration_seconds": 0, "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T08:08:01-05:00", "arrival_epoch": 1793624881, "distance_meters": 3635, "duration_seconds": 481, "leg_distance_meters": 3635, "leg_duration_seconds": 481, "id": "order-1003", "load": [ 2 ] }, { "type": "job", "arrival": "2026-11-02T08:18:34-05:00", "arrival_epoch": 1793625514, "distance_meters": 6563, "duration_seconds": 874, "leg_distance_meters": 2928, "leg_duration_seconds": 393, "id": "order-1001", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T08:27:15-05:00", "arrival_epoch": 1793626035, "distance_meters": 8356, "duration_seconds": 1095, "leg_distance_meters": 1793, "leg_duration_seconds": 221, "load": [ 0 ] } ], "stop_count": 4, "task_count": 2, "distance_meters": 8356, "duration_seconds": 1095, "service_seconds": 540, "waiting_seconds": 0, "geometry": null }, { "vehicle_id": "van-2", "stops": [ { "type": "start", "arrival": "2026-11-02T08:56:13-05:00", "arrival_epoch": 1793627773, "distance_meters": 0, "duration_seconds": 0, "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T09:00:00-05:00", "arrival_epoch": 1793628000, "distance_meters": 1610, "duration_seconds": 227, "leg_distance_meters": 1610, "leg_duration_seconds": 227, "id": "order-1002", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 3077, "duration_seconds": 424, "leg_distance_meters": 1467, "leg_duration_seconds": 197, "load": [ 0 ] } ], "stop_count": 3, "task_count": 1, "distance_meters": 3077, "duration_seconds": 424, "service_seconds": 300, "waiting_seconds": 0, "geometry": null } ], "unassigned": [], "summary": { "routes": 2, "assigned": 3, "unassigned": 0, "distance_meters": 11433, "duration_seconds": 1519 } }, "meta": { "engine": "sroute2", "engine_version": "1.6.1", "capacity_dimensions": [ "0" ] } } } } }, "202": { "description": "Accepted: the work is queued as a job and billed now. Poll GET /v1/jobs/{jobId} (the `Location` header) and collect the result from `result_url`; a verified `callback` is called when it ends.", "headers": { "Location": { "description": "Where to poll for the job.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.refine" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "object", "description": "The job that will produce the result.", "properties": { "id": { "type": "string", "description": "The job id, `job_...`." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Always `queued` on this answer." }, "capability": { "type": "string", "description": "The capability the job runs." }, "poll_after_ms": { "type": "integer", "description": "How long to wait before the first poll." }, "result_url": { "type": "string", "description": "Where to collect the result once the job has succeeded." }, "cancel_url": { "type": "string", "description": "Where to cancel the job." } } } }, "required": [ "job" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.refine", "billing": { "unit": "node", "quantity": 5, "counted": true, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2, "route_stops": 0 } }, "data": { "job": { "id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u", "status": "queued", "capability": "routing.refine", "poll_after_ms": 1000, "result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result", "cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel" } }, "meta": { "mode": "async" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "424": { "description": "The routing engine refused this problem. Its reason is included where available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_REJECTED", "message": "The routing engine refused this problem. Its reason is included where available.", "status": 424, "doc_url": "/developer/errors/ENGINE_REJECTED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } }, "504": { "description": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "SOLVE_TIMEOUT", "message": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "status": 504, "doc_url": "/developer/errors/SOLVE_TIMEOUT" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "constraints": { "type": [ "object", "null" ], "properties": { "balance": { "type": [ "string", "null" ], "enum": [ "none", "balanced", "min_change", "sla_protect", "tolerance", "zone", "hours", "zone_hours" ], "description": "How the work is spread across vehicles. `balanced`, `min_change` and `sla_protect` are engine presets (sroute2, sroute2t or sroute3 only). `tolerance`, `zone`, `hours` and `zone_hours` are enforced by the platform on either engine, on routing.optimize only, and reported in `meta.balance`: `tolerance` holds every vehicle's task count within `balance_tolerance` percent of the balanced share (the twin of the Superroute route builder's mode 4); `zone` first cuts the tasks into one compact, non-overlapping zone per vehicle so routes never cross (mode 5); `hours` evens out working time — driving including the leg back to an end point, setup, service and waiting — by solving from an equal split, then, while a vehicle sits outside the band, closing every vehicle's working day (its `time_window`) at the band's top and a step tighter, handing the tasks the busiest give up to the lightest by their measured time per task, and re-solving, at most twice (mode 6); `zone_hours` cuts the zones of `zone` on time instead of task counts — a slow area gets a smaller zone — and, once the routes are timed, re-cuts them from each vehicle's measured working day and re-solves, at most twice, so routes never cross and the days come out even (mode 7). `none` or omitted: no balancing. On this operation only the engine presets apply; `tolerance`, `zone`, `hours` and `zone_hours` are refused with VALIDATION_FAILED." }, "balance_tolerance": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100, "description": "The band, in percent of the balanced share, for `tolerance`, `zone`, `hours` and `zone_hours`. 1-100; defaults to 15 when omitted. Ignored for the engine presets." }, "deliveries_before_pickups": { "type": [ "boolean", "null" ], "description": "Every delivery of a route before its first pickup (backhaul); unassigned reason `deliveries_first`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "incompatible_goods_classes": { "type": [ "array", "null" ], "items": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "maxItems": 500, "description": "Pairs of goods classes that may not ride in one vehicle, e.g. `[[\"food\", \"chemicals\"]]`; unassigned reason `incompatible_goods`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the vehicles are shared out between the classes of each pair before the solve, so a vehicle carries one of them." }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 86400, "description": "The ride time limit of every shipment without its own `max_ride_seconds`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "merge_stops": { "type": [ "object", "null" ], "properties": { "max_stops": { "type": [ "integer", "null" ], "minimum": 2, "maximum": 50 }, "radius_meters": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Required when constraints.merge_stops is present." }, "same_window_only": { "type": [ "boolean", "null" ] } }, "description": "Nearby jobs sent as one stop: jobs within `radius_meters` (1-1000) of one another that share skills, priority, group, goods class and amount dimensions and have at most one time window go as one stop of at most `max_stops` (2-50, default 10) jobs; the windows are intersected, or with `same_window_only` must be equal. Answered one stop per job. Jobs with alternatives are never merged. Every engine; routing.optimize only." }, "region_filter": { "type": [ "boolean", "null" ] }, "reload": { "type": [ "object", "null" ], "properties": { "depots": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Required when constraints.reload is present.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "loading_bays": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many vehicles may load at the depot in one slot of `slot_seconds` (default 1800); unassigned reason `loading_bay`. `sroute2t` 1.0.20 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "location": { "type": "array" } } } }, "loading_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 14400 }, "max_reloads": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "slot_seconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 14400 } }, "description": "Vehicles may return to a depot to load again: `depots` (1-10, each `{id?, location, loading_bays?}`), `loading_seconds` (default 900), `max_reloads` (1-5, default 1). Routes carry `reload` stops with `depot_index`, `depot_id`, `location` and `service_seconds` (and `trip` when approximated). Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is built as sequential trips: the work a trip leaves out is planned on a further trip from the nearest depot." }, "use_all_vehicles": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How strongly to put every vehicle to work: `off` (default), `low`, `normal` or `high`. Native on `sroute2t` 1.0.19 or later and on `sroute3`, and on `sroute2` as its `orders` balance (which no other balance preset may accompany). Approximated on `sroute`, on routing.optimize only, by capping every vehicle's task count." }, "waiting_cost": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How much time spent waiting for a window costs: `off` (default), `low`, `normal` or `high`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." } } }, "engine": { "type": [ "string", "null" ], "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ], "description": "Which solver serves the request. `sroute2` (default when omitted) and `sroute`, the direct solver, are available to every account; `sroute2t` is an engine of its own that speaks the same router API as sroute2 and is available only to accounts it has been enabled for — otherwise the request is refused with ENGINE_NOT_ENABLED (403). `sroute3` is another engine of its own, offered alongside sroute2t on the same terms: it answers the same router API and plans every routing rule sroute2t plans natively, each from the sroute3 version named in `routing_rules`. Refine, what-if and the engine balance presets run on sroute2, sroute2t or sroute3 only. Any other value is refused with VALIDATION_FAILED (422), detail code INVALID on `engine`, on every transport." }, "existing_routes": { "type": "array" }, "freeze": { "type": "array", "items": { "type": "string", "maxLength": 128 } }, "jobs": { "type": "array", "maxItems": 10000, "items": { "type": "object", "properties": { "alternatives": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array" }, "time_window": { "type": [ "array", "null" ] } } }, "maxItems": 10, "description": "Up to 10 other places the job may be served at instead of its `location`, each `{id?, location, time_window?}`; exactly one place is served. The stop reports `served_at` (`location` or `alternative`) and, at an alternative, `alternative_index` (0-based), `alternative_id` and the `location` served. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There one place is chosen before the solve: the nearest to the vehicles' starts whose time window a vehicle can meet." }, "amount": { "type": [ "array", "null" ] }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The job's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array", "description": "Required when jobs is present." }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "release_at": { "description": "When the job's goods are ready at the depot (ISO-8601 with an offset, or epoch seconds): the trip carrying the job is loaded no earlier. Unassigned reason `release_time`. Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the job only goes to a vehicle whose time window starts at or after its release." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "setup_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": [ "array", "null" ] }, "time_windows": { "type": [ "array", "null" ] } } } }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ] } } }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "shipments": { "type": "array", "maxItems": 5000, "items": { "type": "object", "properties": { "delivery": { "type": "array", "description": "Required when shipments is present." }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The shipment's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "The longest the shipment may be on board, from its pickup to its delivery, in seconds; unassigned reason `max_ride_time`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "pickup": { "type": "array", "description": "Required when shipments is present." } } } }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "breaks": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "duration_seconds": [], "places": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "location": { "type": "array" } } }, "maxItems": 10, "description": "Up to 10 places `{location}` the break must be taken at, a detour the engine plans; the break stop carries the `location` it was taken at. `sroute2t` 1.0.21 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "skip_policy": { "type": [ "string", "null" ], "enum": [ "if_no_intersection", "if_route_ends_before_window_end" ], "description": "When the break may be left out: `if_no_intersection` (the route does not overlap its window) or `if_route_ends_before_window_end` (the route ends before the window closes). The route reports `skipped_breaks` as 0-based break indexes, and break stops carry `break_index`. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is solved again without the breaks the first plan does not need, and kept only when it leaves no more work unassigned." }, "windows": [] } }, "maxItems": 10 }, "capacity": { "type": [ "array", "null" ] }, "end": { "type": [ "array", "null" ] }, "ev_range_meters": { "type": [ "integer", "null" ], "minimum": 1, "description": "An electric vehicle's range on a full charge, in metres. The vehicle starts full and never charges on the way, so its route covers at most the range less `ev_reserve_meters`; unassigned reason `range` on sroute2t and sroute3. On `sroute` and `sroute2` it is the vehicle's maximum distance (its own `max_distance_meters` when shorter), which is exact for a distance range; `sroute2t` and `sroute3` plan it natively." }, "ev_reserve_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The part of `ev_range_meters` kept in reserve, in metres. Ignored without `ev_range_meters`." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "latest_departure_at": { "description": "The latest time the vehicle may leave its start (ISO-8601 with an offset, or epoch seconds); unassigned reason `latest_departure`. Cannot be combined with `shifts`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0 }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0 }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "return_to_start": { "type": [ "boolean", "null" ] }, "shifts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "end": { "type": [ "array", "null" ] }, "from": [], "start": { "type": [ "array", "null" ] }, "to": [] } }, "maxItems": 6, "description": "Working periods of the vehicle, each `{from, to, start?, end?}` (times as ISO-8601 with an offset or epoch seconds, not overlapping; locations `{lat, lng}`), at most 6. Planned as one engine vehicle per shift with the shift as its time window, a full capacity and the shift's own start and end when given; a break goes to the first shift its window fits in. Answered as one route per vehicle with `shift_end` / `shift_start` stops (`shift_index`) between shifts. Every engine; routing.optimize only." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "start": { "type": [ "array", "null" ] }, "time_window": { "type": [ "array", "null" ] } } } } }, "additionalProperties": false, "required": [ "existing_routes", "vehicles" ] }, "example": { "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ], "time_window": [ "2026-11-02T08:00:00-05:00", "2026-11-02T17:00:00-05:00" ] }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ] } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": [ 2 ] }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": [ 3 ], "time_windows": [ [ "2026-11-02T09:00:00-05:00", "2026-11-02T12:00:00-05:00" ] ] }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 240, "amount": [ 1 ] } ], "existing_routes": [ { "vehicle_id": "van-1", "stops": [ { "id": "order-1001" }, { "id": "order-1002" } ] }, { "vehicle_id": "van-2", "stops": [ { "id": "order-1003" } ] } ] } } } } } }, "/v1/routing/what-if": { "post": { "operationId": "routingWhatif", "tags": [ "routing" ], "summary": "Compare alternative plans", "description": "Scores several alternative plans against one another without committing to any of them. Always synchronous, as it is used interactively.\n\nScore several alternative plans side by side without committing to any.", "x-superroute-capability": "routing.whatif", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/routing.whatif", "responses": { "200": { "description": "Several alternative plans for the same problem, each scored, none applied. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "routing.whatif" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": "string", "description": "Identifies the plan in this answer." }, "strategy": { "type": "string", "description": "The strategy that produced it, `min_change` (closest to `existing_routes`), `rebalance` or `sla_protect`." }, "routes": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "The caller's vehicle id." }, "stops": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "start", "job", "pickup", "delivery", "break", "end" ], "description": "What happens at this stop. `start` and `end` are the vehicle's own endpoints; `pickup` and `delivery` are the two legs of a shipment." }, "id": { "type": "string", "description": "The caller's id of the job or shipment served here. Absent on start, end and break." }, "shipment_leg": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Which leg of the shipment `id` names. Present on shipment stops only." }, "arrival": { "type": [ "string", "null" ], "description": "When the vehicle arrives, ISO 8601 with offset. Null when the engine reported no time." }, "arrival_epoch": { "type": [ "integer", "null" ], "description": "`arrival` as Unix seconds." }, "arrival_offset_seconds": { "type": [ "integer", "null" ], "description": "Seconds from the route's start to this stop. Present instead of `arrival` and `arrival_epoch` only when nothing in the request carried a time: no vehicle `time_window` and no job time window." }, "distance_meters": { "type": [ "integer", "null" ], "description": "Distance driven from the route start to this stop, cumulative." }, "duration_seconds": { "type": [ "integer", "null" ], "description": "Driving time from the route start to this stop, cumulative." }, "leg_distance_meters": { "type": "integer", "description": "Distance of the hop into this stop from the previous one." }, "leg_duration_seconds": { "type": "integer", "description": "Driving time of the hop into this stop from the previous one." }, "load": { "type": "array", "items": { "type": "number" }, "description": "What the vehicle carries when it leaves this stop, one figure per capacity dimension, in the order of `meta.capacity_dimensions`." } }, "required": [ "type" ] }, "description": "The stops in driving order, start and end included." }, "stop_count": { "type": "integer", "description": "Number of entries in `stops`." }, "task_count": { "type": "integer", "description": "Jobs and shipment legs served on this route (start, end and breaks not counted)." }, "distance_meters": { "type": "integer", "description": "Total distance driven." }, "duration_seconds": { "type": "integer", "description": "Total driving time. Service and waiting are reported separately." }, "service_seconds": { "type": "integer", "description": "Total service time at the stops." }, "waiting_seconds": { "type": "integer", "description": "Total time spent waiting for time windows to open." }, "geometry": { "type": [ "string", "null" ], "description": "Encoded polyline (precision 5) of the whole route. Null unless `options.geometry` was true." } }, "required": [ "vehicle_id", "stops" ] }, "description": "One route per vehicle that received work. A vehicle left idle does not appear." }, "unassigned": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The caller's id of the job or shipment that no vehicle took." }, "shipment_leg": { "type": [ "string", "null" ], "enum": [ "pickup", "delivery", null ], "description": "For a shipment, which leg was left over." }, "reason": { "type": "string", "description": "Why it was left over, as reported by the engine; `unspecified` when the engine gave no reason." } } }, "description": "Work no vehicle could take. Empty when everything was placed." }, "summary": { "type": "object", "properties": { "routes": { "type": "integer", "description": "Routes in the plan (vehicles with work)." }, "assigned": { "type": "integer", "description": "Tasks placed on a route." }, "unassigned": { "type": "integer", "description": "Tasks left in `unassigned`." }, "distance_meters": { "type": "integer", "description": "Sum of every route's distance." }, "duration_seconds": { "type": "integer", "description": "Sum of every route's driving time." } } } } }, "description": "One entry per alternative." } } }, "meta": { "type": "object", "description": "Facts about the solve.", "properties": { "engine": { "type": "string", "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ], "description": "The engine that answered." }, "engine_version": { "type": "string", "description": "That engine's version." }, "solve_id": { "type": "string", "description": "The engine's id for this solve. Quote it with `request_id` when asking support about a plan." }, "capacity_dimensions": { "type": "array", "items": { "type": "string" }, "description": "The names of the capacity dimensions, in the order `load` reports them. A list capacity is named by position (`\"0\"`, `\"1\"`, ...)." }, "balance": { "type": "object", "description": "Present only when `constraints.balance` was `tolerance`, `zone`, `hours` or `zone_hours`; see the routing.optimize reference for its fields.", "properties": [] }, "rule_notices": { "type": "array", "items": { "type": "object", "properties": [] }, "description": "Present only when a routing rule was approximated or adjusted; each entry is also a RULE_APPROXIMATED or RULE_ADJUSTED warning." }, "mode": { "type": "string", "enum": [ "sync", "async" ], "description": "Present on a queued answer." } }, "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "routing.whatif", "billing": { "unit": "call", "quantity": 1, "counted": true, "breakdown": { "nodes": 5, "jobs": 3, "shipments": 0, "shipment_nodes": 0, "vehicles": 2, "vehicle_nodes": 2 } }, "data": { "plans": [ { "plan_id": "min_change", "strategy": "min_change", "routes": [ { "vehicle_id": "van-1", "stops": [ { "type": "start", "arrival": "2026-11-02T08:00:00-05:00", "arrival_epoch": 1793624400, "distance_meters": 0, "duration_seconds": 0, "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T08:08:01-05:00", "arrival_epoch": 1793624881, "distance_meters": 3635, "duration_seconds": 481, "leg_distance_meters": 3635, "leg_duration_seconds": 481, "id": "order-1003", "load": [ 2 ] }, { "type": "job", "arrival": "2026-11-02T08:18:34-05:00", "arrival_epoch": 1793625514, "distance_meters": 6563, "duration_seconds": 874, "leg_distance_meters": 2928, "leg_duration_seconds": 393, "id": "order-1001", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T08:27:15-05:00", "arrival_epoch": 1793626035, "distance_meters": 8356, "duration_seconds": 1095, "leg_distance_meters": 1793, "leg_duration_seconds": 221, "load": [ 0 ] } ], "stop_count": 4, "task_count": 2, "distance_meters": 8356, "duration_seconds": 1095, "service_seconds": 540, "waiting_seconds": 0, "geometry": null }, { "vehicle_id": "van-2", "stops": [ { "type": "start", "arrival": "2026-11-02T08:56:13-05:00", "arrival_epoch": 1793627773, "distance_meters": 0, "duration_seconds": 0, "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T09:00:00-05:00", "arrival_epoch": 1793628000, "distance_meters": 1610, "duration_seconds": 227, "leg_distance_meters": 1610, "leg_duration_seconds": 227, "id": "order-1002", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 3077, "duration_seconds": 424, "leg_distance_meters": 1467, "leg_duration_seconds": 197, "load": [ 0 ] } ], "stop_count": 3, "task_count": 1, "distance_meters": 3077, "duration_seconds": 424, "service_seconds": 300, "waiting_seconds": 0, "geometry": null } ], "unassigned": [], "summary": { "routes": 2, "assigned": 3, "unassigned": 0, "distance_meters": 11433, "duration_seconds": 1519 } }, { "plan_id": "rebalance", "strategy": "rebalance", "routes": [ { "vehicle_id": "van-2", "stops": [ { "type": "start", "arrival": "2026-11-02T08:31:07-05:00", "arrival_epoch": 1793626267, "distance_meters": 0, "duration_seconds": 0, "load": [ 6 ] }, { "type": "job", "arrival": "2026-11-02T08:35:11-05:00", "arrival_epoch": 1793626511, "distance_meters": 1839, "duration_seconds": 244, "leg_distance_meters": 1839, "leg_duration_seconds": 244, "id": "order-1001", "load": [ 4 ] }, { "type": "job", "arrival": "2026-11-02T08:47:56-05:00", "arrival_epoch": 1793627276, "distance_meters": 5338, "duration_seconds": 709, "leg_distance_meters": 3499, "leg_duration_seconds": 465, "id": "order-1003", "load": [ 3 ] }, { "type": "job", "arrival": "2026-11-02T09:00:00-05:00", "arrival_epoch": 1793628000, "distance_meters": 9220, "duration_seconds": 1193, "leg_distance_meters": 3882, "leg_duration_seconds": 484, "id": "order-1002", "load": [ 0 ] }, { "type": "end", "arrival": "2026-11-02T09:08:17-05:00", "arrival_epoch": 1793628497, "distance_meters": 10687, "duration_seconds": 1390, "leg_distance_meters": 1467, "leg_duration_seconds": 197, "load": [ 0 ] } ], "stop_count": 5, "task_count": 3, "distance_meters": 10687, "duration_seconds": 1390, "service_seconds": 840, "waiting_seconds": 0, "geometry": null } ], "unassigned": [ { "id": "order-1004", "reason": "unspecified" } ], "summary": { "routes": 1, "assigned": 3, "unassigned": 1, "distance_meters": 10687, "duration_seconds": 1390 } } ] }, "meta": { "engine": "sroute2", "engine_version": "1.6.1", "capacity_dimensions": [ "0" ] } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "424": { "description": "The routing engine refused this problem. Its reason is included where available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_REJECTED", "message": "The routing engine refused this problem. Its reason is included where available.", "status": 424, "doc_url": "/developer/errors/ENGINE_REJECTED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } }, "504": { "description": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "SOLVE_TIMEOUT", "message": "The solve exceeded the synchronous budget. Send the same request with \"mode\":\"async\" and collect the result from the job.", "status": 504, "doc_url": "/developer/errors/SOLVE_TIMEOUT" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback": { "type": [ "object", "null" ], "properties": { "events": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "format": { "type": [ "string", "null" ], "enum": [ "native", "ce_binary", "ce_structured" ] }, "secret": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 255, "description": "Required when callback.signature is standard_webhooks." }, "signature": { "type": [ "string", "null" ], "enum": [ "native", "standard_webhooks" ] }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Required when callback is present." } } }, "constraints": { "type": [ "object", "null" ], "properties": { "balance": { "type": [ "string", "null" ], "enum": [ "none", "balanced", "min_change", "sla_protect", "tolerance", "zone", "hours", "zone_hours" ], "description": "How the work is spread across vehicles. `balanced`, `min_change` and `sla_protect` are engine presets (sroute2, sroute2t or sroute3 only). `tolerance`, `zone`, `hours` and `zone_hours` are enforced by the platform on either engine, on routing.optimize only, and reported in `meta.balance`: `tolerance` holds every vehicle's task count within `balance_tolerance` percent of the balanced share (the twin of the Superroute route builder's mode 4); `zone` first cuts the tasks into one compact, non-overlapping zone per vehicle so routes never cross (mode 5); `hours` evens out working time — driving including the leg back to an end point, setup, service and waiting — by solving from an equal split, then, while a vehicle sits outside the band, closing every vehicle's working day (its `time_window`) at the band's top and a step tighter, handing the tasks the busiest give up to the lightest by their measured time per task, and re-solving, at most twice (mode 6); `zone_hours` cuts the zones of `zone` on time instead of task counts — a slow area gets a smaller zone — and, once the routes are timed, re-cuts them from each vehicle's measured working day and re-solves, at most twice, so routes never cross and the days come out even (mode 7). `none` or omitted: no balancing. On this operation only the engine presets apply; `tolerance`, `zone`, `hours` and `zone_hours` are refused with VALIDATION_FAILED." }, "balance_tolerance": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100, "description": "The band, in percent of the balanced share, for `tolerance`, `zone`, `hours` and `zone_hours`. 1-100; defaults to 15 when omitted. Ignored for the engine presets." }, "deliveries_before_pickups": { "type": [ "boolean", "null" ], "description": "Every delivery of a route before its first pickup (backhaul); unassigned reason `deliveries_first`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "incompatible_goods_classes": { "type": [ "array", "null" ], "items": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "maxItems": 500, "description": "Pairs of goods classes that may not ride in one vehicle, e.g. `[[\"food\", \"chemicals\"]]`; unassigned reason `incompatible_goods`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the vehicles are shared out between the classes of each pair before the solve, so a vehicle carries one of them." }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 86400, "description": "The ride time limit of every shipment without its own `max_ride_seconds`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "merge_stops": { "type": [ "object", "null" ], "properties": { "max_stops": { "type": [ "integer", "null" ], "minimum": 2, "maximum": 50 }, "radius_meters": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Required when constraints.merge_stops is present." }, "same_window_only": { "type": [ "boolean", "null" ] } }, "description": "Nearby jobs sent as one stop: jobs within `radius_meters` (1-1000) of one another that share skills, priority, group, goods class and amount dimensions and have at most one time window go as one stop of at most `max_stops` (2-50, default 10) jobs; the windows are intersected, or with `same_window_only` must be equal. Answered one stop per job. Jobs with alternatives are never merged. Every engine; routing.optimize only." }, "region_filter": { "type": [ "boolean", "null" ] }, "reload": { "type": [ "object", "null" ], "properties": { "depots": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Required when constraints.reload is present.", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "loading_bays": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many vehicles may load at the depot in one slot of `slot_seconds` (default 1800); unassigned reason `loading_bay`. `sroute2t` 1.0.20 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "location": { "type": "array" } } } }, "loading_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 14400 }, "max_reloads": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "slot_seconds": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 14400 } }, "description": "Vehicles may return to a depot to load again: `depots` (1-10, each `{id?, location, loading_bays?}`), `loading_seconds` (default 900), `max_reloads` (1-5, default 1). Routes carry `reload` stops with `depot_index`, `depot_id`, `location` and `service_seconds` (and `trip` when approximated). Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is built as sequential trips: the work a trip leaves out is planned on a further trip from the nearest depot." }, "use_all_vehicles": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How strongly to put every vehicle to work: `off` (default), `low`, `normal` or `high`. Native on `sroute2t` 1.0.19 or later and on `sroute3`, and on `sroute2` as its `orders` balance (which no other balance preset may accompany). Approximated on `sroute`, on routing.optimize only, by capping every vehicle's task count." }, "waiting_cost": { "type": [ "string", "null" ], "enum": [ "off", "low", "normal", "high" ], "description": "How much time spent waiting for a window costs: `off` (default), `low`, `normal` or `high`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." } } }, "engine": { "type": [ "string", "null" ], "enum": [ "sroute", "sroute2", "sroute2t", "sroute3" ], "description": "Which solver serves the request. `sroute2` (default when omitted) and `sroute`, the direct solver, are available to every account; `sroute2t` is an engine of its own that speaks the same router API as sroute2 and is available only to accounts it has been enabled for — otherwise the request is refused with ENGINE_NOT_ENABLED (403). `sroute3` is another engine of its own, offered alongside sroute2t on the same terms: it answers the same router API and plans every routing rule sroute2t plans natively, each from the sroute3 version named in `routing_rules`. Refine, what-if and the engine balance presets run on sroute2, sroute2t or sroute3 only. Any other value is refused with VALIDATION_FAILED (422), detail code INVALID on `engine`, on every transport." }, "existing_routes": { "type": "array" }, "freeze": { "type": "array", "items": { "type": "string", "maxLength": 128 } }, "jobs": { "type": "array", "maxItems": 10000, "items": { "type": "object", "properties": { "alternatives": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array" }, "time_window": { "type": [ "array", "null" ] } } }, "maxItems": 10, "description": "Up to 10 other places the job may be served at instead of its `location`, each `{id?, location, time_window?}`; exactly one place is served. The stop reports `served_at` (`location` or `alternative`) and, at an alternative, `alternative_index` (0-based), `alternative_id` and the `location` served. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There one place is chosen before the solve: the nearest to the vehicles' starts whose time window a vehicle can meet." }, "amount": { "type": [ "array", "null" ] }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The job's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "location": { "type": "array", "description": "Required when jobs is present." }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "release_at": { "description": "When the job's goods are ready at the depot (ISO-8601 with an offset, or epoch seconds): the trip carrying the job is loaded no earlier. Unassigned reason `release_time`. Native on `sroute2t` 1.0.20 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the job only goes to a vehicle whose time window starts at or after its release." }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "setup_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": [ "array", "null" ] }, "time_windows": { "type": [ "array", "null" ] } } } }, "mode": { "type": [ "string", "null" ], "enum": [ "auto", "sync", "async" ] }, "options": { "type": [ "object", "null" ], "properties": { "geometry": { "type": [ "boolean", "null" ] } } }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "shipments": { "type": "array", "maxItems": 5000, "items": { "type": "object", "properties": { "delivery": { "type": "array", "description": "Required when shipments is present." }, "goods_class": { "type": [ "string", "null" ], "maxLength": 64, "description": "The shipment's goods class, matched against `constraints.incompatible_goods_classes`." }, "group": { "type": [ "string", "null" ], "maxLength": 128, "description": "Jobs and shipments with the same group are served by one vehicle; unassigned reason `group`. Native on `sroute2t` 1.0.19 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "max_ride_seconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "The longest the shipment may be on board, from its pickup to its delivery, in seconds; unassigned reason `max_ride_time`. `sroute2t` 1.0.19 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "pickup": { "type": "array", "description": "Required when shipments is present." } } } }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "properties": { "breaks": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "duration_seconds": [], "places": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "location": { "type": "array" } } }, "maxItems": 10, "description": "Up to 10 places `{location}` the break must be taken at, a detour the engine plans; the break stop carries the `location` it was taken at. `sroute2t` 1.0.21 or later, or `sroute3`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "skip_policy": { "type": [ "string", "null" ], "enum": [ "if_no_intersection", "if_route_ends_before_window_end" ], "description": "When the break may be left out: `if_no_intersection` (the route does not overlap its window) or `if_route_ends_before_window_end` (the route ends before the window closes). The route reports `skipped_breaks` as 0-based break indexes, and break stops carry `break_index`. Native on `sroute2t` 1.0.21 or later and on `sroute3`. Approximated on `sroute` and `sroute2`, on routing.optimize only, with a RULE_APPROXIMATED warning and a `meta.rule_notices` entry. There the plan is solved again without the breaks the first plan does not need, and kept only when it leaves no more work unassigned." }, "windows": [] } }, "maxItems": 10 }, "capacity": { "type": [ "array", "null" ] }, "end": { "type": [ "array", "null" ] }, "ev_range_meters": { "type": [ "integer", "null" ], "minimum": 1, "description": "An electric vehicle's range on a full charge, in metres. The vehicle starts full and never charges on the way, so its route covers at most the range less `ev_reserve_meters`; unassigned reason `range` on sroute2t and sroute3. On `sroute` and `sroute2` it is the vehicle's maximum distance (its own `max_distance_meters` when shorter), which is exact for a distance range; `sroute2t` and `sroute3` plan it natively." }, "ev_reserve_meters": { "type": [ "integer", "null" ], "minimum": 0, "description": "The part of `ev_range_meters` kept in reserve, in metres. Ignored without `ev_range_meters`." }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "latest_departure_at": { "description": "The latest time the vehicle may leave its start (ISO-8601 with an offset, or epoch seconds); unassigned reason `latest_departure`. Cannot be combined with `shifts`. Engines `sroute2t` and `sroute3` only; refused with VALIDATION_FAILED (detail code UNSUPPORTED, or UNSUPPORTED_ENGINE_VERSION on an older engine) elsewhere." }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0 }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0 }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "return_to_start": { "type": [ "boolean", "null" ] }, "shifts": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "end": { "type": [ "array", "null" ] }, "from": [], "start": { "type": [ "array", "null" ] }, "to": [] } }, "maxItems": 6, "description": "Working periods of the vehicle, each `{from, to, start?, end?}` (times as ISO-8601 with an offset or epoch seconds, not overlapping; locations `{lat, lng}`), at most 6. Planned as one engine vehicle per shift with the shift as its time window, a full capacity and the shift's own start and end when given; a break goes to the first shift its window fits in. Answered as one route per vehicle with `shift_end` / `shift_start` stops (`shift_index`) between shifts. Every engine; routing.optimize only." }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "start": { "type": [ "array", "null" ] }, "time_window": { "type": [ "array", "null" ] } } } } }, "additionalProperties": false, "required": [ "existing_routes", "vehicles" ] }, "example": { "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ], "time_window": [ "2026-11-02T08:00:00-05:00", "2026-11-02T17:00:00-05:00" ] }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": [ 10 ] } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": [ 2 ] }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": [ 3 ], "time_windows": [ [ "2026-11-02T09:00:00-05:00", "2026-11-02T12:00:00-05:00" ] ] }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 240, "amount": [ 1 ] } ], "existing_routes": [ { "vehicle_id": "van-1", "stops": [ { "id": "order-1001" }, { "id": "order-1002" } ] }, { "vehicle_id": "van-2", "stops": [ { "id": "order-1003" } ] } ] } } } } } }, "/v1/slots/quote": { "post": { "operationId": "slotsQuote", "tags": [ "slots" ], "summary": "Quote delivery slots", "description": "Prices the new `job` once for every slot in `slots` (each with `from` and `to`, ISO 8601 with an offset): the job takes the slot as its time window and is placed in the plan as stop insertion places it, at the position that adds the least driver time without breaking any rule the plan keeps. Each slot comes back `feasible` or not, with the best vehicle and position, the added distance, duration and waiting, arrival and service start, and a `rank` among the feasible slots, cheapest first. The plan is given as for stop insertion. Nothing is stored. Billed per node: the plan's stops plus one, however many slots are asked.\n\nFor one new job, find which delivery slots a plan you hold can take and what each costs.", "x-superroute-capability": "slots.quote", "x-superroute-billing-unit": "node", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/slots.quote", "responses": { "200": { "description": "Every slot with whether it can take the job, its best position and its rank. Billed per node.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "slots.quote" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "node" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "job": { "type": "string", "description": "The job id." }, "slots": { "type": "array", "description": "Every slot, in the order given.", "items": { "type": "object", "properties": { "slot": { "type": "string", "description": "The slot id, or its number from 1." }, "from": { "type": "string", "description": "Slot start, ISO 8601." }, "to": { "type": "string", "description": "Slot end, ISO 8601." }, "feasible": { "type": "boolean", "description": "Whether the plan can take the job in this slot without breaking a rule." }, "best": { "type": [ "object", "null" ], "description": "The cheapest acceptable position in this slot; null when none.", "properties": { "vehicle_id": { "type": "string", "description": "The vehicle whose route takes the job." }, "position": { "type": "integer", "description": "The job's place in that route's stops, from 1." }, "after": { "type": [ "string", "null" ], "description": "The stop the job follows; null when it comes first." }, "added_distance_meters": { "type": "integer", "description": "Distance the route gains." }, "added_duration_seconds": { "type": "integer", "description": "Driving time the route gains." }, "added_waiting_seconds": { "type": "integer", "description": "Waiting the route gains (negative when the job fills time spent waiting)." }, "arrival": { "type": [ "string", "null" ], "description": "Arrival at the job, ISO 8601." }, "waiting_seconds": { "type": "integer", "description": "Waiting at the job before its window opens." }, "service_start": { "type": [ "string", "null" ], "description": "When work at the job begins: arrival plus waiting." }, "violations": { "type": "array", "description": "What this position breaks. Present only on a position that is not acceptable (`closest`)." } } }, "rank": { "type": [ "integer", "null" ], "description": "1 for the cheapest feasible slot (least added driver time, or distance); null when not feasible." } } } }, "summary": { "type": "object", "properties": { "slots": { "type": "integer", "description": "Slots asked about." }, "feasible": { "type": "integer", "description": "Slots that can take the job." }, "cheapest": { "type": [ "string", "null" ], "description": "The id of the slot ranked 1." } } } }, "required": [ "job", "slots", "summary" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "slots.quote", "billing": { "unit": "node", "quantity": 4, "counted": true, "breakdown": { "planned_stops": 3, "new_jobs": 1 } }, "data": { "job": "order-2001", "slots": [ { "slot": "08-10", "from": "2026-11-02T08:00:00-05:00", "to": "2026-11-02T10:00:00-05:00", "feasible": true, "best": { "vehicle_id": "van-1", "position": 2, "after": "order-1001", "added_distance_meters": 1505, "added_duration_seconds": 213, "added_waiting_seconds": -513, "arrival": "2026-11-02T08:11:57-05:00", "waiting_seconds": 0, "service_start": "2026-11-02T08:11:57-05:00" }, "rank": 1 }, { "slot": "10-12", "from": "2026-11-02T10:00:00-05:00", "to": "2026-11-02T12:00:00-05:00", "feasible": true, "best": { "vehicle_id": "van-1", "position": 3, "after": "order-1002", "added_distance_meters": 4526, "added_duration_seconds": 544, "added_waiting_seconds": 2879, "arrival": "2026-11-02T09:12:01-05:00", "waiting_seconds": 2879, "service_start": "2026-11-02T10:00:00-05:00" }, "rank": 2 }, { "slot": "12-14", "from": "2026-11-02T12:00:00-05:00", "to": "2026-11-02T14:00:00-05:00", "feasible": true, "best": { "vehicle_id": "van-1", "position": 3, "after": "order-1002", "added_distance_meters": 4526, "added_duration_seconds": 544, "added_waiting_seconds": 10079, "arrival": "2026-11-02T09:12:01-05:00", "waiting_seconds": 10079, "service_start": "2026-11-02T12:00:00-05:00" }, "rank": 3 }, { "slot": "17-19", "from": "2026-11-02T17:00:00-05:00", "to": "2026-11-02T19:00:00-05:00", "feasible": true, "best": { "vehicle_id": "van-2", "position": 2, "after": "order-1003", "added_distance_meters": 1402, "added_duration_seconds": 211, "added_waiting_seconds": 31353, "arrival": "2026-11-02T08:17:27-05:00", "waiting_seconds": 31353, "service_start": "2026-11-02T17:00:00-05:00" }, "rank": 4 } ], "summary": { "slots": 4, "feasible": 4, "cheapest": "08-10" } }, "meta": { "region": "NA", "profile": "car", "objective": "duration", "nearest": 25, "legs_measured": 13 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "departed_at": [], "job": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "location": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "lat", "lng" ] }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "location" ], "description": "The job to quote, like a job of `jobs` without time windows: each slot is its time window in turn." }, "jobs": { "type": "array", "maxItems": 2000, "items": { "type": "object", "properties": { "amount": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "location": { "type": "array" }, "service_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "time_windows": { "type": [ "array", "null" ] } }, "required": [ "id", "location" ] } }, "nearest": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "description": "How many of the plan's stops nearest to the new job (straight line) to try positions next to, 1-200, default 25. Every empty route is tried as well." }, "objective": { "type": [ "string", "null" ], "enum": [ "duration", "distance" ], "description": "`duration` (default): the position adding the least driver time, driving plus waiting. `distance`: the position adding the least distance." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for. `car` (default when omitted) and `van` use the road network's car costing. `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle, applied to every vehicle on every engine. `motorcycle` avoids roads a motorcycle may not use, and toll and highway avoidance applies where the road data carries those options. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "region": { "type": [ "string", "null" ], "enum": [ "NA", "EU", "AU", "ASIA", "na", "eu", "au", "asia" ] }, "routes": { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "reverse": { "type": [ "boolean", "null" ] }, "stops": { "type": "array", "maxItems": 2000, "items": { "type": "string", "maxLength": 128 } }, "vehicle_id": { "type": "string", "maxLength": 128 } }, "required": [ "vehicle_id" ] } }, "slots": { "type": "array", "minItems": 1, "maxItems": 96, "items": { "type": "object", "properties": { "from": [], "id": { "type": [ "string", "null" ], "maxLength": 64 }, "to": [] }, "required": [ "from", "to" ] }, "description": "The slots to quote, 1-96, each `{id?, from, to}` in ISO 8601 with an offset." }, "vehicles": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "capacity": { "type": [ "array", "null" ] }, "end": { "type": [ "array", "null" ] }, "id": { "type": "string", "maxLength": 128 }, "max_distance_meters": { "type": [ "integer", "null" ], "minimum": 0 }, "max_tasks": { "type": [ "integer", "null" ], "minimum": 0 }, "max_travel_time_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "return_to_start": { "type": [ "boolean", "null" ] }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 } }, "start": { "type": [ "array", "null" ] }, "time_window": { "type": [ "array", "null" ] } }, "required": [ "id" ] } } }, "additionalProperties": false, "required": [ "job", "jobs", "routes", "slots", "vehicles" ] }, "example": { "departed_at": "2026-11-02T08:00:00-05:00", "vehicles": [ { "id": "van-1", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 }, "time_window": [ "2026-11-02T08:00:00-05:00", "2026-11-02T17:00:00-05:00" ] }, { "id": "van-2", "start": { "lat": 45.5017, "lng": -73.5673 }, "return_to_start": true, "capacity": { "parcels": 10 } } ], "jobs": [ { "id": "order-1001", "location": { "lat": 45.5088, "lng": -73.554 }, "service_seconds": 300, "amount": { "parcels": 2 } }, { "id": "order-1002", "location": { "lat": 45.4972, "lng": -73.5786 }, "service_seconds": 300, "amount": { "parcels": 3 }, "time_windows": [ [ "2026-11-02T09:00:00-05:00", "2026-11-02T12:00:00-05:00" ] ] }, { "id": "order-1003", "location": { "lat": 45.5231, "lng": -73.5817 }, "service_seconds": 240, "amount": { "parcels": 1 } } ], "routes": [ { "vehicle_id": "van-1", "stops": [ "order-1001", "order-1002" ] }, { "vehicle_id": "van-2", "stops": [ "order-1003" ] } ], "job": { "id": "order-2001", "location": { "lat": 45.5155, "lng": -73.5605 }, "service_seconds": 300, "amount": { "parcels": 1 } }, "slots": [ { "id": "08-10", "from": "2026-11-02T08:00:00-05:00", "to": "2026-11-02T10:00:00-05:00" }, { "id": "10-12", "from": "2026-11-02T10:00:00-05:00", "to": "2026-11-02T12:00:00-05:00" }, { "id": "12-14", "from": "2026-11-02T12:00:00-05:00", "to": "2026-11-02T14:00:00-05:00" }, { "id": "17-19", "from": "2026-11-02T17:00:00-05:00", "to": "2026-11-02T19:00:00-05:00" } ] } } } } } }, "/v1/territory/design": { "post": { "operationId": "territoryDesign", "tags": [ "territory" ], "summary": "Design territories", "description": "Assigns every submitted point to one of the territories so that each territory is compact, territories never overlap, and each carries its share of the total `weight` within `tolerance_percent` (default 10). Ask for `count` territories, or name them in `zones` with an optional `anchor` (a depot the territory grows around) and a `share` (relative size, default 1). A point may be fixed to a territory with `zone` or limited to some with `allowed_zones`. Returns each territory's centre, point count, weight and target, its convex `outline` as a GeoJSON polygon (set `outline` to false to leave it out), the territory of every point, and the points that fit none. Distances are straight-line: road travel is not considered. Points times territories may be at most 500 000; above 50 000 the request is run as a job unless `mode` is `sync`. Nothing is stored. Billed per point, invoiced per thousand.\n\nCut weighted points into compact, non-overlapping territories that each carry a balanced share of the work.", "x-superroute-capability": "territory.design", "x-superroute-billing-unit": "point_1k", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/territory.design", "responses": { "200": { "description": "The territories with their centres, weights and outlines, and the territory of every point. Billed per point.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "territory.design" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "zones": { "type": "array", "description": "The territories, in the order asked for.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The territory id: as given in `zones`, or 1..count." }, "center": { "type": [ "object", "null" ], "description": "The territory's centre, `{lat, lng}`. Null for a territory that received no point." }, "anchored": { "type": "boolean", "description": "Whether the territory grew around its `anchor`." }, "points": { "type": "integer", "description": "Points in the territory." }, "weight": { "type": "integer", "description": "The weight of its points." }, "target": { "type": "integer", "description": "The weight it should carry: its share of the total." }, "outline": { "type": [ "object", "null" ], "description": "The convex outline of its points as a GeoJSON Polygon ([lng, lat]). Null below three distinct points; absent when `outline` is false." } } } }, "assignment": { "type": "array", "description": "Every point with its territory, in the order of `points`.", "items": { "type": "object", "properties": { "point": { "type": "string", "description": "The point id." }, "zone": { "type": [ "string", "null" ], "description": "The territory id; null when the point fits none." } } } }, "unplaced": { "type": "array", "items": { "type": "string" }, "description": "Points that fit no territory (their `allowed_zones` are full)." }, "summary": { "type": "object", "properties": { "zones": { "type": "integer", "description": "Territories." }, "points": { "type": "integer", "description": "Points submitted." }, "weight": { "type": "integer", "description": "Total weight." }, "largest_deviation_percent": { "type": "number", "description": "The largest difference between a territory's weight and its target, as a percentage of the target." } } } }, "required": [ "zones", "assignment", "unplaced", "summary" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "territory.design", "billing": { "unit": "point_1k", "quantity": 12, "counted": true }, "data": { "zones": [ { "id": "east", "center": { "lat": 45.520306, "lng": -73.5314 }, "anchored": true, "points": 4, "weight": 7, "target": 9, "outline": { "type": "Polygon", "coordinates": [ [ [ -73.55506, 45.52568 ], [ -73.545, 45.51979 ], [ -73.53724, 45.51723 ], [ -73.49625, 45.51993 ], [ -73.55506, 45.52568 ] ] ] } }, { "id": "west", "center": { "lat": 45.506008, "lng": -73.591628 }, "anchored": true, "points": 6, "weight": 10, "target": 9, "outline": { "type": "Polygon", "coordinates": [ [ [ -73.63772, 45.54922 ], [ -73.63285, 45.48886 ], [ -73.58194, 45.4545 ], [ -73.56081, 45.47888 ], [ -73.56268, 45.5003 ], [ -73.5886, 45.51925 ], [ -73.63772, 45.54922 ] ] ] } }, { "id": "north", "center": { "lat": 45.45714, "lng": -73.53451 }, "anchored": false, "points": 2, "weight": 6, "target": 5, "outline": null } ], "assignment": [ { "point": "stop-1", "zone": "west" }, { "point": "stop-2", "zone": "north" }, { "point": "stop-3", "zone": "east" }, { "point": "stop-4", "zone": "west" }, { "point": "stop-5", "zone": "west" }, { "point": "stop-6", "zone": "west" }, { "point": "stop-7", "zone": "east" }, { "point": "stop-8", "zone": "west" }, { "point": "stop-9", "zone": "north" }, { "point": "stop-10", "zone": "west" }, { "point": "stop-11", "zone": "east" }, { "point": "stop-12", "zone": "east" } ], "unplaced": [], "summary": { "zones": 3, "points": 12, "weight": 23, "largest_deviation_percent": 22.2 } }, "meta": { "distance": "straight_line", "rounds": 3, "mode": "sync" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "413": { "description": "The request body is too large. Upload large payloads as a reusable resource instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body is too large. Upload large payloads as a reusable resource instead.", "status": 413, "doc_url": "/developer/errors/REQUEST_TOO_LARGE" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 200, "description": "How many territories, named 1..count. Give this or `zones`." }, "outline": { "type": [ "boolean", "null" ] }, "points": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "object", "properties": { "allowed_zones": { "type": "array", "maxItems": 200, "items": { "type": "string", "maxLength": 128 } }, "id": { "type": "string", "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "weight": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000 }, "zone": { "type": [ "string", "null" ], "maxLength": 128 } }, "required": [ "id", "lat", "lng" ] }, "description": "The points to cut, 1-10000, each `{id, lat, lng, weight?, zone?, allowed_zones?}`; `weight` defaults to 1." }, "tolerance_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 50, "description": "How far a territory's weight may be from its target, 0-50 percent, default 10." }, "zones": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "anchor": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Required when zones.*.anchor is present." }, "lng": { "type": "number", "minimum": -180, "maximum": 180, "description": "Required when zones.*.anchor is present." } } }, "id": { "type": "string", "maxLength": 128 }, "share": { "type": [ "number", "null" ], "maximum": 1000, "exclusiveMinimum": 0 } }, "required": [ "id" ] }, "description": "The territories, each `{id, anchor?, share?}`: `anchor` `{lat, lng}` is a depot the territory grows around, `share` its relative size." } }, "additionalProperties": false, "required": [ "points", "zones" ] }, "example": { "points": [ { "id": "stop-1", "lat": 45.48886, "lng": -73.63285, "weight": 1 }, { "id": "stop-2", "lat": 45.45869, "lng": -73.56354, "weight": 3 }, { "id": "stop-3", "lat": 45.51993, "lng": -73.49625, "weight": 2 }, { "id": "stop-4", "lat": 45.4545, "lng": -73.58194, "weight": 1 }, { "id": "stop-5", "lat": 45.47888, "lng": -73.56081, "weight": 1 }, { "id": "stop-6", "lat": 45.54922, "lng": -73.63772, "weight": 2 }, { "id": "stop-7", "lat": 45.52568, "lng": -73.55506, "weight": 1 }, { "id": "stop-8", "lat": 45.51925, "lng": -73.5886, "weight": 2 }, { "id": "stop-9", "lat": 45.45559, "lng": -73.50548, "weight": 3 }, { "id": "stop-10", "lat": 45.5003, "lng": -73.56268, "weight": 3 }, { "id": "stop-11", "lat": 45.51723, "lng": -73.53724, "weight": 1 }, { "id": "stop-12", "lat": 45.51979, "lng": -73.545, "weight": 3 } ], "zones": [ { "id": "east", "anchor": { "lat": 45.5, "lng": -73.55 } }, { "id": "west", "anchor": { "lat": 45.5, "lng": -73.64 } }, { "id": "north", "share": 0.5 } ], "tolerance_percent": 20 } } } } } }, "/v1/trace/match": { "post": { "operationId": "traceMatch", "tags": [ "trace" ], "summary": "Match a GPS trace", "description": "Places each point of `points` (2 to 5000, in driving order, each with `lat`, `lng` and optionally an `id` and a `time` in ISO 8601 with an offset) on the road it was most likely driven on for the vehicle `profile`. Each point comes back with its `type` (`matched`, `interpolated` or `unmatched`), its position on the road, how far it was moved and the road's name; `roads` lists the roads driven in order with their class, speed and distance; `summary.distance_meters` is the length of the drive; `geometry` is the driven line as a GeoJSON LineString (set `geometry` to false to leave it out). `search_radius_meters` (at most 200) limits how far a point may be moved. Times help with sparse or noisy traces. Nothing is stored. Billed per point, invoiced per thousand.\n\nSnap a GPS trace to the roads it was driven on and measure the drive.", "x-superroute-capability": "trace.match", "x-superroute-billing-unit": "point_1k", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/trace.match", "responses": { "200": { "description": "The trace matched to roads: every point placed, the roads driven and the drive's length. Billed per point.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "trace.match" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "point_1k" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "points": { "type": "array", "description": "Every point of the trace, in the order given.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The point's place in `points`, from 0." }, "id": { "type": [ "string", "null" ], "description": "The point's id, when given." }, "type": { "type": "string", "enum": [ "matched", "interpolated", "unmatched" ], "description": "`matched`: placed on a road; `interpolated`: placed between matched points; `unmatched`: no road found." }, "lat": { "type": [ "number", "null" ], "description": "Where the point lies on the road." }, "lng": { "type": [ "number", "null" ], "description": "Where the point lies on the road." }, "moved_meters": { "type": [ "number", "null" ], "description": "How far the point was moved onto the road." }, "road": { "type": [ "string", "null" ], "description": "The name of the road, when it has one." } } } }, "roads": { "type": "array", "description": "The roads driven, in order; consecutive stretches of one road are one entry.", "items": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "description": "The road's names; empty for an unnamed road." }, "road_class": { "type": "string", "description": "The road's class: motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_other." }, "speed_kmh": { "type": [ "integer", "null" ], "description": "The road's typical speed." }, "distance_meters": { "type": "integer", "description": "Distance driven on it." } } } }, "summary": { "type": "object", "properties": { "points": { "type": "integer", "description": "Points submitted." }, "matched": { "type": "integer", "description": "Points placed on a road." }, "interpolated": { "type": "integer", "description": "Points placed between matched points." }, "unmatched": { "type": "integer", "description": "Points no road was found for." }, "distance_meters": { "type": "integer", "description": "The length of the drive." } } }, "geometry": { "type": "object", "description": "The driven line as a GeoJSON LineString ([lng, lat]). Absent when `geometry` is false." } }, "required": [ "points", "roads", "summary" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "trace.match", "billing": { "unit": "point_1k", "quantity": 8, "counted": true }, "data": { "points": [ { "index": 0, "id": "fix-1", "type": "matched", "lat": 45.498367, "lng": -73.571597, "moved_meters": 2.6, "road": "Rue Stanley" }, { "index": 1, "id": "fix-2", "type": "matched", "lat": 45.499086, "lng": -73.569893, "moved_meters": 2, "road": "Boulevard René-Lévesque Ouest" }, { "index": 2, "id": "fix-3", "type": "matched", "lat": 45.50129, "lng": -73.567829, "moved_meters": 4.4, "road": "Boulevard René-Lévesque Ouest" }, { "index": 3, "id": "fix-4", "type": "matched", "lat": 45.502922, "lng": -73.566398, "moved_meters": 9.3, "road": "Boulevard René-Lévesque Ouest" }, { "index": 4, "id": "fix-5", "type": "matched", "lat": 45.502289, "lng": -73.564558, "moved_meters": 3.8, "road": "Côte du Beaver Hall" }, { "index": 5, "id": "fix-6", "type": "matched", "lat": 45.502045, "lng": -73.563414, "moved_meters": 5.8, "road": "Côte du Beaver Hall" }, { "index": 6, "id": "fix-7", "type": "matched", "lat": 45.502874, "lng": -73.560672, "moved_meters": 4.4, "road": "Rue Saint-Antoine Ouest" }, { "index": 7, "id": "fix-8", "type": "matched", "lat": 45.504973, "lng": -73.558873, "moved_meters": 3.8, "road": "Rue Saint-Antoine Ouest" } ], "roads": [ { "names": [ "Rue Stanley" ], "road_class": "residential", "speed_kmh": 30, "distance_meters": 67 }, { "names": [ "Boulevard René-Lévesque Ouest" ], "road_class": "secondary", "speed_kmh": 50, "distance_meters": 662 }, { "names": [ "Côte du Beaver Hall" ], "road_class": "tertiary", "speed_kmh": 40, "distance_meters": 280 }, { "names": [ "Rue du Square Victoria" ], "road_class": "tertiary", "speed_kmh": 30, "distance_meters": 113 }, { "names": [ "Rue Saint-Antoine Ouest" ], "road_class": "secondary", "speed_kmh": 49, "distance_meters": 463 } ], "summary": { "points": 8, "matched": 8, "interpolated": 0, "unmatched": 0, "distance_meters": 1585 }, "geometry": { "type": "LineString", "coordinates": [ [ -73.571598, 45.498367 ], [ -73.571479, 45.498308 ], [ -73.571149, 45.498132 ], [ -73.57112, 45.498116 ], [ -73.571049, 45.498079 ], [ -73.570902, 45.498007 ], [ -73.57085, 45.498061 ], [ -73.570706, 45.498216 ], [ -73.570579, 45.498355 ], [ -73.570424, 45.498523 ], [ -73.570397, 45.498553 ], [ -73.570284, 45.498673 ], [ -73.570199, 45.498762 ], [ -73.57015, 45.498813 ], [ -73.570117, 45.498849 ], [ -73.569971, 45.499004 ], [ -73.569894, 45.499087 ], [ -73.56974, 45.49925 ], [ -73.569719, 45.499274 ], [ -73.569664, 45.499334 ], [ -73.569541, 45.499463 ], [ -73.56949, 45.499517 ], [ -73.569244, 45.499785 ], [ -73.56917, 45.49986 ], [ -73.569046, 45.49999 ], [ -73.569027, 45.500011 ], [ -73.568971, 45.500073 ], [ -73.568916, 45.500131 ], [ -73.568903, 45.500144 ], [ -73.568534, 45.500536 ], [ -73.568133, 45.500966 ], [ -73.568076, 45.501026 ], [ -73.567829, 45.501291 ], [ -73.567507, 45.501639 ], [ -73.567451, 45.501698 ], [ -73.567428, 45.50172 ], [ -73.567354, 45.501796 ], [ -73.567236, 45.501928 ], [ -73.567174, 45.501996 ], [ -73.566956, 45.502222 ], [ -73.566784, 45.502408 ], [ -73.566768, 45.502425 ], [ -73.566724, 45.502472 ], [ -73.566681, 45.502519 ], [ -73.566667, 45.502534 ], [ -73.566643, 45.502565 ], [ -73.566585, 45.502648 ], [ -73.566541, 45.502711 ], [ -73.566415, 45.502899 ], [ -73.566399, 45.502923 ], [ -73.566333, 45.503032 ], [ -73.56619, 45.502991 ], [ -73.566159, 45.50298 ], [ -73.565696, 45.502759 ], [ -73.565468, 45.502653 ], [ -73.565065, 45.502461 ], [ -73.565035, 45.502448 ], [ -73.564962, 45.502418 ], [ -73.564879, 45.502387 ], [ -73.564846, 45.502376 ], [ -73.564782, 45.502354 ], [ -73.56471, 45.502331 ], [ -73.564633, 45.502308 ], [ -73.564543, 45.502286 ], [ -73.564463, 45.502269 ], [ -73.564401, 45.502257 ], [ -73.564333, 45.502243 ], [ -73.56429, 45.502236 ], [ -73.564205, 45.502225 ], [ -73.564119, 45.502213 ], [ -73.56408, 45.502208 ], [ -73.564013, 45.502196 ], [ -73.563923, 45.50218 ], [ -73.563849, 45.502165 ], [ -73.563775, 45.502149 ], [ -73.563712, 45.502133 ], [ -73.563632, 45.502112 ], [ -73.563552, 45.502088 ], [ -73.563477, 45.502066 ], [ -73.563379, 45.502034 ], [ -73.563277, 45.502 ], [ -73.563235, 45.501983 ], [ -73.563188, 45.501961 ], [ -73.56315, 45.50194 ], [ -73.563069, 45.501894 ], [ -73.562052, 45.50145 ], [ -73.56202, 45.501435 ], [ -73.561934, 45.501394 ], [ -73.561903, 45.50143 ], [ -73.561881, 45.501457 ], [ -73.561722, 45.501634 ], [ -73.561697, 45.501663 ], [ -73.561641, 45.501726 ], [ -73.561589, 45.501786 ], [ -73.561222, 45.50223 ], [ -73.560672, 45.502874 ], [ -73.560443, 45.503122 ], [ -73.560422, 45.503145 ], [ -73.56037, 45.503204 ], [ -73.560308, 45.503277 ], [ -73.559974, 45.50368 ], [ -73.559757, 45.503939 ], [ -73.559708, 45.503996 ], [ -73.559662, 45.504051 ], [ -73.559594, 45.504126 ], [ -73.559294, 45.504485 ], [ -73.559215, 45.504579 ], [ -73.559195, 45.504603 ], [ -73.559164, 45.50464 ], [ -73.559129, 45.504678 ], [ -73.558989, 45.50484 ], [ -73.558874, 45.504973 ] ] } }, "meta": { "profile": "car", "geometry_format": "geojson" } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } }, "502": { "description": "The routing engine is temporarily unreachable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "ENGINE_UNAVAILABLE", "message": "The routing engine is temporarily unreachable. Please retry.", "status": 502, "doc_url": "/developer/errors/ENGINE_UNAVAILABLE" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "geometry": { "type": [ "boolean", "null" ], "description": "Whether to return the driven line. Default true." }, "points": { "type": "array", "minItems": 2, "maxItems": 5000, "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 128 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "time": [] }, "required": [ "lat", "lng" ] }, "description": "The GPS points in driving order, 2-5000, each `{id?, lat, lng, time?}`; `time` in ISO 8601 with an offset." }, "profile": { "type": [ "string", "null" ], "enum": [ "car", "van", "truck", "bike", "foot", "motorcycle" ], "description": "The vehicle the roads are costed for: `car` (default when omitted) and `van` use the car costing; `truck`, `motorcycle`, `bike` and `foot` use the road costing of that vehicle. `motorcycle` avoids roads a motorcycle may not use. The Open Platform does not expose road preferences (avoid tolls, avoid highways) today, so the profile's default road preferences apply." }, "search_radius_meters": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "description": "How far a point may be moved onto a road, 1-200 metres. Omitted: the platform's default." } }, "additionalProperties": false, "required": [ "points" ] }, "example": { "points": [ { "id": "fix-1", "lat": 45.498348, "lng": -73.571617, "time": "2026-11-02T08:00:00-05:00" }, { "id": "fix-2", "lat": 45.499071, "lng": -73.569882, "time": "2026-11-02T08:00:21-05:00" }, { "id": "fix-3", "lat": 45.501306, "lng": -73.567881, "time": "2026-11-02T08:00:42-05:00" }, { "id": "fix-4", "lat": 45.502841, "lng": -73.566375, "time": "2026-11-02T08:01:03-05:00" }, { "id": "fix-5", "lat": 45.502257, "lng": -73.564575, "time": "2026-11-02T08:01:24-05:00" }, { "id": "fix-6", "lat": 45.502093, "lng": -73.563383, "time": "2026-11-02T08:01:45-05:00" }, { "id": "fix-7", "lat": 45.502914, "lng": -73.560675, "time": "2026-11-02T08:02:07-05:00" }, { "id": "fix-8", "lat": 45.504991, "lng": -73.558915, "time": "2026-11-02T08:02:28-05:00" } ], "profile": "car" } } } } } }, "/v1/webhooks/verify": { "post": { "operationId": "webhooksVerify", "tags": [ "platform" ], "summary": "Verify a webhook endpoint", "description": "Performs a handshake against a callback URL before it may be used. An unverified URL is rejected at job submission rather than after the solve has been billed.\n\nTrack a long-running solve and collect its result.", "x-superroute-capability": "platform.jobs", "x-superroute-billing-unit": "free", "x-superroute-release-stage": "ga", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/platform.jobs", "responses": { "200": { "description": "Whether the endpoint answered the challenge. A job callback is accepted only for a URL verified this way: the endpoint receives `{\"event\": \"endpoint.verify\", \"challenge\": \"...\"}` and must answer 2xx with `{\"challenge\": \"\"}`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "The endpoint echoed the challenge." }, "reason": { "type": [ "string", "null" ], "description": "Why verification failed; null when verified. `UNSAFE` (not a public HTTPS address), `UNREACHABLE` (no answer within the timeout), `HTTP_` (the status your endpoint answered) or `CHALLENGE_MISMATCH`." } }, "required": [ "verified" ] }, "meta": { "type": "object" } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "data": { "verified": true, "reason": null } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "404": { "description": "No such job, or it belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FOUND", "message": "No such job, or it belongs to another account.", "status": 404, "doc_url": "/developer/errors/JOB_NOT_FOUND" } } } } }, "409": { "description": "The job has not finished yet. Poll the job, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_NOT_FINISHED", "message": "The job has not finished yet. Poll the job, or wait for the callback.", "status": 409, "doc_url": "/developer/errors/JOB_NOT_FINISHED" } } } } }, "410": { "description": "The result has expired and is no longer available. Submit the request again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "JOB_RESULT_EXPIRED", "message": "The result has expired and is no longer available. Submit the request again.", "status": 410, "doc_url": "/developer/errors/JOB_RESULT_EXPIRED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "additionalProperties": false, "required": [ "url" ] }, "example": { "url": "https://hooks.example.com/superroute", "secret": "whsec_0123456789abcdef" } } } } } }, "/v1/weight/chargeable": { "post": { "operationId": "weightChargeable", "tags": [ "weight" ], "summary": "Work out chargeable weight", "description": "For each package in `packages` (weight with `weight_unit` g, kg, oz or lb; length, width and height with `dimension_unit` mm, cm, m or in; optional `quantity`) returns the actual weight, the volumetric weight (volume divided by `divisor`) and the chargeable weight, the greater of the two, with which one decided it. `divisor` is in cm³ per kg (`divisor_unit: cm3_kg`, default 5000) or in in³ per lb (`in3_lb`, default 139); results are in `weight_unit` (kg, or lb with an in³/lb divisor). `increment` rounds every chargeable weight up to a multiple (0.5 kg, 1 lb). `totals` gives the packages' sum, billed package by package, and `shipment_chargeable_weight`, the whole shipment taken at once. Nothing is stored. Billed one call.\n\nWork out the weight a carrier bills: the greater of actual and volumetric weight.", "x-superroute-capability": "weight.chargeable", "x-superroute-billing-unit": "call", "x-superroute-release-stage": "beta", "x-superroute-async": false, "x-superroute-docs": "/developer/capabilities/weight.chargeable", "responses": { "200": { "description": "The chargeable weight of every package and of the shipment. Billed one call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identifies this request. Quote it to support." }, "capability": { "type": "string", "const": "weight.chargeable" }, "billing": { "type": "object", "description": "What this call cost. `counted` is false when the call was not billed (for example a job result, billed when the job was accepted).", "properties": { "unit": { "type": "string", "const": "call" }, "quantity": { "type": "number", "description": "Billed quantity in `unit`." }, "counted": { "type": "boolean" }, "breakdown": { "type": "object", "description": "How `quantity` was derived." } } }, "warnings": { "type": "array", "description": "Present only when there is something to report. The answer is still complete.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Never localized. Branch on this." }, "message": { "type": "string" } } } }, "data": { "type": "object", "properties": { "weight_unit": { "type": "string", "enum": [ "kg", "lb" ], "description": "The unit of every weight in the answer." }, "divisor": { "type": "number", "description": "The divisor used." }, "divisor_unit": { "type": "string", "enum": [ "cm3_kg", "in3_lb" ], "description": "The divisor's unit." }, "packages": { "type": "array", "description": "Every package, in the order given; weights are for one package.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The package id, or its number from 1." }, "quantity": { "type": "integer", "description": "How many such packages." }, "actual_weight": { "type": "number", "description": "Its weight, in `weight_unit`." }, "volumetric_weight": { "type": "number", "description": "Its volume divided by the divisor, in `weight_unit`." }, "chargeable_weight": { "type": "number", "description": "The greater of the two, rounded up to `increment` when given." }, "basis": { "type": "string", "enum": [ "actual", "volumetric" ], "description": "Which weight decided." } } } }, "totals": { "type": "object", "properties": { "packages": { "type": "integer", "description": "Packages counted with their quantities." }, "actual_weight": { "type": "number", "description": "Sum of actual weights." }, "volumetric_weight": { "type": "number", "description": "Sum of volumetric weights." }, "chargeable_weight": { "type": "number", "description": "Sum of each package's chargeable weight: billed package by package." }, "shipment_chargeable_weight": { "type": "number", "description": "The greater of the summed actual and volumetric weights: the shipment billed as one." } } } }, "required": [ "weight_unit", "packages", "totals" ] }, "meta": { "type": "object", "properties": [], "additionalProperties": true } }, "required": [ "request_id", "data" ] }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "capability": "weight.chargeable", "billing": { "unit": "call", "quantity": 1, "counted": true }, "data": { "weight_unit": "kg", "divisor": 5000, "divisor_unit": "cm3_kg", "packages": [ { "id": "box-1", "quantity": 1, "actual_weight": 2.4, "volumetric_weight": 7.2, "chargeable_weight": 7.5, "basis": "volumetric" }, { "id": "box-2", "quantity": 2, "actual_weight": 9, "volumetric_weight": 1.8, "chargeable_weight": 9, "basis": "actual" } ], "totals": { "packages": 3, "actual_weight": 20.4, "volumetric_weight": 10.8, "chargeable_weight": 25.5, "shipment_chargeable_weight": 20.5 } }, "meta": { "cm3_per_kg": 5000, "increment": 0.5 } } } } }, "401": { "description": "No API token. Send Authorization: Bearer .", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "TOKEN_MISSING", "message": "No API token. Send Authorization: Bearer .", "status": 401, "doc_url": "/developer/errors/TOKEN_MISSING" } } } } }, "402": { "description": "The included allowance for this capability is used up for the current period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "QUOTA_EXHAUSTED", "message": "The included allowance for this capability is used up for the current period.", "status": 402, "doc_url": "/developer/errors/QUOTA_EXHAUSTED" } } } } }, "403": { "description": "Open Platform access is not enabled for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "OPEN_API_DISABLED", "message": "Open Platform access is not enabled for this account.", "status": 403, "doc_url": "/developer/errors/OPEN_API_DISABLED" } } } } }, "422": { "description": "The request failed validation. See details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "VALIDATION_FAILED", "message": "The request failed validation. See details.", "status": 422, "doc_url": "/developer/errors/VALIDATION_FAILED" } } } } }, "429": { "description": "Too many requests. Please retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please retry after the indicated delay.", "status": 429, "doc_url": "/developer/errors/RATE_LIMITED" } } } } }, "500": { "description": "An unexpected error occurred. Quote the request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenError" }, "example": { "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d", "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Quote the request_id when contacting support.", "status": 500, "doc_url": "/developer/errors/INTERNAL_ERROR" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "divisor": { "type": [ "number", "null" ], "maximum": 100000, "exclusiveMinimum": 0 }, "divisor_unit": { "type": [ "string", "null" ], "enum": [ "cm3_kg", "in3_lb" ] }, "increment": { "type": [ "number", "null" ], "maximum": 100, "exclusiveMinimum": 0 }, "packages": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "dimension_unit": { "type": [ "string", "null" ], "enum": [ "mm", "cm", "m", "in" ] }, "height": { "type": "number", "minimum": 0 }, "id": { "type": [ "string", "null" ], "maxLength": 128 }, "length": { "type": "number", "minimum": 0 }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "weight": { "type": "number", "minimum": 0 }, "weight_unit": { "type": [ "string", "null" ], "enum": [ "g", "kg", "oz", "lb" ] }, "width": { "type": "number", "minimum": 0 } }, "required": [ "height", "length", "weight", "width" ] } }, "weight_unit": { "type": [ "string", "null" ], "enum": [ "kg", "lb" ] } }, "additionalProperties": false, "required": [ "packages" ] }, "example": { "packages": [ { "id": "box-1", "weight": 2.4, "weight_unit": "kg", "length": 40, "width": 30, "height": 30, "dimension_unit": "cm" }, { "id": "box-2", "quantity": 2, "weight": 9, "weight_unit": "kg", "length": 30, "width": 20, "height": 15, "dimension_unit": "cm" } ], "divisor": 5000, "divisor_unit": "cm3_kg", "increment": 0.5 } } } } } } } }