> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapshit.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Start the API">
    ```bash theme={null}
    git clone https://github.com/r-thak/motion.git && cd motion
    docker compose up -d
    ```

    The API starts at `http://localhost:8000`. Verify with:

    ```bash theme={null}
    curl http://localhost:8000/health
    # {"status": "ok"}
    ```
  </Step>

  <Step title="Compute your first route">
    Send a request from Chicago downtown to Midway - that's it:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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"
      }]
    }
    ```
  </Step>

  <Step title="Try the RESTful Routes API">
    For async processing, webhooks, and route persistence - use the `/v1/routes` endpoints:

    ```bash theme={null}
    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"
      }'
    ```

    ```json theme={null}
    {
      "id": "route_01HYX3MPK5XJQJG0NB0PRSDVWC",
      "object": "route",
      "status": "complete",
      "createdAt": "2026-03-01T14:00:01Z",
      "routes": [...]
    }
    ```

    Then retrieve it anytime, or fetch its segment-level telemetry:

    ```bash theme={null}
    # 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
    ```
  </Step>
</Steps>

## What makes Motion different

<CardGroup cols={2}>
  <Card title="Google-compatible" icon="arrows-rotate">
    Same request/response format as Google Routes API. Change your base URL and get enrichment for free.
  </Card>

  <Card title="Physics enrichment" icon="flask">
    Grade, curvature, fuel burn, speed limits, and road class on every step - computed from USGS elevation data and road geometry.
  </Card>

  <Card title="Stateful routes" icon="database">
    Create, retrieve, poll, and delete routes. Async processing with webhook notifications for long computations.
  </Card>

  <Card title="Idempotent & safe" icon="shield-check">
    Idempotency keys for safe retries. Rate limiting with clear headers. Consistent error responses.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/endpoint/google-compute-routes">
    Explore all endpoints with interactive examples.
  </Card>

  <Card title="Tech Stack" icon="layer-group" href="/development">
    Learn about the architecture and run locally.
  </Card>
</CardGroup>