FuelOracle

Create a trip. Required: title, vehicleId (from list_vehicles) and at least two waypoints. Each waypoint has sequence (0, 1, 2 ... in route order), type (start, sightseeing, overnight, fuel, finish; the first is start and the last is finish), label, lat and lng (from geocode_place), and optionally address, notes, category, mandatoryFuelStop (the plan must refuel here), fillTank and fillCans (what a required fuel stop fills: the car, the jerry cans, or both; left out they default to the car alone, or keep the stored value), arrive_date and depart_date (YYYY-MM-DD), arrive_time and depart_time (HH:mm, local). A waypoint has one purpose. A required fuel stop is a waypoint of its own: one given type fuel, or a sight in the Fuel category, is saved as a required fuel stop (type fuel, category fuel, mandatoryFuelStop true). A camp, town, sight or overnight stop is not a fuel stop: one given mandatoryFuelStop, or the Fuel type or category, is not saved until the traveller answers whether to convert it into a required fuel stop and whether to keep a camp at the same place. The result then carries that question and saves nothing; convertToFuelStop and alsoAddCamp on that waypoint carry the answer. A camp and a fuel stop at one place are two waypoints, each with its own card. A required camp saved before this rule stays as it is. On a towing trip (isTowing), the van: towingAfter false on a waypoint is Un-hitch (the van is left there), true is Hitch up (the van is picked up there), null keeps the van as it is; on a trip that does not tow they are kept and have no effect until isTowing is true again. A stop where the traveller comes back to a camp where the van was left (a base camp with day trips) has returnsToWpId, the id of that camp in the same list (a camp new in the same save carries a temporary id there): the van is picked up there, so the plan asks nothing; with several day trips each return is linked, and the last one is where the van is picked up. stayUnhitched true on an Un-hitch stop records Stay un-hitched to the finish (the van stays there for the rest of the trip, so the plan has no warning about it). A towing trip has caravanId (from list_caravans) and isTowing. Each plan allows a set number of trips (get_plan_limits). The trip has no fuel plan until it is planned with plan_trip.

create_trip

Permanently delete every in-app notification the user has, read or unread. It cannot delete only some of them; mark_notifications_read clears the unread count without deleting any.

delete_notifications

Permanently delete a caravan and its weigh-ins, including combined weigh-ins with any vehicle. If it was the default caravan, the oldest remaining caravan becomes the default.

delete_caravan

Permanently delete one of the user's trips with its waypoints, fuel plan, check-ins and fill-ups. People it was synced to lose it. Locked trips cannot be deleted (set_trip_locked unlocks them). Archiving with set_trip_status keeps the history instead.

delete_trip

Permanently delete a vehicle and its weigh-ins. Trips that used it keep their history but need another vehicle before they can be planned again.

delete_vehicle

Permanently delete a weigh-in. for="vehicle" needs vehicleId, for="caravan" needs caravanId, for="combined" needs neither. The weigh-in id comes from list_weigh_ins.

delete_weigh_in

Copy a trip as a new planned trip with the same waypoints and settings. The copy is titled "<title> (Copy)", has no fuel plan, check-ins or fill-ups, and is left out of travel stats. Works on the user's own trips and trips synced to them; a copy of a synced trip has no vehicle until set_trip_vehicle sets one. Counts toward the plan's trip limit.

duplicate_trip

Find the coordinates of a place in Australia from its name or address. Returns up to 5 matches with their full name, lat and lng, best match first. Trips, search_fuel_prices and preview_route take these coordinates.

geocode_place

