# 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: . ## 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](/docs/api-integration#account-integration-tokens). 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. ```http 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. | Status | Meaning | What the caller should do | |---|---|---| | 401 | Authentication missing or invalid | Check the integration token | | 403 | Account context or account access is unavailable | Check the token's account membership, role and X-Account-ID | | 422 | Invalid coordinates, stop list or request fields | Correct the request; do not retry unchanged input | | 429 | Rate limit exceeded | Wait before retrying | | 502 | The provider failed or returned an unusable route | Retry later; do not treat the failure as zero distance | | 503 | Planning is not configured for a supported provider | Contact the Fleetr server operator | The existing **`GET /api/nav/route`** endpoint remains available for its original ordered-waypoint directions contract. See the [interactive API reference](https://fleetr.co.ke/api/docs) for exact request and response schemas.