Prices & stations

FuelAtlas exposes truck-stop diesel prices as your effective prices: the retail price and your negotiated discount at each site, already applied. Two endpoints answer the two questions that matter — "what's near this point?" and "what's along this route?" Both require the prices:read scope.

#Stations near a point

curl "https://api.fuelatlas.com/v1/stations?latitude=35.15&longitude=-90.05&radius_miles=25" \
  -H "Authorization: Bearer fa_live_…"

Returns nearby stations, nearest-first, each with your price:

{
  "count": 12,
  "stations": [
    {
      "id": "stn_9Qm…",
      "name": "TA Memphis",
      "chain": "TA Petro",
      "latitude": 35.06, "longitude": -89.99,
      "address": "I-40 Exit 12, Memphis, TN",
      "price_usd_per_gallon": 3.499,
      "discount_usd_per_gallon": 0.42,
      "price_updated_at": "2026-07-06T09:00:00Z",
      "amenities": ["showers", "truck_parking", "scales"]
    }
  ]
}

price_usd_per_gallon is the site's current retail; discount_usd_per_gallon is your per-gallon discount off it (0 when you have none there). Net cost is price − discount.

#Stations along a route

Most fuel decisions are corridor decisions, not radius decisions. POST /v1/stations/along-route returns stations within a driving corridor — supply either an encoded polyline or an origin/destination pair:

{
  "origin": { "latitude": 35.15, "longitude": -90.05 },
  "destination": { "latitude": 41.88, "longitude": -87.63 },
  "corridor_width_miles": 3,
  "max_results": 40,
  "fuel_level_percent": 40,
  "estimated_mpg": 6.5,
  "tank_capacity_gallons": 200
}

Add the fuel context (fuel_level_percent + estimated_mpg + tank_capacity_gallons) and results are narrowed to stations the vehicle can actually reach on its current tank. Omit it to see every station on the corridor.

#The caps are the design

The station endpoints have firm caps. They aren't rate-limit accidents — they're what keeps the pricing dataset a routing tool rather than a scrapeable price book. Design to them and you'll never be surprised by a 4xx.

• Every request is shape-checked before it runs. Radius and corridor width/results-per-query beyond the caps above are rejected immediately with 422 validation_failed — fix the field named in errors and retry.
• Every disclosed station is charged to your plan's station-query budget. A response with 40 stations spends 40. When the budget is exhausted you get 429 station_budget_exceeded — reduce query volume or upgrade the plan.
• Sustained broad/grid-style scanning is detected, not blocked per-request. There's no per-call "you're scanning" error — instead, a pattern like querying dozens of distinct grid cells in an hour, or a day's unique-station count creeping past ~90% of your budget, logs a warning against your key. Warnings that repeat or escalate get your key auto-suspended (an admin alert fires at the same time); every call after that returns 403 key_suspended until support reinstates it. Querying tight corridors along real routes doesn't come close to these thresholds; sweeping a grid of the whole country does.
• Station ids are opaque (stn_…) and stable per fleet. They are never the internal truck-stop identifier, so you can't use them to enumerate the master dataset.

The practical rule: query the corridor of a real trip, not a wide area "to be safe." Autoguide already does this optimally for you — if you just want the right stop for a vehicle heading somewhere, use Autoguide instead of raw station queries.

#Savings report

Once trucks are fueling at recommended stops, GET /v1/reports/savings rolls up how much you saved over a period (requires usage:read):

curl "https://api.fuelatlas.com/v1/reports/savings?from=2026-06-01&to=2026-06-30" \
  -H "Authorization: Bearer fa_live_…"

It returns fleet totals (gallons, actual vs baseline cost, savings, per-gallon savings), an adherence rate (how often you fueled at a recommended stop), and per-vehicle rows. The figures derive from a rolling projection window; a period entirely before that window returns zeros with an explanatory note — that's an expected data-availability limit, not an error.

#Next

• Rate limits — how budgets, quotas, and per-minute limits interact.
• Autoguide — let the platform pick the stop for you.