Fuel stations out of stock now, with the nearest station still selling that fuel. Along a trip, near a point, in a state or across Australia. For questions about fuel shortages or whether stations on a route have fuel. Each station lists its out-of-stock fuels with since (when the outage began, from FuelOracle's recorded history; sinceAtLeast means it began on or before that), signal (reported by the state scheme, or inferred where NSW FuelCheck stopped listing a fuel the station sells, shown for up to 90 days), in NT the outageReason and expectedBackAt, and nearest (the closest station selling that fuel within 150 km, or null). Stations are grouped by highway corridor, city or state. WA has no listings: FuelWatch does not report stock (see coverage). Every listing is at last report: call ahead to check. Returns at most 60 stations; total says how many there are.

list_out_of_stock

Fuel price trends for Australia, a state, a capital or a suburb. Covers the daily median price per fuel (Australian dollars per litre) over 7, 30 or 90 days with each day's cheapest and dearest: the lowest and highest buyable price (still listed by the feed, in stock and plausible) in force at any time that day for at least 15 minutes. range names the station and day of the window's cheapest and dearest, and of the last complete day (lastFullDay) and the day still under way (partial, up to asOf). Each fuel also has the change, the low and high days of the median, outages, capital against regional prices, the best day of the week to fill up where a reliable pattern exists, and for a suburb the nearby suburbs worth the drive. For capitals and suburbs each fuel also has its price cycle: whether it cycles, the current phase, and a forecast of the next rise only where that forecast has passed a test against FuelOracle's own recorded history (forecast null otherwise, with the reason in cycle.gate.reason). A forecast is an estimate, not a certainty. Nothing is shown for a place or fuel with under 14 days of history.

get_fuel_trends

One caravan in full, including the tow vehicle limits recorded against it (GVM, BTC, GCM, tow ball, axle limits, kg) and its tow compliance check. The caravan id comes from list_caravans. loaded_mass_source and height_source: entered by the user, typical for the body type, or null for unknown. current_location is where the van is now, null when none is recorded: state hitched (no place), or unhitched at lat, lng and label with kind (home, storage, camp for a caravan park or camp, other, or null), with source (trip_completed: where a completed towing trip left it; user_set: set by the traveller; checkin: the check-in answer, un-hitched at the stop or still hitched), trip_id and set_at. with_you is state hitched, for older apps. usually_kept_at is where it lives (lat, lng, label, kind home or storage), or null. recentPlaces (1 to 50) adds recent_places: where it was un-hitched lately, newest first, one per place (lat, lng, label, kind, source, set_at, trip_id).

get_caravan

The trip's current fuel plan without changing anything. For where to fill up on a trip and what its fuel costs. Returns the plan summary: the waypoints in travel order with their route km (route), and the fuel stops in route order, each saying which waypoints it falls between (afterWaypoint, beforeWaypoint, or atWaypoint when the stop is a waypoint; these place a stop on the trip, which route km alone does not; samePlaceAs names the waypoints at the same place, such as a camp beside the station; a camp or town is not a fuel stop, so a stop at it is a stop of its own beside it, and a required fuel stop is a fuel waypoint of its own with the stop at it as atWaypoint), with station, brand, address, state, route km (distance from the start of the trip, not from the last stop), off-route km, arrival fuel % of tank, planned litres, price in cents per litre, leg and cumulative cost in AUD, jerry can fill and draw litres, plus total km, total fuel cost (AUD) and planner warnings. drawsOnJerryCans means the plan uses jerry can fuel, which is the user's choice: get_jerry_decision offers the options. A stop whose fuel the feed has since reported out of stock carries outOfStock (since, a call-ahead note, and in NT the reason and expected-back time), and the plan then carries outOfStockNotice; plan_trip replans around those stations. Also shows the fill recorded at completed stops.

get_fuel_plan

One fuel station in detail: address, opening hours, amenities, whether it needs a permit or fills jerry cans, the latest price for each fuel (Australian dollars per litre) with when it was reported, traveller votes, and recent road and station conditions (what and when; written notes from other travellers are not included). For questions about one station: its prices, hours, facilities and conditions. Station ids come from search_fuel_prices or a trip plan. A government-feed station (for example nsw_, qld_, wa_rss_, nt_) returns its official price for every fuel, each with a status as in search_fuel_prices and, in WA and NT, tomorrow's locked price; traveller votes and conditions are under community. An id the lookup does not know returns communityOnly with votes and conditions only.

get_station

Other stations the user could fill at instead of a planned fuel stop, within windowKm of it along the route, cheapest known price first. Each has stationId, name, brand, address, state, route km, offRouteKm (straight-line km from the route), detourKm (the km the side trip adds there and back as the planner charges it: by road when measured, else twice offRouteKm), price in cents per litre (priceIsUnknown when there is none), costDeltaAud (what choosing it adds to the plan's total cost as the planner weighs it, a saving negative: the fuel difference with its side trip's fuel, plus a per-km allowance for the time and wear of the side trip, which is not money spent), costIncludesDetour (true when that figure counts a side trip of half a km or more, this station's or the planned stop's) and an indicative range after a full fill in km above the reserve (an estimate, not a safety check). swap_fuel_stop takes a stationId and its km from this list.

get_fuel_stop_alternatives

Tested choices for the jerry can fuel the plan uses, or for changing a required fuel stop. Without litres: one decision per pour and per leg the tank alone cannot do (a Law 2 bridge), each option from a re-solve with its outcome (the next stop and the tank % on arrival, litres left in the cans, the plan cost and its change; the change is null when the two plans leave out different litres with no price, and costUnknown then names those stops and the litres the two plans differ by there; it is also null with no costUnknown when the plan as it is does not plan). Options: keep_draw (as planned), reduce_pour (litres is the smallest pour that still plans), remove_pour or keep_in_cans (keeping the fuel in the cans; withOneOf lists the fuel stop or confirmation it needs, notPossible says why it cannot be done). With litres and pour: what that pour would do before it is saved, the same outcome, or the reason it does not plan and the smallest amount that does. pour is { waypointId } for a waypoint's pour, or { stationId, name, stopId or km } for the pour that goes with skipping a station. The amount is the user's decision. A waypoint pour changes through update_waypoint jerry_pour_litres, a skip's pour through skip_station pourLitres, then plan_trip. With requiredStop (a required fuel waypoint's id): the tested changes for that stop instead, each with its outcome in words or notPossible and the fuel stops that fix it (withOneOf): fill_here (intent tank, cans or both), different_station (listed stations within 5 km, up to 5), dont_require (effect remove_waypoint removes a fuel waypoint, not_required keeps a camp or town), keep_on_cans (a pour instead of filling the car, the station skipped on that pass; the smallest pour that plans; fillsNear lists car fills the plan still makes at another station near it). With requiredStop and litres: what keep_on_cans with that many litres does. set_waypoint_mandatory_fuel with change applies an option. A stop with a recorded fill is refused until the fill is removed. Runs several solves, up to about a minute. Writes nothing and is not counted in the daily plan limit. The plan summary marks a plan that uses jerry can fuel with drawsOnJerryCans.

