FuelAtlas.
Join the beta
FAFuelAtlasDevelopers

Developers / Guide

Autoguide

The flagship — bind a vehicle to a destination and continuously pull the cheapest on-route fuel stop.

Autoguide is the heart of the platform. You bind a vehicle to a destination once; from then on FuelAtlas continuously answers a single question as the truck drives: where should this vehicle fuel next, and how much should it buy? The answer accounts for the remaining route, current tank level and burn rate, live prices, your negotiated discounts, and how far each stop is off the corridor.

You don't recompute anything. You set a destination and then read a guidance object — a self-describing snapshot that tells you the current recommendation, how fresh it is, and when to check back.

The lifecycle

Autoguide moves a vehicle through four phases. Every guidance object reports its current phase, so a poller or agent always knows whether the recommendation is actionable.

  1. awaiting_data — guidance is set, but no usable recent breadcrumb has arrived yet. stops is empty. Start pushing locations.
  2. tracking — the vehicle is en route with enough fuel; no stop is needed yet. stops is empty, but the object carries a live fuel projection to the destination.
  3. stop_recommended — the vehicle needs fuel before (or to optimize) the trip. stops contains one or more recommended stops, cheapest-net-cost first.
  4. completed — the vehicle reached the destination (or guidance was cancelled). Set a new destination for the next leg.

1. Set a destination

HTTP
POST /v1/vehicles/veh_5tR…/guidance
Authorization: Bearer fa_live_…
Content-Type: application/json

Requires guidance:manage.

JSON
{
  "destination": {
    "latitude": 41.8781,
    "longitude": -87.6298,
    "name": "Chicago DC"
  },
  "min_arrival_fuel_percent": 15
}

min_arrival_fuel_percent is the reserve you want in the tank on arrival — the emergency floor guidance plans around. Setting a destination opens (or supersedes) the session and returns the guidance object with 201.

2. Read the guidance object

cURL
curl https://api.fuelatlas.com/v1/vehicles/veh_5tR…/guidance \
  -H "Authorization: Bearer fa_live_…"

Requires guidance:read. A vehicle with no active session returns 404 no_active_guidance.

JSON
{
  "id": "gd_7hK…",
  "vehicle_id": "veh_5tR…",
  "status": "active",
  "phase": "stop_recommended",
  "destination": { "latitude": 41.8781, "longitude": -87.6298, "name": "Chicago DC" },
  "based_on_location_at": "2026-07-06T15:04:05Z",
  "data_freshness": "fresh",
  "fuel": {
    "current_percent": 34.2,
    "current_gallons": 68.4,
    "range_miles": 410.0,
    "projected_percent_at_destination": -6.0
  },
  "stops": [
    {
      "stop_id": "stop_1a…",
      "status": "recommended",
      "station": {
        "id": "stn_9Qm…",
        "name": "TA Bucksville",
        "chain": "TA Petro",
        "latitude": 40.61, "longitude": -86.10,
        "address": "I-65 Exit 201, Bucksville",
        "highway_exit": "I-65 Exit 201"
      },
      "distance_ahead_miles": 128.4,
      "eta": "2026-07-06T17:22:00Z",
      "fuel_percent_on_arrival": 12.5,
      "price_usd_per_gallon": 3.499,
      "discount_usd_per_gallon": 0.42,
      "gallons_to_buy": 140.0,
      "target_fuel_percent_after": 88.0,
      "savings_vs_baseline_usd": 58.80,
      "reason": "Cheapest net stop within range; keeps you above your 15% reserve to Chicago."
    }
  ],
  "next_review_expected_at": "2026-07-06T15:09:05Z",
  "created_at": "2026-07-06T14:40:00Z"
}

Reading the fields that matter

  • phase tells you whether to act. Only stop_recommended carries stops.
  • data_freshness grades the breadcrumb the object was computed from: fresh (< 10 min), stale (10–30 min), expired (> 30 min). Treat a recommendation built on expired data with caution — the truck may have moved on. Keep locations flowing to stay fresh.
  • fuel.projected_percent_at_destination can go negative — that's guidance telling you the vehicle will run dry before arrival unless it stops. That's exactly when a stop is recommended.
  • Each stop is fully costed: gallons_to_buy, price_usd_per_gallon, your discount_usd_per_gallon, the resulting target_fuel_percent_after, and savings_vs_baseline_usd (versus fueling naively). reason is a one-sentence, agent-friendly rationale you can surface to a driver verbatim.
  • next_review_expected_at is when a fresh object is expected — roughly the guidance cycle. Poll no faster than this.

3. Poll, or subscribe

You can pull the object on next_review_expected_at, but the lighter path is webhooks. Subscribe to:

  • guidance.updated — the recommended set for a vehicle was created, refreshed, or cleared. Fetch the object when you receive it.
  • guidance.stop_approaching — the vehicle came within the proximity radius of a recommended stop. A good trigger to notify the driver.

Webhooks + an occasional reconciliation poll is the pattern most integrations settle on.

4. Acknowledge or skip a stop

When a driver accepts a recommendation, acknowledge it — this pins the stop so guidance stops re-shuffling it:

cURL
curl -X POST \
  https://api.fuelatlas.com/v1/vehicles/veh_5tR…/guidance/stops/stop_1a…/acknowledge \
  -H "Authorization: Bearer fa_live_…"

If the driver won't take it (closed, no parking, personal preference), skip it — guidance produces a fresh recommendation on the next cycle:

cURL
curl -X POST \
  https://api.fuelatlas.com/v1/vehicles/veh_5tR…/guidance/stops/stop_1a…/skip \
  -H "Authorization: Bearer fa_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "no overnight parking" }'

Both require guidance:manage. A stop's status moves through recommended → acknowledged → fueled (or skipped). When FuelAtlas later detects the truck fueled at the stop, it's marked fueled and rolls into your savings report.

5. Finish or re-target

Guidance auto-completes when the vehicle reaches the destination (phase: completed, status: completed). To retarget mid-trip, just POST a new destination — it supersedes the current session. To stop guidance entirely:

cURL
curl -X DELETE https://api.fuelatlas.com/v1/vehicles/veh_5tR…/guidance \
  -H "Authorization: Bearer fa_live_…"

A note on station ids

Stations in a guidance object are disclosed as opaque stn_… ids — never the internal truck-stop identifier — and each disclosure is metered against your plan's station-query budget. This is by design; see Prices & stations.

Next