API Documentation

The FuelCosts.co.uk API is free and open. No authentication or API keys are required. Data is sourced from the UK Government's Fuel Finder service and updated every 4 minutes.

Base URL: https://fuelcosts.co.uk/api

View System Status

Endpoints

GET/api/stationsGET/api/stations/[nodeId]/historyGET/api/stations/[nodeId]/history/allGET/api/stations/[nodeId]/commentsPOST/api/stations/[nodeId]/commentsGET/api/prices/historyGET/api/stats/brandsGET/api/stats/countiesGET/api/stats/regionsGET/api/stats/best-dayGET/api/geolocationGET/api/vehiclesGET/api/status

GET/api/stations

Search Stations

Fetch fuel stations with current prices, filtered by location and fuel type. Supports pagination and sorting by price or distance.

Parameters

Name	Type	Default	Description
`lat`	float	—	Latitude (required for distance sorting)
`lon`	float	—	Longitude (required for distance sorting)
`radius`	float	10	Max distance in miles
`fuel`	string	—	Fuel type filter (e.g. E10, B7_STANDARD)
`sort`	string	distance	Sort by: price or distance
`page`	int	1	Page number
`perPage`	int	50	Items per page

Example

curl "https://fuelcosts.co.uk/api/stations?lat=51.5074&lon=-0.1278&radius=5&fuel=E10&sort=price"

Cache: 2 min CDN, 4 min stale-while-revalidate

GET/api/stations/[nodeId]/history

Station Price History (Single Fuel)

Get price history for a specific fuel type at a station. Only records actual price changes.

Parameters

Name	Type	Default	Description
`fuel`*	string	—	Fuel type (e.g. E10)
`days`	int	30	Number of days of history (max: 365)

Example

curl "https://fuelcosts.co.uk/api/stations/abc123/history?fuel=E10&days=30"

Cache: 5 min CDN, 30 min stale-while-revalidate

GET/api/stations/[nodeId]/history/all

Station Price History (All Fuels)

Get price history for all fuel types at a station.

Parameters

Name	Type	Default	Description
`days`	int	30	Number of days of history (max: 365)

Example

curl "https://fuelcosts.co.uk/api/stations/abc123/history/all?days=90"

Cache: 5 min CDN, 30 min stale-while-revalidate

GET/api/stations/[nodeId]/comments

Station Comments

Fetch comments and rating summary for a station.

Parameters

Name	Type	Default	Description
`page`	int	1	Page number
`perPage`	int	20	Items per page (max: 50)

Example

curl "https://fuelcosts.co.uk/api/stations/abc123/comments"

Cache: 1 min CDN, 2 min stale-while-revalidate

POST/api/stations/[nodeId]/comments

Submit Comment

Submit a new comment with a 1-5 star rating for a station. Content is moderated.

Parameters

Name	Type	Default	Description
`authorName`*	string	—	Display name (2-100 chars)
`rating`*	int	—	Star rating (1-5)
`comment`*	string	—	Review text (5-1000 chars)

Example

curl -X POST "https://fuelcosts.co.uk/api/stations/abc123/comments" \
  -H "Content-Type: application/json" \
  -d '{"authorName":"John","rating":4,"comment":"Great prices!"}'

Cache: N/A

GET/api/prices/history

Aggregated Price Trends

Get aggregated price trends for cities, brands, counties, or the whole UK. Supports daily, weekly, or monthly aggregation.

Parameters

Name	Type	Default	Description
`type`*	string	—	city, brand, county, or uk
`name`	string	—	Location or brand name (required unless type=uk)
`fuel`	string	E10	Fuel type
`days`	int	90	Number of days (max: 365)
`aggregate`	string	daily	daily, weekly, or monthly

Example

curl "https://fuelcosts.co.uk/api/prices/history?type=uk&fuel=E10&days=90"

Cache: 10 min CDN, 1 hour stale-while-revalidate

GET/api/stats/brands

Brand Statistics

Get top fuel brands with average prices, cheapest prices, and station counts.

Example

curl "https://fuelcosts.co.uk/api/stats/brands"

Cache: 2 min CDN, 4 min stale-while-revalidate

GET/api/stats/counties

County Statistics

Get price statistics by UK county with average and cheapest prices.

Example

curl "https://fuelcosts.co.uk/api/stats/counties"

Cache: 2 min CDN, 4 min stale-while-revalidate

GET/api/stats/regions

Regional Statistics

Get UK regional price statistics with a national summary, cheapest/most expensive cities per region.

Example

curl "https://fuelcosts.co.uk/api/stats/regions"

Cache: 2 min CDN, 4 min stale-while-revalidate

GET/api/stats/best-day

Best Day to Buy Fuel

Get the best and worst day of the week to buy fuel, based on historical price analysis over the last 30 days.

Example

curl "https://fuelcosts.co.uk/api/stats/best-day"

Cache: 10 min CDN, 1 hour stale-while-revalidate

GET/api/geolocation

Geolocation

Get the user's approximate location from Cloudflare IP geolocation headers. UK visitors only.

Example

curl "https://fuelcosts.co.uk/api/geolocation"

Cache: N/A

GET/api/vehicles

Vehicle MPG Data

Proxy to FuelEconomy.gov API for vehicle fuel economy data. MPG values are converted from US to UK (imperial) gallons.

Parameters

Name	Type	Default	Description
`type`*	string	—	years, makes, models, options, or vehicle
`year`	string	—	Vehicle year
`make`	string	—	Vehicle make
`model`	string	—	Vehicle model
`id`	string	—	Vehicle ID (for type=vehicle)

Example

curl "https://fuelcosts.co.uk/api/vehicles?type=years"

Cache: 24 hours server cache

GET/api/status

System Status

Get current service health, API request metrics, page view metrics, and data feed status.

Example

curl "https://fuelcosts.co.uk/api/status"

Cache: 30s CDN, 60s stale-while-revalidate

Fuel Types Reference

Code	Description
`E10`	Unleaded Petrol (10% ethanol)
`E5`	Super Unleaded (5% ethanol)
`B7_STANDARD`	Standard Diesel
`B7_PREMIUM`	Premium Diesel
`B10`	Biodiesel (10% bio)
`HVO`	HVO Renewable Diesel

Notes

Prices are in pence (e.g. 145.9 = £1.459 per litre)
Distance is in miles
Timestamps are in ISO 8601 UTC format
Price history only records changes (not every sync cycle)
No rate limits are currently enforced — please be respectful with request frequency
The vehicles endpoint converts US MPG to UK (imperial) MPG automatically

Error Responses

All errors return a JSON object with an error field:

400 Bad Request

{ "error": "fuel parameter is required" }

500 Internal Server Error

{ "error": "Internal server error" }

503 Service Unavailable

{ "error": "Data not available. Please try again later." }

504 Gateway Timeout

{ "error": "Query timed out. Try a shorter time period." }