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

# Introduction

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

## Overview

Motion is a **drop-in replacement for the [Google Routes API](https://developers.google.com/maps/documentation/routes/compute_route_directions)** 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:

<CardGroup cols={2}>
  <Card title="Google-Compatible" icon="arrows-rotate" href="/endpoint/google-compute-routes">
    Drop-in replacement for Google Routes API. Same request and response format - change only the base URL.
  </Card>

  <Card title="Route Resources" icon="route" href="/endpoint/create-route">
    Stateful routes with async processing, webhooks, idempotency, and telemetry.
  </Card>
</CardGroup>

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

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