Quickstart

Get your first truck route in under 30 seconds

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.