Optimize API Reference

The Optimize API solves multi-vehicle routing problems (VRP). Given a fleet of vehicles and a list of jobs, it assigns jobs to vehicles and orders each route to satisfy all constraints while minimizing cost, distance, or duration.

Endpoint: POST /solver/optimize

---

Overview

A single request can handle:

• Job assignment across multiple vehicles
• Route ordering (minimize distance, duration, or cost)
• Time window constraints
• Vehicle capacity constraints
• Break scheduling
• Skill-based vehicle–job matching

The API automatically detects the problem type. You only need to describe your vehicles, jobs, and what to optimize.

---

Request

Query Parameters

Parameter	Type	Required	Description
apiKey	string	Optional	Your API key
direction	string	Optional	Geometry format: "geocode" or "polyline". If omitted, direction and steps geometry are returned as null.

Request Body

Key	Type	Required	Description
vehicles	array of Vehicle	Yes	Available vehicles
jobs	array of Job	Yes	Tasks to be performed
options	Options	Yes	Optimization settings

---

Vehicle

Describes a vehicle and its constraints.

Key	Type	Required	Description
id	string	Yes	Unique vehicle identifier
start	Location	Optional	Vehicle start location
end	Location	Optional	Vehicle end location (if omitted, route ends at the last visited job)
time_window	["HH:MM:SS", "HH:MM:SS"]	Optional	Vehicle working hours
skills	array of integers	Optional	Skills this vehicle has
breaks	array of Break	Optional	Planned breaks
steps	array of VehicleStep	Optional	Pre-planned route ordering
costs	Costs	Optional	Per-km, per-hour, fixed costs
constraints	VehicleConstraints	Optional	Physical and routing constraints

Notes: - At least one of start or end must be provided. - To request a round trip, set start and end to the same location. - skills from the VROOM model: a vehicle can only serve a job if the vehicle's skills array contains all of the job's required skills.

Costs

Defines the cost model for this vehicle. Used when minimize: "cost".

Key	Type	Description
fixed	integer ≥ 0	Fixed cost for using this vehicle (default: 0)
per_hour	integer ≥ 0	Cost per hour of travel time (default: 3600)
per_task_hour	integer ≥ 0	Cost per hour of task time (setup + service) (default: 0)
per_km	integer ≥ 0	Cost per km of travel (default: 0)

Note: If you set a custom per_hour, it acts as a multiplier on travel time. Providing a custom cost matrix alongside a non-default per_hour is inconsistent and will raise an error.

Vehicle Constraints

Physical and routing restrictions for the vehicle. Also controls routing behavior (e.g., truck routing, hazmat).

Key	Type	Description
vehicleType	string	"car", "van", "truck", "motorcycle", "trailer"
fuelType	string	"diesel", "gasoline", "electric", "hybrid", "lpg"
capacity	number ≥ 0	Load capacity
capacityType	string	Unit: "weight_kg", "weight_ton", "volume_l", "volume_m3", "pallet", "unit", etc.
length	integer 0–30000	Vehicle length (cm)
width	integer 0–5000	Vehicle width (cm)
height	integer 0–5000	Vehicle height (cm)
axle_count	integer 2–255	Total axles
trailer_axle_count	integer ≥ 1	Trailer axles
trailer_count	integer 0–255	Number of trailers
tires_count	integer 0–255	Total tires
hazardousGoods	array of strings	Hazardous materials (e.g. "flammable", "explosive")
max_distance	integer > 0	Maximum route distance (meters)
max_travel_time	integer ≥ 0	Maximum travel time (seconds)
max_tasks	integer ≥ 0	Maximum number of tasks per route
manufactureYear	integer	Vehicle manufacture year
brand	string	Vehicle brand
model	string	Vehicle model

---

Break

A scheduled break for the vehicle.

