FieldGenius API

FieldGenius API (FG-API) is a REST API for solving Vehicle Routing Problems (VRP). Send a JSON description of your fleet and jobs, and get back optimized routes.

What is a VRP?

A Vehicle Routing Problem asks: given a fleet of vehicles starting from one or more depots and a list of jobs (stops) that each need a visit, what is the best way to assign jobs to vehicles and order each vehicle's stops? "Best" usually means least total distance or time, while respecting constraints like time windows, vehicle capacity, and driver skills.

What it does

FG-API is a REST service for solving Vehicle Routing Problems. Clients POST a JSON OptimizationRequest describing resources (vehicles or crews), jobs, time windows, capacities, and other constraints. The API computes travel matrices if needed, solves the routing problem, and returns an OptimizationResponse with full routes, timing, load snapshots, and a score breakdown.

The solve pipeline

Every request passes through the same stages:

Validate - request shape, referential integrity, time window ordering.
Compute travel matrices - the API computes distance/time matrices from GPS coordinates when no matrix is supplied (optional; skip this by sending matrices directly).
Normalize - symbolic IDs (job/resource/depot strings) are converted to integer indices for the solver.
Solve - the solver searches for a feasible, low-cost assignment of jobs to vehicle routes.
Extract routes - the raw solver assignment is converted into a typed list of activities per vehicle.
Score - distance, time, fairness, and penalty metrics are computed and returned alongside the routes.

Key capabilities

Time windows

Hard or soft (penalty-based) time windows per job, with early and late penalties.

Multi-capacity vehicles

Named capacity dimensions (e.g. weight, volume, waste type) per vehicle and job.

Skills & proficiency

Binary skill matching plus proficiency levels and per-skill service-time multipliers.

Pickup & delivery

Shipment pairs with linked pickup/delivery steps and capacity tracking.

Multi-day planning

Expand a fleet across several planning days with per-resource availability.

Live replanning

Re-optimize mid-day from a vehicle's current position, with completed/cancelled jobs and urgent insertions.

Mixed fleet

Per-vehicle-type travel matrices (auto, truck, bicycle).

Recurring jobs

A stateless-optimizer-preserving layer for weekly recurring patterns with free/fix/pin-after-first knobs.

Infeasibility diagnostics

A 3-stage diagnostic pipeline explains exactly why jobs were dropped.

Auto-optimizer

Automatically configures solver strategy and phases based on problem signals when no explicit options are sent.

Traffic-aware segments

Multi-pass solving across time-of-day traffic bands with a configurable speed-factor curve.

Dual solver engines

A full-featured default engine, or an alternative engine that's faster on large wide-time-window problems.

Quick example

A minimal request: one truck, two jobs, an explicit distance matrix.

curl -X POST https://api.fieldgenius.be/api/v1/optimize/sync \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "problem_id": "quickstart-01" },
    "travel": {
      "distance_matrix": [[0, 4, 8], [4, 0, 5], [8, 5, 0]]
    },
    "resources": [
      { "id": "truck-1", "depot_index": 0 }
    ],
    "jobs": [
      { "id": "job-amsterdam-01", "location_index": 1 },
      { "id": "job-rotterdam-02", "location_index": 2 }
    ],
    "options": { "time_limit_seconds": 5 }
  }'

import httpx

payload = {
    "metadata": {"problem_id": "quickstart-01"},
    "travel": {
        "distance_matrix": [[0, 4, 8], [4, 0, 5], [8, 5, 0]],
    },
    "resources": [{"id": "truck-1", "depot_index": 0}],
    "jobs": [
        {"id": "job-amsterdam-01", "location_index": 1},
        {"id": "job-rotterdam-02", "location_index": 2},
    ],
    "options": {"time_limit_seconds": 5},
}

response = httpx.post(
    "https://api.fieldgenius.be/api/v1/optimize/sync",
    json=payload,
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result["status"], result["score"]["total"])

Where to go next

Next steps

Getting Started - install, authenticate, and run your first solve in 5 minutes.
User Guide - core VRP concepts: fleet, depot, constraints.
API Reference - every endpoint, every field, every error code.