What it does
- Current price at a station, for the fuel types that station sells.
- Cheapest fuel near a point, within a radius you choose.
- Cheapest fuel along a route, which is the question a dispatcher actually has.
- Price history for a station and for a market, so a price can be read against its own trend rather than in isolation.
- Change alerts on the stations you care about.
- Refuelling decisions — given a vehicle, its fuel card and its tank, which stop on an already-planned route it should refuel at.
This module is built on the Australian state government fuel-price disclosure schemes. There is no equivalent data source wired up for any other country, so the module has nothing to say outside Australia.
How it works
A price carries the kind of price it is
The states do not all publish the same thing, and treating their numbers as interchangeable would be dishonest. In Western Australia a published price is legally fixed for tomorrow — it is a commitment, not an observation. In New South Wales it is an observation of what a station was charging. In Victoria it is an observation that has been embargoed for 24 hours before release.
Those are three different claims about the world. A legally fixed future price, a current observation and a day-old observation cannot be ranked against each other as though they were the same measurement. So every price carries the kind of price it is, and a caller that wants to compare across states has to decide explicitly what to do about it rather than having the question quietly answered for them.
This is not route optimisation
The refuelling side takes a route that has already been decided and picks where on it to refuel. It does not reorder stops, and it does not trade delivery efficiency against fuel cost. Those are route optimisation’s job and belong to that module.
The decision it does make weighs the fuel card the vehicle carries (which stations it is accepted at, and at what discount), the state of the tank, and what the detour to a cheaper station actually costs in time and distance. A station that is four cents cheaper eleven kilometres off the route is not cheaper.
Current prices are served from the edge
The current-price lookups are answered from a cell-indexed snapshot at the edge rather than from the primary database. A dispatcher asking “what is cheap near here” is a read-heavy, latency-sensitive question with an answer that is the same for everyone asking from the same place — so it is precomputed and served close to the caller. History and market analysis, which are neither, are served from the database.
Permissions
| Permission | What it allows | Needed |
|---|---|---|
| fuel-prices.read | Read prices: current, cheapest near a point, cheapest along a route, and history. | Required |
| fuel-prices.write | Manage the stations you track and the price-change alerts on them. | Required to configure |
| fuel-optimisation.read | Read the account’s fuel-card rules — which cards are accepted where, and at what discount. | Required to refuel |
| fuel-optimisation.write | Create and edit those fuel-card rules. | Required to configure |
| fuel-optimisation.execute | Ask for a refuelling decision on a given route and vehicle. | Required to refuel |
| assets.read | Resolve the vehicle whose tank and fuel card the decision depends on. | Recommended |
| runs.read | Read the route a refuelling stop is being placed on. | Recommended |
These permission codes are defined and grantable, but the services behind them are not serving requests yet — see API reference. Granting them today prepares a credential; it does not make anything callable.
API reference
Both contracts are scaffolded but not yet serving operations — the price and refuelling endpoints described above are not callable.
| Service | What it covers | Reference | Contract |
|---|---|---|---|
| fuel-prices-api | Retail prices: current, cheapest near a point, cheapest along a route, history. | OpenAPI description | openapi.json |
| fuel-optimisation-api | Where a vehicle should refuel, given its fuel card, tank and detour cost. | — | — |
Neither service is serving yet. fuel-prices-api publishes a contract, but it is still a placeholder with no operations in it; fuel-optimisation-api is not deployed at all, which is why it has no links. Both will be filled in here when the module ships.
Each openapi.json is the generated OpenAPI 3.1 contract, served by the service itself — it is never hand-edited, so it cannot drift from the running API. The OpenAPI description link opens the same contract as a browsable reference. Both resolve to the environment these docs are served from, so a page read on the test site links to the test contract.
Events
This module raises no events yet.
Price-change alerts on the stations you track are part of the design, and they are the obvious candidate to arrive as webhook deliveries once the module ships. Nothing is published today, so there is nothing to subscribe to and no event type to register for.
The modules that do put events on the stream are listed with their event types in the event catalog; the envelope they arrive in and the delivery guarantees behind them are in Events & webhooks.