v4

latestOpenAPI 3.1.0Proprietary2026-08-034715226.2 KB

routing

Compute a truck route with hazard enrichment

Returns a routed polyline annotated with warnings[] — every nearby hazard, restriction, and operational note our database knows about (active incidents, planned construction, bridge clearance/weight problems for the requested truck, public at-grade rail crossings with 49 CFR 392.10 hazmat-stop awareness, truck/weight restrictions, weigh stations, weather, alerts, special events). When the load is hazardous, segments restricted to hazardous materials surface as hazmat_restriction warnings, and the routing engine is asked to avoid them via the hazardous/tunnel_category profile. Invalid hazardous or tunnel_category values are rejected with HTTP 400.

Every successful call:

Counts against the customer's monthly routing quota (subscription bucket first, then top-ups FIFO by expiry). Cache hits still charge — the route is the API call regardless of whether we re-used a cached payload.
Auto-saves the result to saved_routes with a 30-minute TTL. The returned route_id can be refetched (with re-evaluated warnings) via GET /routing/route/saved/{id} or persisted via POST /routing/route/saved/{id}/persist.

The truck block is required on every request. See the request schema for the full set of vehicle parameters.

Unknown request fields are accepted, not rejected — but any key the server did not bind is echoed back in ignored_fields (sorted dotted paths, e.g. truck.axles) and in the X-Routing-Ignored-Fields response header. Use it to catch a mis-spelled field: axles instead of axle_count, or origin.lon instead of origin.lng, is silently dropped otherwise and the route is computed without it.

Supplying truck.hos (the driver's Hours-of-Service clock) adds an hos[] channel to each route: the points where the driver must take a break or stop driving under the chosen regime (US, Canada, EU), each with reachable truck parking / rest areas before the limit. It is free on every plan. See truck.hos in the request schema.

post/routing/route

Request body

alternativesinteger

arrival_timestring

Mutually exclusive with departure_time

avoidstring[]

avoid_countriesstring[]

Route around these countries entirely where possible (ISO 3166-1 alpha-3 codes, e.g. "USA", "CAN").

avoid_truck_roadsstring[]

Avoid these truck-road usage classes.

avoid_zonesstring[]

Avoid whole categories of zone along the route.

currencystring

ISO 4217; only honored when tolls is requested

customer_route_idstring

Opaque client-side correlation key. Echoed verbatim in the response. Not used by enrichment.

departure_timestring

ISO 8601 or 'now'; defaults to 'now'

detailsstring[]

Per-span road-attribute detail channels to compute along the route (returned on the route's spans). Independent of include.

exclude_countriesstring[]

Hard-exclude these countries from the route (ISO 3166-1 alpha-3). Stricter than avoid_countries — the route will fail rather than pass through.

includestring[]

Optional route detail channels to compute. polyline and summary are always included. Request tolls to have the routing engine price the route's toll systems for your truck profile — the cost then appears as routes[].sections[].tolls[] (per toll system) and is rolled up per currency into routes[].summary.toll_costs[]. Set currency (ISO 4217) to control the fare currency. Toll pricing adds upstream cost, so it is off unless requested.

Request mileage_by_state for a per-jurisdiction distance breakdown on routes[].summary.mileage_by_state[] — one entry per US state / Canadian province the route touches, ordered longest-first, computed by intersecting the route with fixed jurisdiction boundary polygons. A stable, reproducible figure for IFTA quarterly reporting, mileage-based billing, and driver pay. Off unless requested (it adds a spatial query).

Request toll_alternative (paid plans only; implies tolls) to also compute a second, toll-free route and price the trade — extra distance/time vs. toll dollars saved — returned as the top-level toll_alternative block. Because this computes a second route, it is billed as 2 routing calls (or 1 when the whole response is served from cache). If the second route can't be produced the primary route still returns, with the reason in toll_alternative_omitted.

Request parking_trend to add typical_occupancy to every parking/rest feature in features[] and to each hos[].suggested_stops[] — what that lot's recorded occupancy history says about the hour you are projected to reach it, rather than how many spaces are free right now. Off unless requested (it adds a history query), and a lot with no recorded history simply omits the block.

languagestring

BCP-47 (e.g. en-US)

optimize'time' | 'distance'

tagsstring[]

Free-form labels for fleet/lane analytics rollup. Echoed and stored on the saved route. Max 16 tags, each up to 64 chars.

traffic'live' | 'historical' | 'off'

units'metric' | 'imperial'

Response

Route computed with warnings enriched