get_jerry_decision

The trip's jerry cans: each can's canId, capacity and current litres, and the average price paid for the fuel in it (cents per litre, null when unknown). borrowedFuel is the borrowed fuel on board, one entry per stretch it was lent for (id, from_km and to_km in route km from the start, from_name, to_name, litres confirmed and litres_left, whole litres): it counts only on that stretch, is not refilled at a station, and is no longer counted once the trip passes the stretch's end. An entry with needs_confirming true is not counted: the route changed and the stretch is no longer on it, so remove it and borrow for the stretch again. borrowed.litres is the figure older app builds read, null once a stretch has its own.

get_jerry_cans

Which notifications the user receives (trip reminders, price changes, road alerts and so on) and how.

get_notification_preferences

How many trips the user's plan allows and how many they have, which says whether another trip can be created.

get_plan_limits

Check a plan that was still running when plan_trip, swap_fuel_stop, skip_station or unskip_station returned a jobId. Waits up to 25 seconds more. When finished: Returns the plan summary: the waypoints in travel order with their route km (route), and the fuel stops in route order, each saying which waypoints it falls between (afterWaypoint, beforeWaypoint, or atWaypoint when the stop is a waypoint; these place a stop on the trip, which route km alone does not; samePlaceAs names the waypoints at the same place, such as a camp beside the station; a camp or town is not a fuel stop, so a stop at it is a stop of its own beside it, and a required fuel stop is a fuel waypoint of its own with the stop at it as atWaypoint), with station, brand, address, state, route km (distance from the start of the trip, not from the last stop), off-route km, arrival fuel % of tank, planned litres, price in cents per litre, leg and cumulative cost in AUD, jerry can fill and draw litres, plus total km, total fuel cost (AUD) and planner warnings. drawsOnJerryCans means the plan uses jerry can fuel, which is the user's choice: get_jerry_decision offers the options. A stop whose fuel the feed has since reported out of stock carries outOfStock (since, a call-ahead note, and in NT the reason and expected-back time), and the plan then carries outOfStockNotice; plan_trip replans around those stations. If planning failed, returns the reason.

