{
  "openapi": "3.1.0",
  "info": {
    "title": "Cheapest Fuel UK fuel prices API",
    "version": "1.0.0",
    "summary": "Live petrol and diesel prices at every UK forecourt.",
    "description": "Free, keyless JSON API for UK pump prices from the government's Fuel Finder scheme, refreshed twice a day and quality-checked (prices 100–300p, reported in the last 30 days, UK locations, duplicates removed). Prices are in pence per litre. Contains public sector information licensed under the Open Government Licence v3.0. Please credit Cheapest Fuel (cheapestfuelnearme.co.uk).",
    "contact": { "name": "Cheapest Fuel", "email": "hello@cheapestfuelnearme.co.uk", "url": "https://cheapestfuelnearme.co.uk/developers" },
    "license": { "name": "Open Government Licence v3.0 (data)", "url": "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" }
  },
  "servers": [{ "url": "https://cheapestfuelnearme.co.uk" }],
  "paths": {
    "/api/stations": {
      "get": {
        "operationId": "findStations",
        "summary": "Forecourts near a point, cheapest or nearest first",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 53.4808 },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -2.2426 },
          { "name": "fuel", "in": "query", "schema": { "type": "string", "enum": ["E10", "E5", "B7"], "default": "E10" }, "description": "E10 standard petrol, E5 super unleaded, B7 diesel" },
          { "name": "radius", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 50, "default": 10 } },
          { "name": "unit", "in": "query", "schema": { "type": "string", "enum": ["mi", "km"], "default": "mi" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["cheapest", "nearest"], "default": "cheapest" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": { "description": "Stations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StationsResponse" } } } },
          "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/summary": {
      "get": {
        "operationId": "ukSummary",
        "summary": "UK averages and the five cheapest stations for petrol and diesel",
        "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } } }
      }
    },
    "/api/postcode/{postcode}": {
      "get": {
        "operationId": "lookupPostcode",
        "summary": "Coordinates for a UK postcode (postcodes.io proxy)",
        "parameters": [{ "name": "postcode", "in": "path", "required": true, "schema": { "type": "string" }, "example": "M11AE" }],
        "responses": {
          "200": { "description": "postcodes.io result; use result.latitude and result.longitude" },
          "400": { "description": "Not a valid UK postcode" },
          "404": { "description": "Postcode not found" }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "health",
        "summary": "Data freshness and quality-filter statistics",
        "responses": { "200": { "description": "Status" } }
      }
    },
    "/data/uk-towns.csv": {
      "get": { "operationId": "townsCsv", "summary": "Average and cheapest prices for every town with 5+ forecourts (CSV)", "responses": { "200": { "description": "CSV", "content": { "text/csv": {} } } } }
    },
    "/data/towns/{town}.csv": {
      "get": {
        "operationId": "townCsv", "summary": "Every forecourt in a town with prices and report times (CSV)",
        "parameters": [{ "name": "town", "in": "path", "required": true, "schema": { "type": "string" }, "example": "leeds" }],
        "responses": { "200": { "description": "CSV", "content": { "text/csv": {} } }, "404": { "description": "Unknown town" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Station": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "brand": { "type": "string" },
          "address": { "type": "string" },
          "city": { "type": "string" },
          "postcode": { "type": "string" },
          "lat": { "type": "number" },
          "lon": { "type": "number" },
          "is24h": { "type": "boolean" },
          "prices": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Pence per litre by fuel code" },
          "updated": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "When each price was reported" },
          "price": { "type": "number", "description": "Price for the requested fuel" },
          "distance": { "type": "number", "description": "Straight-line distance in the requested unit" },
          "distanceKm": { "type": "number" },
          "path": { "type": "string", "description": "Station page path on cheapestfuelnearme.co.uk" }
        }
      },
      "StationsResponse": {
        "type": "object",
        "properties": {
          "query": { "type": "object" },
          "lastUpdated": { "type": "string", "format": "date-time" },
          "total": { "type": "integer" },
          "stations": { "type": "array", "items": { "$ref": "#/components/schemas/Station" } }
        }
      },
      "Summary": {
        "type": "object",
        "properties": {
          "lastUpdated": { "type": "string", "format": "date-time" },
          "stationCount": { "type": "integer" },
          "E10": { "type": "object" },
          "B7": { "type": "object" }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  }
}