Key	Type	Required	Description
id	integer	Yes	Unique break identifier
time_windows	array of ["HH:MM:SS","HH:MM:SS"]	Optional	Valid time slots for the break to start
service	integer ≥ 0	Optional	Break duration in seconds (default: 0)
description	string	Optional	Human-readable label
max_load	array of integers	Optional	Maximum vehicle load during this break

Each break must have a unique id within the same vehicle.

---

Vehicle Step

Forces a specific ordering or timing for a vehicle route. Useful in "plan mode" to fix the sequence of tasks.

Key	Type	Required	Description
type	string	Yes	"start", "job", "pickup", "delivery", "break", or "end"
id	string	Optional	ID of the task at this step (required for job, pickup, delivery, break)
service_at	string	Optional	Hard constraint: service must start exactly at this time
service_after	string	Optional	Hard constraint: service must start at or after this time
service_before	string	Optional	Hard constraint: service must start at or before this time

---

Job

A task to be performed by a vehicle. Each job has a pickup location, a delivery location, and optional constraints.

Key	Type	Required	Description
id	string	Yes	Unique job identifier
start	JobLocation	Yes	Pickup location
end	JobLocation	Yes	Delivery location
amount	integer ≥ 1	Optional	Quantity (demand) for this job
amount_type	string	Optional	Unit of quantity (same values as capacityType)
priority	integer 0–100	Optional	Job priority — higher values are preferred when not all jobs can be served (default: 0)
skills	array of integers	Optional	Skills required to perform this job

Skills logic: A job with skills: [1, 2] can only be assigned to a vehicle that includes both 1 and 2 in its skills array.

---

Location

Used in vehicle.start / vehicle.end.

Key	Type	Description
latitude	number	Latitude
longitude	number	Longitude
address	string	Street address
city	string	City
district	string	District
country	string	Country
postalCode	string	Postal code
timezone	string	Timezone
locationId	string	Location identifier

---

Job Location

Used in job.start and job.end. Extends Location with service timing fields.

All Location keys, plus:

Key	Type	Description
setup	integer ≥ 0	Setup duration before service begins (seconds). Not re-applied for consecutive tasks at the same location.
service	integer ≥ 0	Service duration at this location (seconds)
setup_per_type	object	Override setup duration per vehicle type: { "truck": 120 }
service_per_type	object	Override service duration per vehicle type: { "van": 60 }
time_windows	array of ["HH:MM:SS","HH:MM:SS"]	Valid time slots for service to start. Multiple windows can be provided.

Time windows: The actual service start must fall within one of the provided windows. If no time_windows is set, there is no timing constraint for this location.

---

Options

Key	Type	Required	Description
minimize	string	Optional	Optimization objective: "distance", "duration", or "cost"
timeout	integer	Optional	Maximum solver time in seconds
avoid_tolls	boolean	Optional	Avoid toll roads (default: false)
avoid_zones	array of coordinate polygons	Optional	Geographic areas to avoid

---

Response

Top-level

Key	Type	Description
summary	Summary	Global solution summary
unassigned	array of Job	Jobs that could not be assigned
routes	array of Route	One route per vehicle used

Summary

Key	Type	Description
cost	number	Total solution cost
routes	integer	Number of routes used
unassigned	integer	Number of unassigned jobs
setup	integer	Total setup time (seconds)
service	integer	Total service time (seconds)
duration	integer	Total travel time (seconds)
distance	integer	Total distance (meters)
waiting_time	integer	Total waiting time (seconds)
priority	integer	Total priority score of assigned jobs

Route

Key	Type	Description
vehicle	string	Vehicle ID
cost	number	Route cost
duration	integer	Total travel time (seconds)
distance	integer	Total distance (meters)
setup	integer	Total setup time (seconds)
service	integer	Total service time (seconds)
waiting_time	integer	Total waiting time (seconds)
priority	integer	Total priority of jobs on this route
toll_cost	number	Total toll cost for this route
steps	array of Step	Ordered steps
geometry	string	Encoded polyline geometry (if direction="polyline")

Step

Each stop in a route — including start, end, jobs, and breaks.