get_plan_status

The user's FuelOracle profile: name, email, home location, and app preferences (navigation app, default trip view, fuel discount programs).

get_profile

Current road incidents near the trip's route (closures, hazards, roadworks, floods). Incidents come from state traffic authorities, with severity, road, start and end times, and a warning when a stated height clearance is below the towed caravan's height. Available on paid plans only; otherwise returns the plan message.

get_road_alerts

A trip another user has synced to this user, read-only, in the same shape as get_trip. Where the owner hides their home, the start and finish show only the suburb. Trip ids come from list_shared_with_me.

get_synced_trip

One of the user's trips in full: settings, waypoints (with ids, route km and check-ins), the planned fuel stops (with ids, station, route_km from the start of the trip, the waypoints each falls between as afterWaypoint and beforeWaypoint, price in cents per litre, litres to fill, cost in AUD, fuel on arrival as % of the tank, and any completion recorded), the completion summary, plan warnings and flood warnings. For questions about one trip: its route, dates, stops and fuel. While its last plan failed and none has worked since, planBlockers says why and what would fix it: one blocker per failing stretch, in route order, with its ledger in whole litres: stretchL used, tankAboveReserveL (what can be used from the tank before reaching the reserve, not what it holds), reserveL kept in the tank, cansNowL in the jerry cans on reaching it (null where the cans cannot bridge it), cansCapacityL when full, borrowedL, cansNeededL and shortL, where stretchL = tankAboveReserveL + cansNowL + shortL; cansCapacityL and cansNowL include the borrowed fuel lent for that stretch (borrowedL), and ownCansCapacityL, ownCansNowL and borrowedNowL split them into the traveller's own cans and that borrowed fuel (a fill at a station tops up only the own cans). A stretch that holds borrowed fuel already has it in borrowed (id, litres). Each stretch blocker lists every fix for it in priority order (fuel station, unlisted station with fuel confirmed, jerry cans, borrowed fuel); a fix that changes something else, such as a skipped station or the fuel level at the start, says what in why. towing_return: set towing_after on the option waypoint. A blocker with alternativeOf (older stored plans) is another way to fix the stretch blocker with that id, not a separate problem. An option with tested true planned the whole trip in a test solve. An option with fixesTrip false (tested false) fixed its stretch while another listed stretch still fails, and alsoFixes lists later stretch ids the same test cleared. Any other option was not proved and carries untestedReason. A borrowed_fuel option is fuel borrowed for that stretch only: litres is what the stretch holds once applied, for borrowedStretch (fromKm, toKm); the planner counts it on that stretch alone, does not refill it, and stops counting what is left at the stretch's end. Apply it with set_jerry_can_level (borrowed, with stretch, or borrowedFuelId when the option has borrowedId). An add_jerry_cans option with withOneOf was tested only together with one of those fills: the capacity with one of them works, the capacity alone was not proved. Each option has fuelFrom (station, unlisted, cans, borrowed), and options are listed in that order of priority, so the first that passed is the highest-priority fix. planBlockers.packages lists up to three whole-trip fixes, each tested with one solve that planned the whole trip when tested is true: its apply.jerryCansConfig (the trip's own jerry cans to set, when present) and then each of apply.options, applied as that option on its own, fix every stretch together; own_cans packages say in fills where the cans are filled and how much each fill carries, with ownCanCapacityL the traveller's own cans once applied. Options from several stretches were not tested together, a package was. Distances are km. Trip ids come from list_trips.

get_trip

An overview of all the user's trips that are not archived: how many are in each status, and for each trip its places (label, type, coordinates) and the fuel stations it stops at. Useful for "where have I been" and "where am I going" questions. Distances and costs are in list_trips and get_trip_report.

get_trips_overview

The trip's dashboard: progress while it is under way, or the finished report once completed. For questions about how a trip is going or how a finished trip went. Includes distance (km), litres bought and poured from jerry cans, spend against the plan (AUD), prices paid (cents per litre), measured economy (L/100 km), per-stop and per-day figures, per-leg predicted and actual burn, the wind met on each leg driven, an elevation profile, and the next stop. wind.legs gives each driven leg's mean wind, headwind (+ into the vehicle, - behind it) and crosswind in km/h; get_trip_wind has every point read along the route. elevation.points (km, metres) is thinned to at most 120 points and keeps every high and low. Works for the user's own trips and trips synced to them.

