Create Route

Creates a route resource with physics enrichment.

POST /v1/routes

cURL

simple

curl --request POST \
  --url http://localhost:8000/v1/routes \
  --header 'Content-Type: application/json' \
  --data '
{
  "origin": {
    "location": {
      "latLng": {
        "latitude": 41.878,
        "longitude": -87.636
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 41.705,
        "longitude": -87.613
      }
    }
  }
}
'

200

Example

{
  "id": "route_01HYX3MPK5XJQJG0NB0PRSDVWC",
  "object": "route",
  "status": "complete",
  "createdAt": "2026-02-28T15:12:32Z",
  "routes": [],
  "fallbackInfo": null,
  "geocodingResults": null,
  "warnings": [],
  "error": null
}

This is the hybrid sync/async route creation endpoint. It uses below pattern:

• Fast path (< 3s): Returns 200 with the completed route inline.
• Slow path (> 3s): Returns 202 with status: "processing". Poll GET /v1/routes/{id} or use a webhookUrl to be notified when it completes.

The Idempotency-Key header makes retries safe - if your client times out, just resend with the same key to get the cached response instead of creating a duplicate.

Headers

Idempotency-Key · string

A unique key to ensure idempotent route creation. If a request with the same key was already processed, the cached response is returned. If the same key is reused with a different request body, a 422 error is returned.

Example:

"req_abc123"

Body

application/json

Request body for route computation. Accepts all Google Routes API fields — unsupported fields are silently ignored.

origin · object · required

Origin waypoint (required)

Show child attributes

destination · object · required

Destination waypoint (required)

Show child attributes

intermediates · object[]

Intermediate waypoints (stops or pass-through points)

Show child attributes

travelMode · string · default: DRIVE

Travel mode. Only DRIVE is supported (truck routing).

routingPreference · string · default: TRAFFIC_UNAWARE

Routing preference. Traffic is not currently modeled.

departureTime · string<date-time>

Departure time in ISO 8601 UTC format. Affects school zone detection and time-based routing.

computeAlternativeRoutes · boolean · default: false

When true and no intermediate waypoints, returns up to 3 alternative routes.

routeModifiers · object

Route modifiers (avoid tolls, highways, ferries)

Show child attributes

languageCode · string · default: en-US

Language for navigation instructions

vehicleSpec · object

Vehicle specification for physics enrichment. Defaults to SEMI_TRAILER preset if omitted.

Show child attributes

routingProfile · enum<string> · default: balanced

Routing profile that adjusts enrichment weights

Available options: balanced, fuel_optimal, time_optimal, fatigue_aware

profileOverrides · object

Override individual profile weights (e.g. {"fuelWeight": 1.5})

Show child attributes

webhookUrl · string<uri>

Webhook URL for async route completion notifications. Only used by POST /v1/routes.

Response

200

application/json

Route computed synchronously (fast path). Status is complete with full route data.

A route resource. Used by the /v1/routes endpoint family.

id · string · required

Unique route ID (prefixed with route_)

Example:

"route_01HYX3MPK5XJQJG0NB0PRSDVWC"

object · enum<string> · required

Object type (always route)

Available options: route

status · enum<string> · required

Current status of the route computation.

• processing - route is still being computed (routes array is empty)
• complete - route computation finished (routes array is populated)
• failed - route computation failed (error object is populated)

Available options: processing, complete, failed

createdAt · string<date-time> · required

ISO 8601 UTC timestamp of creation

Example:

"2026-02-28T15:12:32Z"

routes · object[] · required

Computed routes (empty while processing)

Show child attributes

fallbackInfo · object | null

geocodingResults · object | null

warnings · string[]

error · object | null

Error details (populated when status is failed)

Show child attributes