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
api_key	string	Optional	Your API key

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 (default: ["00:00:00", "23:59:59"])
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
constraints	VehicleConstraints	Optional	Physical, routing, and cost 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.

Vehicle Constraints

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

Key	Type	Description
capacity	number >= 0	Load capacity
capacity_type	string	Unit: "weight_kg", "weight_ton", "volume_l", "volume_m3", "length", "area", "pallet", "unit"
vehicle_type	string	"truck", "van", "car", "motorcycle", "trailer"
fuel_type	string	"diesel", "gasoline", "electric", "hybrid", "lpg"
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 (default: 0)
tires_count	integer 0-255	Total tires
hazardous_goods	array of strings	Hazardous materials: "explosive", "gas", "flammable", "combustible", "organic", "poison", "radioactive", "corrosive", "poisonousInhalation", "harmfulToWater", "other"
manufacture_year	integer	Vehicle manufacture year
brand	string	Vehicle brand
model	string	Vehicle model
type	string	Vehicle type description
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
per_km	integer >= 0	Cost per km of travel (default: 1000)
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)
fixed	integer >= 0	Fixed cost for using this vehicle (default: 0)

Note: Cost fields (fixed, per_hour, per_task_hour, per_km) are used when minimize: "cost". If you set a custom per_hour, it acts as a multiplier on travel time.

---

Break

A scheduled break for the vehicle.

Key	Type	Required	Description
time_windows	array of ["HH:MM:SS","HH:MM:SS"]	Optional	Valid time slots for the break to start (default: [["00:00:00","23:59:59"]])
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

---

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 capacity_type)
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 and in response step locations.

Key	Type	Description
name	string	Location name
address	string	Street address
city	string	City
district	string	District
country	string	Country
postal_code	string	Postal code
timezone	string	Timezone
latitude	number (-90 to 90)	Latitude
longitude	number (-180 to 180)	Longitude
time_window_start	string (time, HH:MM:SS)	Start of available time window
time_window_end	string (time, HH:MM:SS)	End of available time window
location_id	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: Use time_window_start and time_window_end on the job location to define when service can begin. If not set, there is no timing constraint for this location.

---

Options

Key	Type	Required	Description
minimize	string	Optional	Optimization objective: "distance", "duration", or "cost" (default: "distance")
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 (array of arrays of [lat, lng] pairs)
direction	string	Optional	Geometry format for per-step direction data: "geocode" or "polyline" (default: "polyline"). When null, direction data is not returned.
action	boolean	Optional	When true, route sections include turn-by-turn maneuver actions (default: true)
language	string	Optional	Language for maneuver instructions: "tr-TR" or "en-US" (default: "tr-TR")

---

Response

Top-level

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

Summary

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

Route

Key	Type	Required	Description
vehicle	string	Yes	Vehicle ID
cost	number	Yes	Route cost
amount	integer	Yes	Total amount of jobs on this route
steps	array of Step	Yes	Ordered steps
duration	integer	Optional	Total travel time (seconds)
distance	integer	Optional	Total distance (meters)
setup	integer	Optional	Total setup time (seconds)
service	integer	Optional	Total service time (seconds)
waiting_time	integer	Optional	Total waiting time (seconds)
priority	integer	Optional	Total priority of jobs on this route
actions	array of Action	Optional	Turn-by-turn maneuver actions (if action: true)
toll_cost	number	Optional	Total toll cost for this route
direction	string or array	Optional	Route geometry -- encoded polyline string or coordinate array depending on direction option

Step

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

Key	Type	Required	Description
type	string	Yes	"start", "job", "pickup", "delivery", "break", "end"
load	integer	Yes	Vehicle load after this step
duration	integer	Yes	Cumulative travel time at this step (seconds)
distance	integer	Yes	Cumulative distance at this step (meters)
location	Location	Yes	Step location
id	string	Optional	Task ID (present for job, pickup, delivery, break)
setup	integer	Optional	Setup duration at this step (seconds)
service	integer	Optional	Service duration at this step (seconds)
waiting_time	integer	Optional	Waiting time at this step (seconds)
arrival	integer	Optional	Estimated time of arrival at this step (seconds from route start)

Unassigned

Jobs that could not be assigned to any vehicle.

Key	Type	Required	Description
id	string	Yes	Job identifier
start	Location	Yes	Pickup location
end	Location	Yes	Delivery location
amount	integer	Optional	Job quantity
amount_type	string	Optional	Unit of quantity (CapacityType)
priority	integer	Optional	Job priority (0-100)
skills	array of integers	Optional	Required skills

Action

Turn-by-turn maneuver action for route navigation.

Key	Type	Description
action	string	Maneuver action type
direction	string	Maneuver direction
severity	string	Maneuver severity
instruction	string	Human-readable instruction
offset	integer	Offset in the direction geometry
duration	integer	Duration of this maneuver segment (seconds)
length	integer	Length of this maneuver segment (meters)

---

Examples

Request

{
  "vehicles": [
    {
      "id": "vehicle_1",
      "start": {
        "latitude": 41.0082,
        "longitude": 28.9784,
        "time_window_start": "08:00:00",
        "time_window_end": "18:00:00"
      },
      "end": {
        "latitude": 41.0082,
        "longitude": 28.9784
      },
      "time_window": ["08:00:00", "18:00:00"],
      "skills": [1, 2],
      "constraints": {
        "vehicle_type": "van",
        "fuel_type": "diesel",
        "capacity": 100,
        "capacity_type": "weight_kg",
        "per_km": 1000,
        "per_hour": 3600
      }
    }
  ],
  "jobs": [
    {
      "id": "job_1",
      "start": {
        "latitude": 41.0100,
        "longitude": 28.9800,
        "service": 300,
        "time_window_start": "09:00:00",
        "time_window_end": "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,
    "avoid_tolls": false,
    "direction": "polyline",
    "action": true,
    "language": "tr-TR"
  }
}

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": {
                "vehicle_type": "van",
                "fuel_type": "diesel",
                "capacity": 100,
                "capacity_type": "weight_kg",
                "per_km": 1000,
                "per_hour": 3600
            }
        }
    ],
    "jobs": [
        {
            "id": "job_1",
            "start": {
                "latitude": 41.0100,
                "longitude": 28.9800,
                "time_window_start": "09:00:00",
                "time_window_end": "12:00:00",
                "service": 300
            },
            "end": {"latitude": 41.0150, "longitude": 28.9850},
            "amount": 20,
            "amount_type": "weight_kg",
            "priority": 50
        }
    ],
    "options": {
        "minimize": "cost",
        "direction": "polyline",
        "action": True,
        "language": "tr-TR"
    }
}

response = requests.post(
    f"{API_BASE_URL}/solver/optimize?api_key={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?api_key=YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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": {
          "vehicle_type": "van",
          "capacity": 100,
          "capacity_type": "weight_kg"
        }
      }
    ],
    "jobs": [
      {
        "id": "job_1",
        "start": {
          "latitude": 41.0100,
          "longitude": 28.9800,
          "time_window_start": "09:00:00",
          "time_window_end": "12:00:00",
          "service": 300
        },
        "end": {"latitude": 41.0150, "longitude": 28.9850},
        "amount": 20,
        "amount_type": "weight_kg",
        "priority": 50
      }
    ],
    "options": {"minimize": "cost", "direction": "polyline", "action": true}
  }'

---

Optimize API reference -- Flio.ai

Next Steps

• Optimize Overview
• Optimize Features
• Optimize Examples