Key	Type	Description
type	string	"start", "job", "pickup", "delivery", "break", "end"
id	string	Task ID (present for job, pickup, delivery, break)
arrival	integer	Estimated time of arrival at this step (seconds from route start)
duration	integer	Cumulative travel time at this step (seconds)
distance	integer	Cumulative distance at this step (meters)
setup	integer	Setup duration at this step (seconds)
service	integer	Service duration at this step (seconds)
waiting_time	integer	Waiting time at this step (seconds)
load	array of integers	Vehicle load after this step (with capacity constraints)
location	[lat, lon]	Step coordinates
violations	array of Violation	Constraint violations at this step

Violation

Reported when a constraint cannot be met (most relevant in plan mode).

Key	Type	Description
cause	string	Reason for violation (see below)
duration	integer	Earliness or lateness in seconds (for lead_time / delay)

Violation causes:

Cause	Description
"delay"	Service started after the time window ended
"lead_time"	Service started before the time window began
"load"	Vehicle load exceeded capacity
"max_tasks"	Route has more tasks than max_tasks
"skills"	Vehicle lacks required skills for a task
"precedence"	Shipment pickup/delivery order violated
"missing_break"	A vehicle break was omitted from its custom route
"max_travel_time"	Route travel time exceeds max_travel_time
"max_distance"	Route distance exceeds max_distance
"max_load"	Vehicle load during a break exceeds max_load

---

Examples

Request

{
  "vehicles": [
    {
      "id": "vehicle_1",
      "start": { "latitude": 41.0082, "longitude": 28.9784 },
      "end":   { "latitude": 41.0082, "longitude": 28.9784 },
      "time_window": ["08:00:00", "18:00:00"],
      "skills": [1, 2],
      "costs": {
        "per_km": 5,
        "per_hour": 100
      },
      "constraints": {
        "vehicleType": "van",
        "capacity": 100,
        "capacityType": "weight_kg"
      }
    }
  ],
  "jobs": [
    {
      "id": "job_1",
      "start": {
        "latitude": 41.0100,
        "longitude": 28.9800,
        "service": 300,
        "time_windows": [["09:00:00", "12:00:00"]]
      },
      "end": {
        "latitude": 41.0150,
        "longitude": 28.9850
      },
      "amount": 20,
      "amount_type": "weight_kg",
      "priority": 50,
      "skills": [1]
    }
  ],
  "options": {
    "minimize": "cost",
    "timeout": 30
  }
}

Python

import requests

API_BASE_URL = "https://api.flio.ai"
API_KEY = "YOUR-API-KEY"

payload = {
    "vehicles": [
        {
            "id": "vehicle_1",
            "start": {"latitude": 41.0082, "longitude": 28.9784},
            "end":   {"latitude": 41.0082, "longitude": 28.9784},
            "time_window": ["08:00:00", "18:00:00"],
            "constraints": {
                "vehicleType": "van",
                "capacity": 100,
                "capacityType": "weight_kg"
            }
        }
    ],
    "jobs": [
        {
            "id": "job_1",
            "start": {"latitude": 41.0100, "longitude": 28.9800},
            "end":   {"latitude": 41.0150, "longitude": 28.9850},
            "amount": 20,
            "priority": 50
        }
    ],
    "options": {
        "minimize": "cost"
    }
}

response = requests.post(
    f"{API_BASE_URL}/solver/optimize?apiKey={API_KEY}",
    json=payload
)
result = response.json()

print(f"Cost: {result['summary']['cost']}")
print(f"Routes: {result['summary']['routes']}")
print(f"Unassigned: {result['summary']['unassigned']}")

cURL

curl -X POST "https://api.flio.ai/solver/optimize?apiKey=YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicles": [...],
    "jobs": [...],
    "options": { "minimize": "cost" }
  }'

---

Optimize API reference — Flio.ai

Next Steps

• Optimize Overview
• Optimize Features
• Optimize Examples