cheapest_fuel_along_route
Find the cheapest fuel along a route, with the REAL extra travel time of stopping at each station, never a straight-line guess. Provide origin + destination (a route is computed) or an existing route's geometry_polyline6, plus a fuel code ("diesel" default, "petrol_95", "petrol_98", "premium_diesel", "e85", "lpg") and max_detour_minutes (default 10). Stations come from the live open-data price feeds (UK retailer feeds of the closed CMA interim scheme and/or the statutory Fuel Finder, FR prix-carburants, DE Tankerkoenig; the response's fuel_attribution names the ones actually matched), are priced through the routing engine with your costing (a truck profile makes detours respect dimensional/ADR restrictions) and ranked freshest-priced first and cheapest within that. Each result carries price {value, currency, updated_at, stale}, detour_minutes/detour_km, and saving_per_litre vs the cheapest on-route baseline (pass fill_litres to also get saving_total). stale = not verifiably fresher than 24 h: true unless BOTH the price's own updated_at and the snapshot's fetch time are inside that window, and true whenever either is missing. A stale price is ranked below every fresh one, is never the baseline, and carries NO saving_per_litre, quote it as "last seen at X on ", never as a saving. say is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the number, the detour and the honest qualifier already in it. Prefer reading it verbatim to writing your own summary: a stale price's line states the figure and the day it was last seen and claims no saving, and an empty result's line names the cause rather than implying there is no fuel on that road. coverage says what the price snapshot holds (stations, countries, sources) and, when it holds UK stations, carries a statement naming the UK retailers covered, with uk_retailers and uk_partial. Show the statement with any UK answer: when uk_partial is true UK prices come only from those retailers' feeds, so an empty UK result means "none from these retailers", never "no fuel here". An empty result also carries note, the cause in prose, which on such a route ends with that statement. Requires the MapMap gateway; answers a clear error when the deployment has no fuel-price dataset. Display the returned fuel_attribution with the prices.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fuel | No | Which fuel to price: "diesel" (default), "petrol_95", "petrol_98", "premium_diesel", "e85" or "lpg" (aliases "petrol", "unleaded", "e10", "super_unleaded", "e5", "b7" and "sdv" are accepted). | |
| truck | No | Truck profile (dimensions + ADR declaration). Requires costing "truck"; the detours then respect dimensional/ADR restrictions. | |
| origin | No | Route origin (with `destination`, when no geometry is given). | |
| costing | No | Costing model for the route and detour matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". | auto |
| destination | No | Route destination. | |
| fill_litres | No | Optional fill size in litres; each result then also carries `saving_total` = `saving_per_litre` × `fill_litres`. | |
| max_results | No | Maximum results (default 5, at most 25). | |
| geometry_polyline6 | No | An existing route geometry as an encoded polyline6 (the `route` tool's `geometry_polyline6`). Provide either this or `origin` + `destination`, not both. | |
| max_detour_minutes | No | Largest acceptable detour in minutes (default 10, at most 120). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| say | Yes | **Always present.** The whole answer as one short spoken line, composed by the gateway: the number, the detour, and the honest qualifier where one applies. Safe to read to a driver verbatim, and safe on an empty result, where it names the cause rather than implying there is no fuel on the road. A stale price's line states the figure and the day it was last seen and claims no saving. | |
| fuel | Yes | The normalised fuel code that was priced (e.g. "diesel"). | |
| note | No | Why `results` is empty, when it is: the cause, not a bare list. On a UK route where UK prices come only from some retailers' feeds it ends with `coverage.statement`, so an empty answer is never read as "no fuel here". Absent when there are results. | |
| costing | Yes | The costing the detours were priced with. | |
| results | Yes | Stations within the detour budget, cheapest first (price, then detour). | |
| baseline | Yes | The cheapest effectively-on-route option per currency (empty when no station sits on the route itself). | |
| coverage | No | What the deployment's price snapshot covers. On a UK route, show `coverage.statement` to the user alongside the results: it names the UK retailers covered, and an empty UK result means "none from these retailers", never "no fuel here". Absent when the gateway is too old to report coverage. | |
| candidate_cap | Yes | The matrix fan-out cap in force. | |
| route_length_m | Yes | Length of the route geometry in metres. | |
| fuel_attribution | No | Attribution string for the fuel-price data sources actually returned, display it with the prices (a licence obligation). | |
| route_distance_m | No | Direct origin→destination distance in metres. | |
| route_duration_s | No | Direct origin→destination travel time in seconds (same estimator as the detour legs), when routable. | |
| candidates_costed | Yes | Candidates actually priced through the engine (fan-out capped at `candidate_cap`, cheapest kept). | |
| max_detour_minutes | Yes | The detour budget applied, minutes. | |
| candidates_considered | Yes | Stations selling the fuel that passed the corridor pre-filter. |