get_trip_report

Daily weather forecast (up to 16 days ahead) at each waypoint of the trip, with the date the traveller is expected there. Each day has maximum and minimum temperature (°C), rain (mm), maximum wind speed (km/h) and a WMO weather code. Dates outside the forecast window have no forecast.

get_trip_weather

The wind actually met on each leg of a trip that has been driven, with every point read along the route: km, position, hour, wind speed (km/h), the direction it blew from and the direction of travel (degrees), and the headwind (+ into the vehicle, - behind it) and crosswind. Legs run between recorded fills and check-ins and appear a few hours after they end. A leg is "estimated" when its ends were recorded across a stay, so the drive is placed just before arrival. Own trips only.

get_trip_wind

One vehicle in full, including towing limits (GVM, GCM, tow ball), size (height_mm, length_mm), loaded_mass_kg and service schedule.

get_vehicle

What the vehicle actually uses, measured from recorded fills, and the economy plans use, at a given speed and optionally towing one of the user's caravans. For questions about how much fuel the user's vehicle uses, solo or towing. measured: litres-weighted figures from fill-to-fill legs, solo and towing. estimate.towingSource says where a towing plan's figure comes from: computed (the normal case, worked out from the caravan's mass and drag), vehicle (a figure stored on the vehicle) or override. estimate.towingCalibration, on the computed branch: the rig's measured figure, how many legs it rests on, the legs needed (5) and, once active, calibratedEstimate, which is the figure plans use.

get_vehicle_economy

The user's caravans and trailers with masses (tare, loaded, ATM and tow ball download, kg), size (mm), modifications, hub odometer (km), service status and, when the tow vehicle limits are recorded, a tow compliance check. The default caravan is listed first. For questions about the user's own caravans and trailers and their weights.

list_caravans

The fuel discount cards and memberships FuelOracle knows (for example supermarket dockets and fuel cards), with their tiers, for update_preferences.

list_fuel_discount_programs

The user's in-app notifications, newest first.

list_notifications

The public share links the user has made for one of their trips: when each was created and expires, how many times it was viewed, whether viewers may sync the trip, whether home is hidden, whether it was revoked, and who synced through it. The links themselves are not shown; the user can copy them in the FuelOracle app.

list_trip_shares

The people the user has invited to follow one of their trips, with each sync's status (pending, active, removed by the recipient, or revoked by the owner), when it was invited, accepted and last viewed, and whether home is hidden from them.

list_trip_syncs

The user's trips (up to 100), active first, then planned, completed and archived, each status in order of start date. For questions about the user's road trips: the next trip, what is planned, where they are going and where they have been. Trips with no start date come last within their status. Each has its id, title, status, dates, start and finish place, vehicle, whether it tows, planned distance (km), planned fuel cost and fuel spent so far (AUD), and whether it is locked. planned_fuel_cost_aud is what the plan buys at the pump, which includes fuel still in the tank at the finish, so it is not the cost of the fuel the trip burns. get_trip returns one trip in full.

list_trips

Trips other FuelOracle users have synced to this user (active syncs only), with the sync id, trip id, owner, dates, start and finish, and planned distance (km). get_synced_trip takes the trip id and returns the full trip; leave_sync takes the sync id and stops following it.

list_shared_with_me

The user's vehicles with fuel type, tank size, economy (solo and towing, L/100 km), range, odometer and service status. For questions about the user's own vehicles. Towing economy is normally empty: plans then work it out per caravan and learn it from recorded fills (get_vehicle_economy shows the figure used).

list_vehicles

Weighbridge records, newest first. for="vehicle" needs vehicleId (from list_vehicles); for="caravan" needs caravanId (from list_caravans); for="combined" lists whole-rig weigh-ins, optionally filtered by vehicleId and caravanId. Masses are kg; tank levels are percent.

list_weigh_ins

Lock a trip so its route, settings and waypoint notes cannot be changed and it cannot be deleted, or unlock it. Recording or editing anything on a locked trip (fill-ups, jerry can pours and refills, check-ins, stop rules) needs it unlocked.

set_trip_locked

Mark the user's notifications as read: the ones given, or all of them when none are given.

mark_notifications_read