Fuel Stops

SALLY monitors fuel consumption across every segment of a route and automatically inserts fuel stops when the tank would drop below a safe threshold. Fuel stops are selected based on price, proximity to the route, and truck-friendliness.

How Fuel Insertion Works

During route planning, the fuel simulation runs alongside the HOS simulation:

Track consumption — For each drive segment, calculate fuel used: distance_miles / vehicle_mpg
Check threshold — If fuel would drop below 25% of tank capacity before reaching the next stop, a fuel stop is needed
Find stations — Query for truck-friendly fuel stations within 10 miles of the route
Select best station — Choose based on optimization priority (price or time)
Insert segment — Add a fuel stop segment to the route plan

Fuel Stop Selection Criteria

Criterion	Priority	Description
Proximity to route	Required	Station must be within 10 miles of the route path
Truck-friendly	High	Prefer stations with truck parking (Pilot, TA, Loves, Flying J)
Diesel price	Medium–High	Select cheapest option among candidates (when priority is `cost`)
Detour time	Medium	Minimize time lost leaving and rejoining the route
Operating hours	Required	Station must be open at the estimated arrival time

Fuel Stop API (Internal)

POST /api/v1/fuel/find-stops

This endpoint is called internally by the route planner, not directly by clients.

Request

{
  "route_segment": {
    "from": { "latitude": 34.0522, "longitude": -118.2437 },
    "to": { "latitude": 36.7783, "longitude": -119.4179 },
    "distance_miles": 250
  },
  "vehicle": {
    "fuel_level_gallons": 50,
    "fuel_capacity_gallons": 200,
    "mpg": 6.0
  },
  "optimization_priority": "cost"
}

Response

{
  "fuel_stop_needed": true,
  "recommended_stop": {
    "station_name": "Pilot #4521",
    "brand": "Pilot",
    "latitude": 35.3733,
    "longitude": -119.0187,
    "diesel_price_per_gallon": 4.29,
    "distance_from_route_miles": 0.3,
    "detour_time_minutes": 5,
    "miles_into_segment": 150,
    "truck_friendly": true
  },
  "fill_recommendation": {
    "gallons_to_fill": 150,
    "estimated_cost": 643.50,
    "fuel_level_after": 200,
    "range_after_miles": 1200
  }
}

Fuel Segments in Route Plans

When a fuel stop is inserted, it appears as a segment in the route plan:

{
  "sequence": 4,
  "type": "fuel",
  "location": "Pilot Travel Center - Bakersfield",
  "station_name": "Pilot #4521",
  "fuel_price_per_gallon": 4.29,
  "gallons_to_fill": 65,
  "fuel_cost": 278.85,
  "duration_hours": 0.5,
  "fuel_state_after": {
    "fuel_level_gallons": 165,
    "range_remaining_miles": 990
  }
}

Key fields:

Field	Description
`station_name`	Name of the fuel station
`fuel_price_per_gallon`	Diesel price at the station
`gallons_to_fill`	How many gallons will be added
`fuel_cost`	Total cost for this fuel stop
`duration_hours`	Estimated time for the fuel stop (typically 0.5h)
`fuel_state_after`	Fuel level and range after filling

Fuel Tracking Through the Route

The route plan tracks fuel state across every segment. Here’s an example of how fuel is consumed and replenished:

Segment	Distance	Fuel Used	Fuel Remaining	Range	Action
Origin → Stop A	100 mi	17 gal	83 gal	498 mi	—
Stop A → Stop B	250 mi	42 gal	41 gal	246 mi	—
Stop B → (check)	—	—	41 gal	246 mi	Fuel stop needed (next segment is 300 mi)
Stop B → Pilot #4521	120 mi	20 gal	21 gal	126 mi	Fuel stop inserted
Pilot #4521 (fill)	—	—	200 gal	1200 mi	Filled to capacity
Pilot #4521 → Stop C	180 mi	30 gal	170 gal	1020 mi	—

Optimization Priorities

How the optimization_priority in the route plan request affects fuel stop selection:

Priority	Fuel Stop Behavior
`time`	Selects the closest station to minimize detour time, even if price is slightly higher
`cost`	Selects the cheapest station among candidates, accepting a longer detour if savings are significant
`balanced`	Weighs price and detour time equally

Configuration

Default fuel parameters (configured per vehicle):

Parameter	Default	Description
Tank capacity	200 gallons	Total fuel tank capacity
MPG	6.0	Miles per gallon
Low fuel threshold	25% of capacity	When to trigger fuel stop insertion
Search radius	10 miles	Maximum distance from route to search for stations
Fill strategy	Fill to capacity	Always fills tank completely at fuel stops

Data Source

In the current POC, fuel prices come from a mock fuel price API:

GET /api/v1/external/fuel-prices?latitude=35.37&longitude=-119.02&radius_miles=10

This returns realistic mock data with artificial latency (100–150ms). Responses include a data_source: "Fuel Finder (Mock)" field to clearly indicate mock data.

In production (Phase 3), this will be replaced with live data from GasBuddy or a similar fuel price API.