POST /v1/optimize

Compute the cost-optimal fueling plan for a route

POST /v1/optimize

Compute the cost-optimal fueling plan for a route

cURL

curl --request POST \
  --url https://api.example.com/v1/optimize \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "route": {
    "total_distance_miles": 123,
    "total_duration_minutes": 123,
    "start": {
      "lat": 0,
      "lng": 0
    },
    "end": {
      "lat": 0,
      "lng": 0
    },
    "polyline": "<string>",
    "waypoints": [
      {
        "lat": 0,
        "lng": 0
      }
    ]
  },
  "stations": [
    {
      "id": "<string>",
      "name": "<string>",
      "address": "<string>",
      "location": {
        "lat": 0,
        "lng": 0
      },
      "brand": "<string>",
      "price_per_gallon": 50,
      "fuel_type": "regular",
      "miles_from_route_start": 1,
      "detour_minutes": 1,
      "metadata": {}
    }
  ],
  "vehicle": {
    "mpg": 100,
    "tank_capacity_gallons": 250,
    "current_fuel_gallons": 250,
    "year": 2005,
    "make": "<string>",
    "model": "<string>"
  },
  "params": {
    "time_value_dollars_per_minute": 0.5,
    "destination_reserve_fraction": 0.1,
    "inter_stop_buffer_fraction": 0.05
  }
}
'

200

{
  "stops": [
    {
      "station_id": "partner_xyz_001",
      "station_name": "Pilot",
      "station_address": "456 Truck Rd, Flagstaff, AZ",
      "miles_from_route_start": 487.3,
      "gallons_to_purchase": 247.2,
      "price_per_gallon": 4.29,
      "total_cost_at_stop": 1060.49,
      "detour_minutes": 3.2
    }
  ],
  "summary": {
    "total_fuel_cost": 1847.32,
    "total_fuel_gallons": 432.1,
    "total_time_hours": 31.5,
    "total_distance_miles": 2015.3,
    "fuel_remaining_at_destination_gallons": 32.4,
    "baseline_comparison": {
      "strategy_description": "Refuel to full at the next station ahead whenever the tank reaches 25% capacity.",
      "naive_total_fuel_cost": 2089.74,
      "naive_total_time_hours": 31.8,
      "savings_dollars": 242.42,
      "savings_percent": 11.6
    }
  },
  "feasible": true,
  "warnings": [],
  "request_id": "req_jkl345mno678"
}

The /v1/optimize endpoint is the core of the Nozle API. Given a route, stations with prices, and a vehicle, it returns the cost-optimal sequence of fueling stops along with a baseline comparison showing savings vs. naive refueling.

Algorithm

The optimizer uses dynamic programming to search for the stop sequence minimizing the objective function:

total_cost = fuel_cost + (time_value_dollars_per_minute × total_detour_minutes)

subject to:

• Tank capacity constraints (can’t exceed tank_capacity_gallons at any stop)
• Destination reserve constraint (must arrive with at least destination_reserve_fraction × tank_capacity_gallons)
• Inter-stop buffer constraint (must arrive at each stop with at least inter_stop_buffer_fraction × tank_capacity_gallons)

Baseline Comparison

The response includes a baseline_comparison object computing what a naive 25%-threshold refueling strategy would cost on the same route and station set. This provides the savings number partners use to demonstrate value to their customers.

For comparing costs fairly, the baseline uses net fuel cost (the dollar value of fuel actually consumed on the trip) rather than pump cost, since naive strategies often refuel to full and end with paid-for fuel in the tank.

Infeasibility

If the optimizer cannot find a feasible plan with the given inputs, it returns a 422 INFEASIBLE_ROUTE response with diagnostic details explaining why. Common causes:

• Insufficient current_fuel_gallons to reach the first available station
• Gap between consecutive stations exceeds vehicle range
• Reserve constraints can’t be satisfied with available stations

The details field in error responses includes specific diagnostic information to help debug the issue.

Authorizations

X-API-Key · string · header · required

Body

application/json

route · Route · object · required

Internal route representation. Flat shape — upstream adapters normalize Google/Mapbox responses into this before it hits B2B code.

Show child attributes

stations · Station · object[] · required

Required array length: 1 - 5000 elements

Show child attributes

vehicle · Vehicle · object · required

Vehicle parameters for optimization. Accepts either direct specs (preferred) or year/make/model for lookup. Direct specs override lookup values when both are provided.

Show child attributes

params · OptimizationParams · object

Show child attributes

Response

200

application/json

Optimal plan computed.

stops · StopRecommendation · object[] · required

Show child attributes

summary · RouteSummary · object · required

Show child attributes

feasible · boolean · required

request_id · string · required

warnings · string[]