ShortPath Routing API

API Reference

Send us your stops, get back the fastest route. The ShortPath Routing API is a single, well-behaved REST endpoint — authenticate with a bearer token, POST your deliveries as coordinates or addresses, and receive an optimized stop sequence with ETAs.

v1 REST · JSON Bearer auth

Introduction

The Routing API exposes the ShortPath optimization engine to your own stack. It is the Routing API plan, billed per depot: each subscription is one API key for one depot, with a monthly allowance of route optimizations per depot. Need more locations? Add a depot, add a key. All requests and responses are JSON over HTTPS.

Prefer to keep everything in-house? The same engine is available self-hosted as On-Premise ShortPath Routing — a flat monthly license with unlimited optimizations.

Authentication

Authenticate every request with your secret API key, sent as a bearer token in the Authorization header. You can find and rotate your keys in your dashboard. Keep secret keys server-side — never expose them in a browser or mobile app.

HTTP header

Authorization: Bearer sk_live_3f9a1c4b8e7d6a2f0b5c9d1e

A request without a valid bearer token returns 401 Unauthorized.

Base URL

All endpoints are relative to:

Base URL

https://api.shortpath.llc/v1

Optimize a route

POST /v1/routes/optimize

Send a depot (the start/end point) and a list of deliveries. Each delivery can be given as coordinates (lat / lng) or as a free-form address — you can even mix both in the same request.

Body parameters

Field	Type	Description
depot	object	Start location. `{ lat, lng }` or `{ address }`.
deliveries	array	The stops to visit. Each item needs `lat`+`lng` or an `address`.
deliveries[].id	string	Optional. Your own reference (echoed back in the response).
deliveries[].time_window	object	Optional. `{ from, to }` in 24h `HH:MM`.
round_trip	boolean	Optional. Return to the depot after the last stop. Defaults to `true`.

Example request — by address

cURL

curl https://api.shortpath.llc/v1/routes/optimize \
  -H "Authorization: Bearer sk_live_3f9a1c4b8e7d6a2f0b5c9d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "depot": { "address": "1200 Logistics Way, Sheridan, WY 82801" },
    "round_trip": true,
    "deliveries": [
      { "id": "ORD-1001", "address": "742 Evergreen Terrace, Sheridan, WY" },
      { "id": "ORD-1002", "address": "55 Coffeen Ave, Sheridan, WY 82801" },
      { "id": "ORD-1003", "address": "1401 N Main St, Sheridan, WY 82801" }
    ]
  }'

Example request — by lat / long

cURL

curl https://api.shortpath.llc/v1/routes/optimize \
  -H "Authorization: Bearer sk_live_3f9a1c4b8e7d6a2f0b5c9d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "depot": { "lat": 44.7972, "lng": -106.9562 },
    "deliveries": [
      { "id": "ORD-1001", "lat": 44.8021, "lng": -106.9481 },
      { "id": "ORD-1002", "lat": 44.7888, "lng": -106.9210,
        "time_window": { "from": "09:00", "to": "12:00" } },
      { "id": "ORD-1003", "lat": 44.8155, "lng": -106.9637 }
    ]
  }'

The response

A 200 OK returns the optimized route: the stops re-ordered for the shortest feasible path, each with a sequence number, resolved coordinates and an ETA, plus a summary and an encoded polyline you can draw on a map.

200 OK · application/json

{
  "route_id": "rt_8s2k4d9f1a",
  "status": "optimized",
  "summary": {
    "stops": 3,
    "distance_meters": 18420,
    "distance_miles": 11.45,
    "duration_seconds": 2760
  },
  "stops": [
    {
      "sequence": 1,
      "id": "ORD-1002",
      "lat": 44.7888,
      "lng": -106.9210,
      "eta": "2026-06-04T09:12:00Z",
      "distance_from_prev_meters": 5200
    },
    {
      "sequence": 2,
      "id": "ORD-1001",
      "lat": 44.8021,
      "lng": -106.9481,
      "eta": "2026-06-04T09:34:00Z",
      "distance_from_prev_meters": 6100
    },
    {
      "sequence": 3,
      "id": "ORD-1003",
      "lat": 44.8155,
      "lng": -106.9637,
      "eta": "2026-06-04T10:05:00Z",
      "distance_from_prev_meters": 7120
    }
  ],
  "geometry": "ku{nF~ps|U_pR_ulL..."
}

Response fields

Field	Description
route_id	Unique id for this optimization. Use it to retrieve the route later.
summary	Totals: stop count, distance (meters & miles) and estimated drive time.
stops[]	The optimized order. `sequence` is the visit order; `id` is echoed from your request.
stops[].eta	Estimated arrival time (ISO‑8601, UTC).
geometry	Encoded polyline of the full route for drawing on a map.

Retrieve a route

GET /v1/routes/{route_id}

Fetch a previously optimized route by its route_id. Returns the same shape as the optimize response.

cURL

curl https://api.shortpath.llc/v1/routes/rt_8s2k4d9f1a \
  -H "Authorization: Bearer sk_live_3f9a1c4b8e7d6a2f0b5c9d1e"

Errors

Errors use standard HTTP status codes and a consistent JSON body.

401

authentication_error

Missing or invalid bearer token.

422

validation_error

A delivery is missing both coordinates and an address, or a field is malformed.

429

rate_limit_exceeded

Monthly optimization allowance reached for your plan.

422 Unprocessable Entity

{
  "error": {
    "type": "validation_error",
    "message": "Each delivery must include either lat/lng or an address.",
    "field": "deliveries[2]"
  }
}

Rate limits

The Routing API plan includes unlimited API calls and a monthly allowance of route optimizations — 10,000 per depot. Each successful POST /v1/routes/optimize consumes one optimization. Remaining quota is returned on every response:

Response headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9974
X-RateLimit-Reset: 1751328000

Need unlimited optimizations, live tracking and a branded driver app? Upgrade to the Complete Delivery Platform.

Ready to start routing?

Create an account, grab your API key, and send your first batch of stops.

Get your API key