Highway Motor Freight

Fuel Planner

If you know the next load, the planner buys only what makes sense before the delivery and shows where to fuel on the way to the next stop.
Use this if the straight-line demo route drifts from the highway you actually drive.
Auto finds the cheapest plan with any number of stops.
Enter a start, destination and current range, then press Plan fuel stops.

Trucks

Range is tank size × mileage. Edit any row; add a row for each unit. A fleet-wide CSV upload (unit, model year, make, tank, mpg) will replace this table later.

Unit / nameTank (gal)Miles per galFull range

Planning rules

If no station within that width lets the truck cross a stretch, the search widens across that stretch only (to at most 150 mi) and says so. Road factor only matters in this demo, which estimates distance from straight lines. The production build will use a routing API (Google, HERE or Mapbox) and this setting disappears.

Exchange rate & maps

Entered daily for the demo. Production pulls the Bank of Canada daily rate automatically each evening with the price files. All optimisation runs in USD per US gallon.

US price file (BVD / PCN, USD per gallon)

Upload tomorrow's PCN file (the same CSV format you receive today)

Columns read: SITE, NAME, CITY, STATE, RETAIL PRICE (column M) and YOUR PRICE (column N — the price offered to HMF, used for all planning), plus the effective date in the header row. Coordinates come from the site list; a new site that is not in the list shows up as "needs location" until it is geocoded.

Canada price file

Upload the Canada file

Reads the "YOUR PRICE" column (Q in your BVD file) the same way the US file reads column N. Accepts the PCN layout (SITE, NAME, CITY, PROV, YOUR PRICE) or a simple list (name, city, prov, price). LAT/LON columns are used when present; otherwise the town name is geocoded.

StationCityCAD / L≈ USD / gal

How the planner decides where to fuel

  1. Route. Start → (via stops) → border crossing → delivery → (next load). The downloadable file routes on real highways with OpenStreetMap data (OSRM) and shows the route on a map; the claude.ai-hosted copy cannot reach outside services, so it draws straight legs × a road factor instead.
  2. Next load. When the next stop after unloading is entered, the whole run is optimised together, so the last fill before delivery is sized with the onward stations in mind — small if cheap fuel is coming, larger if the next leg is expensive or empty.
  3. Stations on the route. Every station in the price file within the corridor width (default 15 miles either side) is placed at its mile marker along the trip.
  4. Common currency. US prices are your contracted price in USD per gallon. Canadian prices are CAD per litre × 3.785 ÷ today's CAD/USD rate, so both sides compare on the same scale.
  5. Cheapest plan. The planner tests every sequence of stops that keeps the truck above its reserve. At each stop it buys just enough to reach the next stop if that one is cheaper, and fills the tank if the next one is dearer. Auto picks the cheapest sequence overall; a fixed number of stops picks the cheapest sequence with exactly that many.
  6. Savings shown. Three comparisons for the same gallons: (a) buying everything at the dearest station on the route, (b) a full tank at the first station on the route and filling again whenever forced — what a driver does without the tool, and (c) pump retail at the chosen stops, which is what the BVD contract saves.
  7. Two price files, two fixed columns. US prices always come from column N ("YOUR PRICE") of the PCN file; Canadian prices always come from column Q ("YOUR PRICE") of the BVD Canada file. Everything else in each file (cost, taxes, retail) is ignored for planning, except retail, which is used only for the retail-savings comparison.

Assumptions in this demo

  • Default truck: 240 gal tank × 5 mpg = 1,200 miles. Reserve 100 miles. Minimum 30 gal per stop.
  • Map tiles are from CARTO's free basemap, not OpenStreetMap's own tile servers, which block apps like this one that have no web referrer. CARTO's free tier is also meant for light, non-commercial use — a real rollout needs a small paid tile plan.
  • Distances are estimates (straight line × 1.18). Add a via city if the route looks wrong.
  • Canadian stations come from the BVD Canada file (95 sites, column Q = "YOUR PRICE"), same as the 606 US sites from the PCN file (column N).
  • Settings and uploaded files are kept in this browser only; nothing is shared between users yet.

Modules (for the build-out)

The script is split into independent parts — Store (settings), Data (price files), Places (geocoding), Routing (distance & corridor), Optimizer (fuel-stop maths), Planner (screen), TripSheet (PDF). Each can be swapped or moved to a server without touching the others.