OptimizationRequest

The top-level request body accepted by every /optimize/* endpoint. It is divided into 18 logical sections. Only resources and travel are required — every other section has a safe default or is simply omitted.

Units

All time values are seconds (typically seconds-from-midnight or seconds-from-an-arbitrary-origin, consistent across the whole request). All distance values are metres.

Section map

Key	Required?	Purpose
metadata	No	Problem identification and tags
problem	No	Global settings: `num_days`, `timezone`, `max_wait_before_service`
depots	No	Named depots with GPS or matrix index
resources	Yes	Vehicles/crews with capacity, skills, time window
jobs	No*	Service stops with demands, time windows, skills (*omitting jobs is valid but pointless — nothing to solve)
shipments	No	Pickup-delivery pairs
relations	No	Precedence, sequence, same/different route
zones	No	Geographic access restrictions
appointments	No	Pre-scheduled time slots (resource + job + time)
dump_stations	No	Capacity-reset stops (waste handlers)
exclusive_dimensions	No	Incompatible load dimension pairs
locations	No†	GPS catalog for coordinate-based matrix mode (†required when `travel.profile` is set)
travel	Yes	`distance_matrix`/`time_matrix` OR `profile`
objectives	No	min_distance, min_time, min_vehicles, etc.
locks	No	Dynamic replanning: freeze existing routes
seed_solution	No	Initial solution hint
webhooks	No	Completion notification webhooks — accepted but not yet delivered, see the Async guide
options	No	Solver time limit, strategy, metaheuristic
output_options	No	Control what appears in the response

Metadata

Field	Type	Description
problem_id	string	Client-supplied problem identifier; echoed back in the response.
description	string	Human-readable description.
tags	string[]	Arbitrary tags for filtering/logging.

Problem config

Field	Type	Description
num_days	integer	Number of planning days (≥1). Enables multi-day scheduling — each resource is expanded into one virtual vehicle per day. Must live here, not under `options`; misplacing it is silently ignored and the solve runs single-day.
timezone	string	IANA timezone (e.g. `Europe/Amsterdam`). Informational only.
max_wait_before_service	integer	Global maximum waiting time at a stop before service begins (seconds, ≥0). Overridden per-resource or per-job.

Depot

Field	Type	Description
id	string	required Unique depot identifier.
location	Location	required See Location below.
time_window	TimeWindow	Opening hours of the depot.
label	string	Human-readable depot name.

Location

Field	Type	Description
index	integer	Zero-based row/column index in the travel matrices (≥0). Required if no GPS coordinates.
lat	float	Latitude (WGS84). Required if no `index`.
lon	float	Longitude (WGS84). Required if no `index`.
label	string	Human-readable location name.

TimeWindow

Field	Type	Description
start	integer	required Earliest service start time (seconds, ≥0).
end	integer	required Latest service start time (must be ≥ start).

Resource (vehicle / crew)

Field	Type	Description
id	string	required Unique resource identifier.
start_depot_id	string	Depot id where the resource starts. One of `start_depot_id`, `start_location`, or `depot_index` must be provided.
end_depot_id	string	Depot id where the resource ends. Defaults to `start_depot_id`.
start_location / end_location	Location	Explicit start/end locations as an alternative to depot ids.
depot_index	integer	Fallback: matrix index for the start depot.
capacities	object \| integer	Named capacity limits, e.g. `{"waste": 10, "recyclable": 5}`, or a single integer (becomes `{"_default": n}`).
time_window	TimeWindow	Working hours for this resource.
max_travel_time	integer	Maximum total travel time in the route (seconds, ≥0).
max_tasks	integer	Maximum number of jobs in the route (≥0).
max_distance	integer	Maximum total route distance (metres, ≥0).
skills	string[]	Skill tags this resource has.
breaks	Break[]	Scheduled break intervals; see Break below.
max_continuous_driving	integer	Auto-generate a break every N seconds of driving (≥1).
driving_break_duration	integer	Duration of auto-generated driving break (seconds, default 15).
max_continuous_work	integer	Auto-generate a break every N seconds of work (≥1).
work_break_duration	integer	Duration of auto-generated work break (seconds, default 30).
max_wait_before_service	integer	Overrides the global wait cap for this resource (≥0).
available_days	integer[]	Multi-day only: day indices this resource is available on.
active	boolean	If `false`, this resource is excluded from the solve entirely (default `true`).
fixed_cost	integer	Cost charged if the vehicle is used (≥0).
cost_per_km	float	Variable distance cost per kilometre (≥0).
cost_per_hour	float	Variable time cost per hour (≥0).

Break

Field	Type	Description
id	string	Optional break identifier.
time_window	TimeWindow	required Window within which the break must start.
duration	integer	required Duration of the break (seconds, ≥0).

Breaks force a fixed search strategy

When any resource has breaks, the solver requires PATH_CHEAPEST_ARC as the first-solution strategy regardless of what options.first_solution_strategy requests. The adapter applies this override automatically.

Job

Field	Type	Description
id	string	required Unique job identifier.
location / location_index	Location / integer	Job location, or a matrix index shorthand (≥0).
demands	object \| integer	Named capacity demands, e.g. `{"waste": 3}`, or a single integer.
service_time	integer	Time to complete service at the stop (seconds, default 0).
time_windows	TimeWindow[]	Acceptable service time windows.
required_skills	string[]	Skills a resource must have to serve this job.
allowed_resource_ids	string[]	Restrict to specific resources. Empty = all resources.
mandatory	boolean	If `false`, the job may be dropped with a penalty (default `true`).
penalty	integer	Cost paid if the job is dropped (default 100000).
revenue	integer	Revenue gained if served (used by `maximize_served`).
priority	integer	Scheduling priority 1–10 (higher = serve first); multiplies into the penalty under priority-aware objectives.
day	integer	Multi-day only: pin the job to this day index (≥0).
locked	boolean	Dynamic replanning: preserve this job's current assignment.
setup_time	integer	One-time setup cost added before the first visit (seconds).
lifo	boolean	Last-in-first-out ordering constraint.
max_wait_before_service	integer	Overrides the max wait for this specific job (≥0).
departure_time	integer	Seconds-from-midnight at which the assigned vehicle leaves its depot heading for this job. Requires exactly one entry in `allowed_resource_ids`. FG computes the depot→job travel time and derives the exact arrival window automatically (`arrival = departure_time + travel_time`); any manually specified `time_windows` on the same job are replaced.

departure_time validation

departure_time requires exactly one entry in allowed_resource_ids; otherwise the request fails validation with 400 Bad Request.

Shipment (pickup-delivery pair)

Field	Type	Description
id	string	required Unique shipment identifier.
pickup / delivery	ShipmentStep	required Pickup and delivery steps. The solver guarantees the same vehicle does both, pickup before delivery.
mandatory	boolean	May be dropped if `false` (default `true`).
penalty	integer	Drop penalty (default 100000).
allowed_resource_ids	string[]	Restrict to specific resources.
required_skills	string[]	Required skills for serving this shipment.

ShipmentStep

Field	Type	Description
id	string	required Unique step identifier.
location / location_index	Location / integer	Step location.
service_time	integer	Service duration (seconds, default 0).
time_windows	TimeWindow[]	Acceptable service time windows.
demands	object \| integer	Capacity change at this step.

Relation

Field	Type	Description
type	string	required One of the four types below.
job_ids	string[]	required Job ids involved (min 2).
lapse	integer	Required time gap (seconds, ≥0). Only used by `precedence`.

Type	Meaning
`precedence`	Job A served before Job B, with at least `lapse` seconds gap. Different vehicles allowed.
`sequence`	Jobs served in exactly that order, on the same vehicle, with nothing in between.
`same_route`	All listed jobs assigned to the same vehicle.
`different_route`	All listed jobs assigned to different vehicles.

Zone

Field	Type	Description
id	string	required Unique zone identifier.
location_indices	integer[]	required Matrix indices belonging to this zone (min 1).
allowed_resource_ids	string[]	required Resources allowed to serve locations in this zone.

Appointment

Syntactic sugar for pinning a specific job to a specific resource at a specific time. Internally normalized to job-level time_windows and allowed_resource_ids.

Field	Type	Description
resource_id	string	required Resource that must serve this job.
job_id	string	required Job to be served.
time	integer	required Scheduled service start (seconds, ≥0).
tolerance	integer	Allowed deviation from `time` in either direction (seconds, default 0).

DumpStation

Reset a vehicle's capacity when visited — modelled as an optional node with a large negative demand.

Field	Type	Description
id	string	required Unique dump station identifier.
location / location_index	Location / integer	Station location.
service_time	integer	Unload/reload time at the station (seconds, default 0).
resets_capacities	string[]	Which capacity dimensions to reset. Empty = reset all.
max_vehicles	integer	Maximum simultaneous vehicles (≥1, default 1). Values >1 generate virtual copies of the node.

Exclusive dimensions

A list of pairs of capacity-dimension names that cannot both be loaded between dump visits, e.g. [["organic", "recyclable"]]. Before loading one, the truck must have emptied all of the other.

Travel config

Field	Type	Description
distance_matrix	integer[][]	N×N distance matrix (metres, 0-indexed). Required if no GPS profile.
time_matrix	integer[][]	N×N time matrix (seconds, 0-indexed). Required if no GPS profile.
speed_kmh	float	Fixed speed for converting distance to time. Used if only one matrix is provided.
profile	string	Routing profile: `auto`, `truck`, or `bicycle`. Triggers automatic matrix computation from GPS coordinates in a top-level `locations` array.

Objectives config

Field	Type	Description
primary	string	Default `min_distance`. One of the five values below.
fairness_weight	integer	Workload balance coefficient (≥0, default 0).
vehicle_fixed_cost_weight	float	Weight on per-vehicle fixed cost (≥0, default 1.0).

Value	Meaning
`min_distance`	Minimize total route distance (default).
`min_time`	Minimize total route time.
`min_vehicles`	Use as few vehicles as possible.
`maximize_served`	Maximize revenue from served jobs.
`balance_workload`	Minimize workload variance across vehicles.

Solver options

Field	Type	Description
time_limit_seconds	integer	Solver runtime limit (≥1, default 30).
solution_limit	integer	Stop after finding N solutions (≥1, optional).
first_solution_strategy	string	Initial-solution heuristic. Default `PATH_CHEAPEST_ARC`.
local_search_metaheuristic	string	Improvement algorithm. Default `GUIDED_LOCAL_SEARCH`.
num_threads	integer	Parallel search threads (≥1, default 1).
log_search	boolean	Enable verbose solver log (default `false`).

first_solution_strategy	Description
`AUTOMATIC`	The solver chooses the best strategy automatically.
`PATH_CHEAPEST_ARC`	Greedy cheapest-edge insertion; default, and forced when breaks are present.
`PATH_MOST_CONSTRAINED_ARC`	Prioritizes the most-constrained nodes first.
`PARALLEL_CHEAPEST_INSERTION`	Parallel cheapest insertion heuristic.
`LOCAL_CHEAPEST_INSERTION`	Sequential cheapest insertion.
`GLOBAL_CHEAPEST_ARC`	Global minimum-cost arc selection.
`SAVINGS`	Clarke-Wright savings algorithm.
`CHRISTOFIDES`	Christofides approximation algorithm.

local_search_metaheuristic	Description
`AUTOMATIC`	The solver chooses automatically.
`GUIDED_LOCAL_SEARCH`	GLS with penalty-guided neighborhood exploration (default).
`GREEDY_DESCENT`	Classic hill climbing.
`SIMULATED_ANNEALING`	Temperature-based acceptance of worse solutions.
`TABU_SEARCH`	Forbids recently-visited moves.
`GENERIC_TABU_SEARCH`	Tabu search with aspiration criteria.

Locks config

Used for dynamic replanning: preserve some routes while re-optimizing the rest.

Field	Type	Description
routes	LockedRoute[]	List of locked routes.
disabled_resource_ids	string[]	Resources excluded from the re-optimization entirely.

LockedRoute

Field	Type	Description
resource_id	string	required Resource whose route is locked.
job_ids	string[]	required Ordered sequence of locked job ids (min 1).

Output options

Field	Type	Description
include_unserved_reasons	boolean	Include reason codes for unserved jobs (default `true`).
include_violations	boolean	Include constraint violation details (default `true`).
include_diagnostics	boolean	Include solver diagnostics (default `false`).
include_score_breakdown	boolean	Include per-component score (default `true`).
route_geometry	boolean	Include route GeoJSON geometry (default `false`).

Minimal request

{
  "metadata": { "problem_id": "v2-01-basic" },
  "travel": {
    "distance_matrix": [
      [0, 4, 8, 6, 7],
      [4, 0, 5, 3, 6],
      [8, 5, 0, 6, 4],
      [6, 3, 6, 0, 5],
      [7, 6, 4, 5, 0]
    ]
  },
  "resources": [
    { "id": "truck-1", "depot_index": 0 },
    { "id": "truck-2", "depot_index": 0 }
  ],
  "jobs": [
    { "id": "j1", "location_index": 1 },
    { "id": "j2", "location_index": 2 },
    { "id": "j3", "location_index": 3 },
    { "id": "j4", "location_index": 4 }
  ],
  "options": { "time_limit_seconds": 5 }
}

See OptimizationResponse for the full shape of what comes back.