Optimization API

The optimization endpoint takes your unassigned jobs, available drivers, and trucks for a given date and returns optimized assignments with container chaining.

How It Works

You create jobs, drivers, and trucks via the REST API. Then call optimize for a date. The optimizer reads all unassigned jobs for that date, all active drivers and trucks, and produces assignments that minimize miles and maximize container chains.

Jobs

Type (DELIVERY, PICKUP, DUMP_RETURN, SWAP), container size, site location, scheduled date.

Drivers

Name, start time, assigned truck.

Trucks

Number, compatible container sizes.

Async Optimization (Recommended)

The primary endpoint starts an optimization job and returns immediately. Poll for the result.

1. Start the job

POST /api/v1/dispatches/optimize
Content-Type: application/json
Authorization: Bearer <token>

{
  "date": "2026-03-15",
  "optimizationMode": "FULL_DAY"
}

Request Body

Field	Type	Description
date	string	Required. `YYYY-MM-DD` format.
optimizationMode	string	Optional. `FULL_DAY` (default), `NEW_JOB`, or `REBALANCE`.
regionId	string	Optional. Restrict to a service region.
yardId	string	Optional. Restrict to a specific yard.

Returns 202 Accepted:

{
  "data": {
    "jobId": "opt-abc123",
    "status": "PENDING",
    "estimatedDurationSeconds": 5,
    "pollUrl": "/api/v1/dispatches/optimize/opt-abc123"
  }
}

2. Poll for results

GET /api/v1/dispatches/optimize/<jobId>
Authorization: Bearer <token>

Returns the job status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED. When COMPLETED, the result field contains the optimization output.

{
  "data": {
    "jobId": "opt-abc123",
    "status": "COMPLETED",
    "dispatchDate": "2026-03-15",
    "createdAt": "2026-03-15T06:00:00Z",
    "startedAt": "2026-03-15T06:00:01Z",
    "completedAt": "2026-03-15T06:00:02Z",
    "durationMs": 1200,
    "result": { ... }
  }
}

Sync Optimization

For smaller dispatches or when you prefer a blocking call, use the synchronous endpoint. It returns the full result directly (no polling).

POST /api/v1/dispatches/optimize/sync
Content-Type: application/json
Authorization: Bearer <token>

{
  "date": "2026-03-15"
}

Returns 200 OK with the optimization result directly.

Optimization Modes

FULL_DAYDefault

Optimizes all unassigned jobs for the date. Use at the start of the day or for a complete re-plan.

NEW_JOB

Inserts a newly created job into an existing dispatch with minimal disruption.

REBALANCE

Re-distributes remaining jobs across drivers mid-day (e.g., when a driver calls out).

Container Chaining

The optimizer looks for same-size container sequences (e.g., Pickup 20yd → Dump → Deliver 20yd) that let a driver reuse a container without returning to the yard. This is the core value of Klau's optimization — it reduces dead miles and increases the number of jobs a driver can complete in a day.

Prerequisites

Before running an optimization, ensure you have created the following for the target date and company:

At least one Driver (POST /api/v1/drivers)
At least one Truck (POST /api/v1/trucks)
At least one Yard (POST /api/v1/yards) — the depot where drivers start and end
Jobs scheduled for that date (POST /api/v1/jobs) with status UNASSIGNED