API Documentation | FuelFinder Scotland

FuelFinder API Documentation

The FuelFinder REST API provides programmatic access to fuel price data across 225 Scottish locations. All endpoints return JSON and use official UK Government fuel price data.

Base URL

https://fuelfinder.scot/api/v1

Endpoints

`GET /locations`

Returns a list of all 225 Scottish locations with their coordinates and default search radii.

Example Request:

curl https://fuelfinder.scot/api/v1/locations

Response:

{
  "status": "success",
  "locations": [
    {
      "id": "edinburgh",
      "name": "Edinburgh",
      "district": "City of Edinburgh",
      "type": "City",
      "latitude": 55.953,
      "longitude": -3.189,
      "defaultRadiusMiles": 5.0
    },
    ...
  ],
  "locationCount": 225
}

`GET /locations/{locationId}`

Returns fuel price data for a specific location, including cheapest station, best value station, and all nearby stations sorted by price.

Path Parameters:

locationId (required) - Location identifier (e.g., 'edinburgh', 'glasgow', 'aberdeen')

Query Parameters:

Parameter	Type	Default	Description
`fuelType`	string	`unleaded`	Fuel type: `unleaded` or `diesel`
`radius`	number	location-specific	Search radius in miles (max: 100)

Example Request:

curl "https://fuelfinder.scot/api/v1/locations/edinburgh?fuelType=diesel&radius=10"

Response:

{
  "status": "success",
  "location": {
    "id": "edinburgh",
    "name": "Edinburgh",
    "district": "City of Edinburgh",
    "type": "City",
    "latitude": 55.953,
    "longitude": -3.189,
    "defaultRadiusMiles": 5.0
  },
  "fuelType": {
    "id": "diesel",
    "name": "Diesel"
  },
  "radius": 10.0,
  "cheapest": {
    "id": "station-123",
    "name": "Tesco Edinburgh",
    "price": 135.9,
    "formattedPrice": "135.9",
    "distance": 2.3,
    "priceCategory": "GOOD",
    "lastUpdated": "2 hours ago",
    ...
  },
  "bestValue": { ... },
  "stations": [ ... ],
  "stationCount": 47
}

Error Responses

All error responses include a status field set to "error" and an error field with a description.

404 Not Found:

{
  "status": "error",
  "error": "Unknown location: xyz"
}

500 Internal Server Error:

{
  "status": "error",
  "error": "An unexpected error occurred. Please try again later."
}

Interactive Documentation

For interactive API documentation with request/response examples and the ability to test endpoints directly in your browser, visit:

Open Swagger UI

Rate Limits

The API enforces IP-based rate limiting to ensure fair usage:

Limit	Value	Response on Exceeded
Requests per minute	100 per IP address	HTTP 429 (Too Many Requests)

Rate Limit Headers:

All API responses include rate limit information in headers:

X-RateLimit-Limit: 100 - Maximum requests allowed per minute
X-RateLimit-Remaining: 95 - Requests remaining in current window
Retry-After: 60 - Seconds to wait before retrying (only when limited)

429 Error Response:

{
  "status": "error",
  "error": "Rate limit exceeded. Maximum 100 requests per minute allowed."
}

Usage Notes:

Rate limits apply per IP address (supports X-Forwarded-For header)
No authentication required - API is free to use within rate limits
Data is updated regularly but prices can change rapidly - always verify before filling up
If you need higher limits for production use, please contact us

Note: This API uses official UK Government fuel price data. While we strive for accuracy, prices are provided by retailers and may not be up-to-date. Always verify prices before refueling.