Plan routes for a fleet
POST/v2/route/plan
Paid API plans only (basic, pro, enterprise). Other keys get
403 PLAN_UPGRADE_REQUIRED. To see it working first, try the free
delivery planner at maps.afrihex.com/dispatch,
which is built on this endpoint.
Call this from your server, not the browser. A request sent from a web page or a shipped app exposes your API key to anyone who looks. Have your dashboard call your backend, and your backend call AfriHex. See Authentication.
Assigns stops to a fleet of vehicles and orders each vehicle's stops.
It handles several vehicles with different modes, capacities, skills,
shifts and breaks, plus single-stop jobs and pickup→delivery
shipments with time windows and priorities. Use
/v2/route/optimized to order one vehicle's stops.
Travel times come from AfriHex road data (Valhalla) and are scaled by
the Ghana traffic model for the period at start_at, so a plan that
starts at 07:30 in Accra allows for the morning rush. Set
options.traffic: false for free-flow times.
Every location takes any AfriHex location form: a GhanaPostGPS
gps_code, a point, a plus_code, a hex or a profile_slug.
Stops that cannot be served are returned in unassigned with a
reason. Stops that no vehicle could ever serve (unreachable by road,
a skill no vehicle has, or larger than every vehicle) are reported
without being planned. Times in the response are RFC 3339.
Limits per request: 50 distinct locations, 20 vehicles, 3 modes.
Travel times are planning estimates. Get turn-by-turn directions for a
planned route from POST /v2/route with its stops as waypoints.
Required fields
Always required:
| Field | Rule |
|---|---|
vehicles | At least one vehicle. |
vehicles[].id | Unique across all vehicles, jobs and shipments. |
vehicles[].start or vehicles[].end | At least one of them. Give both (the same place) for a round trip; without end the route finishes at its last stop. |
jobs or shipments | At least one job or shipment between them. |
jobs[].id, jobs[].location | Every job needs both. |
shipments[].id, .pickup.location, .delivery.location | Every shipment needs all three. |
Required only when you use a feature:
| If you send… | …you must also send |
|---|---|
any delivery, pickup or amount | capacity on every vehicle, with the same number of values as every amount (e.g. all [n], or all [parcels, kg]) |
a time window (shift, breaks[].window, time_windows[]) | both start and end, no earlier than start_at and within 7 days of it |
breaks[] | duration_s (positive) |
Everything else is optional: start_at (default now), mode (default
driving), skills, max_stops, max_trips, reload_s, cost,
service_s, priority,
options.
A location (start, end, location) is a RouteEndpoint: give
exactly one of point, gps_code (GhanaPostGPS), plus_code, hex
or profile_slug.
Missing or invalid fields return 400 VALIDATION_ERROR naming the
field, for example vehicles[0]: give a start, an end, or both or
vehicles[0]: capacity is required when jobs or shipments carry amounts.
Capacity and load
capacity is what a vehicle can carry; delivery, pickup and
amount are what each stop needs. The plan never puts more on a
vehicle than its capacity at any point on the route.
| Field | On | Meaning |
|---|---|---|
capacity: [n] | vehicle | Most it can hold at once. |
delivery: [n] | job | Dropped at this stop. It is on board from the vehicle's start. |
pickup: [n] | job | Collected at this stop. It stays on board to the vehicle's end. |
amount: [n] | shipment | Collected at pickup, dropped at delivery. |
Each step in the response has load: what is on board after that
step. A van that starts with 6 parcels and makes three drops of 1, 2
and 3 reads [6], [5], [3], [0]; a shipment picked up on the
way adds to it until it is delivered.
Units are yours. Use parcels, crates, kilograms or litres. To track several at once, give more values, in the same order everywhere:
"capacity": [20, 500]
"delivery": [2, 35]
reads as "holds 20 parcels and 500 kg; this stop takes 2 parcels weighing 35 kg".
Two rules: once any job or shipment has an amount, every vehicle needs
a capacity; and every capacity and amount must have the same number
of values. A single job or shipment larger than every vehicle is not
an error: it is returned in unassigned with the reason "larger than
every vehicle's capacity". Leave all amounts out to plan without load
limits.
Request
Responses
- 200
- 400
- 403
- 422
- 503
The plan
Invalid body or constraints (INVALID_BODY, VALIDATION_ERROR)
Your API key is not on a paid API plan (PLAN_UPGRADE_REQUIRED)
The solver rejected the problem (INVALID_INPUT)
Route planning temporarily unavailable