Introduction

Motion Freight Router API - truck routing with physics-based enrichment

Overview

Motion is a drop-in replacement for the Google Routes API that adds segment-level physics enrichment for heavy freight. Every route step includes grade, curvature, fuel burn, zone awareness, and road classification - computed from real USGS elevation data and road geometry.

It exposes two interfaces to the same routing engine:

Google-Compatible

Drop-in replacement for Google Routes API. Same request and response format - change only the base URL.

Route Resources

Stateful routes with async processing, webhooks, idempotency, and telemetry.

Endpoints

Google-Compatible

Method	Endpoint	Description
POST	/directions/v2:computeRoutes	Compute a route synchronously (Google Routes API format)

Route Management

Method	Endpoint	Description
POST	/v1/routes	Create a route (returns immediately or asynchronously)
GET	/v1/routes/{route_id}	Retrieve a route by ID
DELETE	/v1/routes/{route_id}	Delete a route
GET	/v1/routes/{route_id}/telemetry	Get segment-level telemetry data

Enrichment

Every route step is enriched with physics data computed from elevation models, road geometry, and vehicle parameters:

Field	Description
gradePercent	Road grade derived from USGS elevation data
curvatureDegreesPerKm	Bearing change per kilometer
fuelBurnLiters	Fuel consumption estimate using road-load equations
zoneFlags	School zone and residential area detection
speedLimitKmh	Posted speed limit
roadClass	Road classification (motorway, primary, residential, etc.)

Vehicle Presets

Two built-in presets are available. All parameters can be individually overridden in the request.

Preset	Weight	Dimensions (L × W × H)
SEMI_TRAILER	36,000 kg	21.6 × 2.6 × 4.1 m
BOX_TRUCK	12,000 kg	10.0 × 2.4 × 3.5 m

Routing Profiles

Profiles control the relative weight of each enrichment factor:

Profile	Fuel	Grade	Zone
balanced	1.0	1.0	1.0
fuel_optimal	2.0	1.5	0.5
time_optimal	0.3	0.3	0.3
fatigue_aware	0.8	1.0	1.5

Errors

All error responses use a consistent structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_waypoint_type",
    "message": "Address and placeId waypoints are not supported; use latLng coordinates.",
    "param": "origin"
  }
}

Error type	Description
invalid_request_error	The request was malformed or missing required fields
routing_error	The routing engine could not compute a route
rate_limit_error	Rate limit exceeded (60 requests/min per IP)
api_error	An internal server error occurred
enrichment_error	Enrichment data could not be computed

Rate-limited responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Idempotency

POST /v1/routes accepts an Idempotency-Key header for safe retries. Requests with the same key and body return a cached response. Reusing a key with a different body returns 422.