Capability discovery
List what this key can call, at what price, against which quota.
platform.capabilities
Stable
free
How to call it
REST
GET
/v1/capabilities
GET
/v1/capabilities/{code}
GET
/v1/geo/coverage
GET
/v1/routing/presets
GraphQL
query
openCapabilities
query
openGeoCoverage
query
openRoutingPresets
MCP
open_geo_coverage
Which countries the geocoding chain covers and how well. Free — you must be able to ask whether your market is covered before you buy anything.
open_platform_capabilities
List every Open Platform capability, whether this connection may call it, what it is billed in, and where its documentation is. Call this first: it is the only reliable way to know what the connected client has bought.
open_routing_presets
The engine's balance presets and what each one optimizes for, plus the four modes the platform enforces itself on either engine: `tolerance` (every vehicle's task count within a percentage of the balanced share), `zone` (one compact, non-crossing zone per vehicle), `hours` (every vehicle's working day within the band, by closing the days at the band's top and re-solving) and `zone_hours` (the zones cut on time and re-cut from the measured working day, so routes never cross and the days come out even). Each entry names the field, its range and default, and how the result is reported in meta.balance. Free — you have to be able to discover a field's valid values before you can fill it in.
Response
What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.
GET /v1/capabilities
Response schema
{
"description": "Every capability, whether this key may call it, what it is billed in and its limits. The example is shortened to two capabilities.",
"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."
}
}
}
}
}
}Response 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
}
}
}GET /v1/capabilities/{code}
Response schema
{
"description": "One capability, in the same shape as an entry of GET /v1/capabilities.",
"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."
}
}
}
}Response 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"
}
}GET /v1/geo/coverage
Response schema
{
"description": "Which providers answer for which country, in the order they are tried. Free. The example is shortened to two countries and two providers.",
"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."
}
}
}
}
}
}
}Response 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
}
]
}
}GET /v1/routing/presets
Response schema
{
"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.",
"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."
}
}
}
}
}
}Response 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."
}
}
}What it costs
Never billed, and never disable-able.
Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.
Errors it can return
| Status | Code | Description |
|---|---|---|
| 401 | SESSION_EXPIRED |
The session token is invalid or has expired. |
| 401 | TOKEN_INVALID |
Unknown or revoked API token. |
| 401 | TOKEN_MISSING |
No API token. Send Authorization: Bearer <your token>. |
| 403 | CAPABILITY_NOT_ENABLED |
This capability is not enabled for your account. See :doc to enable it. |
| 403 | CAPABILITY_NOT_GRANTED_TO_KEY |
Your account has this capability, but this API key was not granted it. |
| 403 | OPEN_API_DISABLED |
Open Platform access is not enabled for this account. |
| 404 | JOB_NOT_FOUND |
No such job, or it belongs to another account. |
| 409 | JOB_NOT_FINISHED |
The job has not finished yet. Poll the job, or wait for the callback. |
| 410 | JOB_RESULT_EXPIRED |
The result has expired and is no longer available. Submit the request again. |
| 422 | VALIDATION_FAILED |
The request failed validation. See details. |
| 429 | RATE_LIMITED |
Too many requests. Please retry after the indicated delay. |
| 500 | INTERNAL_ERROR |
An unexpected error occurred. Quote the request_id when contacting support. |