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	Yes	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 (default: empty object)

Notes: - 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.

VehicleConstraints¶

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 (default: `0`)
`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

VehicleStep¶

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 (job locations only)
`time_window_end`	string (time, HH:MM:SS)	End of available time window (job locations only)
`location_id`	string	Location identifier

JobLocation¶

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 }`

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
      },
      "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
)
response.raise_for_status()
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

Optimize API Reference¶

Overview¶

Request¶

Query Parameters¶

Request Body¶

Vehicle¶

VehicleConstraints¶

Break¶

VehicleStep¶

Job¶

Location¶

JobLocation¶

Options¶

Response¶

Top-level¶

Summary¶

Route¶

Step¶

Unassigned¶

Action¶

Examples¶

Request¶

Python¶

cURL¶

Next Steps¶