Skip to main content
POST
/
v1
/
optimize
Compute the cost-optimal fueling plan for a route
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,
      "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
  }
}
'
{
  "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.

​
stations
Station · object[]
required
Required array length: 1 - 5000 elements
​
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.

​
params
OptimizationParams · object

Response

Optimal plan computed.

​
stops
StopRecommendation · object[]
required
​
summary
RouteSummary · object
required
​
feasible
boolean
required
​
request_id
string
required
​
warnings
string[]