Route Planning for Connected Apps

Send shop or stop locations to Fleetr and receive a suggested visiting order with road directions, distance and driving time. Schoolrun, Dispatchr and other connected apps can use the same API.

Last updated: 20 October 2026.

What the API Calculates

Use POST /api/nav/plan to calculate a route. Supply a starting point, the stops to visit and, optionally, a final destination. If you omit the destination, the route returns to the starting point.

With optimize: true, Fleetr asks the configured routing provider to suggest an efficient stop order while keeping the start and destination fixed. With optimize: false, it calculates directions through the stops in the exact order supplied. This lets your app show the suggested order, let a person change it and request updated directions.

The caller keeps its own plan and any related bookings, school runs or dispatch work. This calculation does not save a route record in Fleetr or create a recorded GPS journey.

Authenticate and Select an Account

Create a suitable account integration token. Send it as a bearer token and use X-Account-ID to select the account. The token must belong to a user with access to that account. Account selection does not grant access to another account.

Use Content-Type: application/json and Accept: application/json. Send account context explicitly from both Schoolrun and Dispatchr; do not rely on the first-account fallback in a multi-account integration.

Request a Suggested Visiting Order

This example uses invented shop identifiers and example coordinates. Replace them with your app's data.

POST /api/nav/plan HTTP/1.1
Host: fleetr.co.ke
Authorization: Bearer YOUR_ACCOUNT_API_TOKEN
X-Account-ID: YOUR_ACCOUNT_ID
Content-Type: application/json
Accept: application/json

{
  "origin": {"lat": -1.2864, "lng": 36.8172},
  "destination": {"lat": -1.2864, "lng": 36.8172},
  "stops": [
    {"id": "shop-a", "label": "Shop A", "lat": -1.2921, "lng": 36.8219},
    {"id": "shop-b", "label": "Shop B", "lat": -1.3000, "lng": 36.8300},
    {"id": "shop-c", "label": "Shop C", "lat": -1.3100, "lng": 36.8400}
  ],
  "optimize": true
}

Send a JSON object of at most 64 KB with no query parameters. Supply 1–25 stops, separate from the origin and destination. Latitude must be between −90 and 90; longitude must be between −180 and 180. Optional stop IDs are unique strings from the calling app. They do not identify Fleetr database records. Labels and IDs are returned to the caller; route calculation uses coordinates.

Use the Returned Order

stopOrder contains zero-based indexes into the submitted stops array. For example, [2, 0, 1] means visit the third submitted shop, then the first, then the second. orderedStops includes each stop's original inputIndex, coordinates and any supplied ID or label.

The response also includes distanceMeters, durationSeconds, decoded route points and turn-by-turn steps. Distance and duration cover the drive from the origin, through the returned stop order, to the destination. Add your own visit, loading or waiting time when scheduling work.

The provider field identifies the calculation source. optimized describes whether optimisation was requested. trafficAware describes whether the calculation requested traffic-aware routing; it is not a guarantee that traffic observations exist for every road.

Recalculate After Someone Changes the Order

Reorder the stops array in your app and submit the same origin and destination with optimize: false. Fleetr preserves that array order and recalculates road directions, distance and driving time. The returned stopOrder is [0, 1, 2, ...] for that request.

Indexes always refer to the current request. Keep your own stop IDs when carrying business data between recalculations.

Choose a Routing Provider

Fleetr supports Google Routes and OSRM for this endpoint. Google requests traffic-aware driving routes and can optimise stop order. OSRM provides road routing and an approximate visiting order using its Trip service. It does not supply a live traffic feed through this API.

The server operator selects the planning provider. Google planning needs the Google Routes API enabled in the server key's Google Cloud project and allowed by that key's API restrictions. An OSRM deployment needs its routing endpoint configured. Client apps never receive the provider's credentials.

This endpoint plans one route. Vehicle capacities, school pickup time windows and allocation across multiple vehicles require a separate fleet-optimisation capability. The returned order is a suggestion; check operational requirements before using it.

Handle Errors and Limits

Calls are limited to 30 requests per minute per authenticated caller. Debounce changes in your app and request a new calculation when the user is ready.

The existing GET /api/nav/route endpoint remains available for its original ordered-waypoint directions contract. See the interactive API reference for exact request and response schemas.