Skip to main content

​
Your first route in 7 lines

Motion is a drop-in replacement for the Google Routes API that adds physics-based enrichment for heavy freight - grade, curvature, fuel burn, and zone awareness on every step.
1

Start the API

git clone https://github.com/r-thak/motion.git && cd motion
docker compose up -d
The API starts at http://localhost:8000. Verify with:
curl http://localhost:8000/health
# {"status": "ok"}
2

Compute your first route

Send a request from Chicago downtown to Midway - that’s it:
curl -X POST http://localhost:8000/directions/v2:computeRoutes \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {"location": {"latLng": {"latitude": 41.878, "longitude": -87.636}}},
    "destination": {"location": {"latLng": {"latitude": 41.705, "longitude": -87.613}}}
  }'
The response is identical to Google’s computeRoutes - same fields, same format - but every step includes an enrichment object with physics data:
{
  "routes": [{
    "legs": [{
      "steps": [{
        "distanceMeters": 542,
        "staticDuration": "28s",
        "polyline": {"encodedPolyline": "..."},
        "navigationInstruction": {"maneuver": "DEPART", "instructions": "Head south"},
        "enrichment": {
          "gradePercent": 1.2,
          "curvatureDegreesPerKm": 8.5,
          "fuelBurnLiters": 0.08,
          "zoneFlags": [],
          "speedLimitKmh": 56.0,
          "roadClass": "PRIMARY"
        }
      }]
    }],
    "distanceMeters": 21450,
    "duration": "1820s"
  }]
}
3

Try the RESTful Routes API

For async processing, webhooks, and route persistence - use the /v1/routes endpoints:
curl -X POST http://localhost:8000/v1/routes \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-route" \
  -d '{
    "origin": {"location": {"latLng": {"latitude": 41.878, "longitude": -87.636}}},
    "destination": {"location": {"latLng": {"latitude": 41.705, "longitude": -87.613}}},
    "vehicleSpec": {"type": "SEMI_TRAILER", "grossWeightKg": 36000},
    "departureTime": "2026-03-01T14:00:00Z"
  }'

{
  "id": "route_01HYX3MPK5XJQJG0NB0PRSDVWC",
  "object": "route",
  "status": "complete",
  "createdAt": "2026-03-01T14:00:01Z",
  "routes": [...]
}
Then retrieve it anytime, or fetch its segment-level telemetry:
# Get the route
curl http://localhost:8000/v1/routes/route_01HYX3MPK5XJQJG0NB0PRSDVWC

# Get paginated telemetry
curl "http://localhost:8000/v1/routes/route_01HYX3MPK5XJQJG0NB0PRSDVWC/telemetry?limit=10"

# Delete when done
curl -X DELETE http://localhost:8000/v1/routes/route_01HYX3MPK5XJQJG0NB0PRSDVWC

​
What makes Motion different

Google-compatible

Same request/response format as Google Routes API. Change your base URL and get enrichment for free.

Physics enrichment

Grade, curvature, fuel burn, speed limits, and road class on every step - computed from USGS elevation data and road geometry.

Stateful routes

Create, retrieve, poll, and delete routes. Async processing with webhook notifications for long computations.

Idempotent & safe

Idempotency keys for safe retries. Rate limiting with clear headers. Consistent error responses.

​
Next steps

API Reference

Explore all endpoints with interactive examples.

Tech Stack

Learn about the architecture and run locally.