Optimizations

Create an optimization from JSON, follow it to completion, then read routes or download driver-ready files.

Method	Path	Purpose
POST	/v1/optimizations	Create (202). Idempotency-Key required
GET	/v1/optimizations	List, newest first (page, page_size)
GET	/v1/optimizations/{id}	Status and progress
GET	/v1/optimizations/{id}/result	Routes, KPIs, unassigned (include_path=true for polylines)
POST	/v1/optimizations/{id}/cancel	Cancel a queued or running optimization
POST	/v1/optimizations/{id}/exports	Excel or CSV export with a signed link

Create: request body

Field	Type	Notes
depot	object	Required. address, or latitude and longitude. Optional label.
orders	array	Required, 1 to 500. Unique id per order.
vehicles	array	Individual vehicles: id, capacity, optional driver, shift_start, shift_end, fixed_cost. Use this or fleet.
fleet	object	N identical vehicles: count (1-100), capacity, shift_start, shift_end, fixed_cost. Use this or vehicles.
name	string	Optional label shown in the portal.
options.strategy	string	optimized (default) or baseline: your file order, for comparison.
options.objective	string	distance (default) or duration.
options.solver_seconds	integer	1 to 60. More time can improve large problems.

Order fields

Field	Notes
id	Your reference, returned in results. Required.
address, city, region, postal_code, country	Give an address, or coordinates. Postal code improves geocoding.
latitude, longitude	Skip geocoding when you already have coordinates.
demand	Load units, same unit as vehicle capacity. Default 1.
service_minutes	Time spent at the stop. Default 5.
time_window_start, time_window_end	HH:MM, 24-hour. Arrival must fall inside the window.
customer, phone, notes	Shown on driver exports. Not required.

Times are local to the depot and expressed as HH:MM. Unknown fields are rejected, so typos are caught instead of ignored.

Status values

queued, running: still working. progress is 0 to 100 and stage names the step (geocoding, matrix, optimizing, storing).
completed: the result is ready.
failed: see error_code and error_message. Fix the cause and create a new optimization.
cancelled: you cancelled it.

Result

GET /v1/optimizations/{id}/result (abridged)

{
  "id": "0d1f0c3e-…",
  "status": "completed",
  "strategy": "optimized",
  "kpis": {
    "orders_total": 3, "orders_assigned": 3, "orders_unassigned": 0,
    "vehicles_available": 2, "vehicles_used": 1,
    "distance_m": 14320, "drive_seconds": 1860, "route_seconds": 3540,
    "late_stops": 0, "avg_utilization": 0.65,
    "per_vehicle": [{ "vehicle_ref": "van-1", "stops": 3, "distance_m": 14320, "load": 39, "capacity": 60 }]
  },
  "routes": [{
    "vehicle_ref": "van-1", "driver_name": "Sam",
    "depart_s": 28800, "return_s": 32340, "distance_m": 14320, "load": 39, "capacity": 60,
    "stops": [{
      "seq": 1, "order_ref": "SO-1001", "address": "255 Bremner Blvd, Toronto, ON",
      "latitude": 43.6416, "longitude": -79.3874,
      "arrival_s": 29400, "start_s": 32400, "depart_s": 33000, "wait_s": 3000, "late_s": 0,
      "leg_distance_m": 2100, "leg_travel_s": 600
    }]
  }],
  "unassigned": [],
  "warnings": []
}

All *_s fields are seconds since midnight (28800 = 08:00). Distances are metres.
stops are in driving order (seq). arrival_s is when the vehicle arrives; start_s is when service begins after any wait.
unassigned lists orders that could not be planned, each with a reason (for example geocode_failed, too_large, window_unreachable) and a message you can show.

Exports for drivers

curl -X POST https://ai-route-optimization.com/v1/optimizations/$ID/exports \
  -H "Authorization: Bearer $AIRO_API_KEY" -H "Content-Type: application/json" \
  -d '{"format": "xlsx", "include_driver_instructions": true}'

The response contains download_url and expires_at. Links are signed and short-lived: request a new export (same arguments return the same file) when one expires.

Idempotency

Send a unique Idempotency-Key (8 to 128 characters) per business operation, for example your dispatch run id.
Retrying with the same key and payload returns the same optimization. It does not run or bill again.
The same key with a different payload is rejected: use a new key for a new plan.

Join the waitlist for API access