Keyless proxy for the UK Fuel Finder API. Holds the GOV.UK OAuth 2.0 client credentials server-side so the FuelBoard iOS app and widget never embed a secret (secrets inside an IPA are extractable by anyone).

Architecture

FuelBoard app / widget
        │  GET http://192.168.1.131:8788/api/v1/stations?fuel=e10&lat=..&lng=..
        ▼
   FuelBoard Relay (this repo, runs on the Mac Mini)
        │  OAuth 2.0 client_credentials grant (token cached ~1h)
        │  GET https://api.fuelfinder.service.gov.uk/v1/prices (snapshot, cached 5 min)
        ▼
   UK Fuel Finder API  (official gov.uk open data)

Token refreshed automatically before expiry (60s buffer).
Station snapshot cached FUEL_CACHE_TTL (default 300s); stale cache is served on upstream failure so the app never sees a hard outage.
No credentials are exposed to clients — the app calls the relay keyless.

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env      # then fill in FUEL_API_CLIENT_ID / FUEL_API_CLIENT_SECRET
./scripts/run.sh

Without credentials the relay runs in demo mode: /health reports demo_mode: true and /api/v1/stations returns a clean 503 with a hint — useful for testing the app→relay path before credentials exist.

Endpoints

Endpoint	Description
`GET /health`	Cache status, last sync, failure counters
`GET /api/v1/stations`	All stations with prices (keyless)
`GET /api/v1/stations?fuel=e10&lat=53.72&lng=-1.85&radius=10&limit=10`	Filter by fuel, radius around a point, sorted nearest-first
`GET /api/v1/stations?fuel=diesel` (no lat/lng)	Sorted cheapest-first

Fuel grades: e10, e5, diesel.

Getting credentials

Sign in at https://developer.fuel-finder.service.gov.uk/get-started-ifr/onelogin with GOV.UK One Login.
Register an application → get client_id + client_secret.
Put them in .env (never in git, never in the app).

Fair use notes (from the Fuel Finder developer guideline)

Refresh at least every 5 minutes — we do (cron-style refresh on request + TTL cache).
Serve data unmodified — this relay only filters/sorts, never alters prices.
Keep timestamps — price_updated is passed through untouched.

Integration point (FuelBoard app)

Shared/FuelPriceProvider.swift has FuelFinderProvider stubbed with a TODO. When the relay is live, point it at:

http://192.168.1.131:8788/api/v1/stations?fuel=<e10|e5|diesel>&lat=..&lng=..

and map stations[].price / stations[].distance_km into FuelStation.