{"openapi":"3.1.0","info":{"title":"FuelRank Public API","version":"0.1.0","description":"Find cheap UK petrol and diesel stations ranked by true cost, including pump price, distance, vehicle MPG, and litres to buy."},"servers":[{"url":"https://www.fuelrank.co.uk"}],"paths":{"/api/v1/fuel-prices":{"get":{"operationId":"findFuelPricesCanonical","summary":"Find UK fuel stations with explicit pump-price and true-cost rankings","description":"Canonical FuelRank JSON API for agents and apps. Accepts either a UK location string or user-approved latitude/longitude. Returns FuelRank-calculated cheapest_pump, cheapest_true_cost, same_station, results_by_true_cost, and results_by_pump_price so agents do not need to recalculate rankings.","parameters":[{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"UK place, postcode, address, or point of interest to geocode, for example Cardiff city centre. Use this when exact coordinates are not already known."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude of the search origin. Use with lng instead of location, after user consent for precise location."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude of the search origin. Use with lat instead of location, after user consent for precise location."},{"name":"fuel","in":"query","required":false,"schema":{"type":"string","enum":["petrol","diesel","e10","unleaded"]},"description":"Fuel type. unleaded is treated as petrol. Defaults to petrol."},{"name":"litres","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Litres the user plans to buy."},{"name":"mpg","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Vehicle fuel economy in UK imperial miles per gallon. Do not supply US MPG."},{"name":"radius","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100,"default":5},"description":"Maximum one-way station search radius in miles when searchMode is radius."},{"name":"searchMode","in":"query","required":false,"schema":{"type":"string","enum":["radius","driveTime"],"default":"radius"},"description":"Use radius miles or a one-way drive-time limit."},{"name":"maxDriveTimeMinutes","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":120,"default":15},"description":"One-way drive-time limit when searchMode is driveTime."}],"responses":{"200":{"description":"Canonical FuelRank response with explicit true-cost and pump-price rankings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CanonicalFuelPricesResponse"}}}},"400":{"description":"Invalid query parameters or unresolved location."},"500":{"description":"Fuel price lookup failed."}}}},"/agent/fuel-prices":{"get":{"operationId":"getFuelPricesPlainTextForAgents","summary":"Get nearby fuel stations as an agent-readable plain text ranking","description":"Returns the same trip-adjusted FuelRank result as the JSON API, formatted as plain text/markdown for browsing-based agents.","parameters":[{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"UK place, postcode, address, or point of interest to geocode. Use instead of lat/lng when coordinates are not already known."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude of the search origin. Use with lng instead of location."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude of the search origin. Use with lat instead of location."},{"name":"fuel","in":"query","required":false,"schema":{"type":"string","enum":["petrol","diesel","e10","unleaded"]},"description":"Fuel type. Defaults to petrol."},{"name":"litres","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Litres the user plans to buy."},{"name":"mpg","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Vehicle fuel economy in UK miles per gallon."},{"name":"radius","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100,"default":5},"description":"Search radius in miles."}],"responses":{"200":{"description":"Plain text fuel ranking.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid query parameters."},"500":{"description":"Fuel price lookup failed."}}}},"/api/fuel-prices":{"get":{"operationId":"findFuelPricesByTrueCost","summary":"Find nearby fuel stations ranked by trip-adjusted cost","description":"Legacy endpoint returning UK fuel stations near a latitude/longitude or location query sorted by effective price per litre after round-trip travel cost is included. Prefer /api/v1/fuel-prices for new agent integrations.","parameters":[{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"UK place, postcode, address, or point of interest to geocode. Use instead of lat/lng when coordinates are not already known."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude of the search origin. Use with lng instead of location."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude of the search origin. Use with lat instead of location."},{"name":"fuel","in":"query","required":false,"schema":{"type":"string","enum":["petrol","diesel","e10","unleaded"]},"description":"Fuel type. Alias of fuelType."},{"name":"fuelType","in":"query","required":false,"schema":{"type":"string","enum":["petrol","diesel","e10","unleaded"]},"description":"Fuel type. Defaults to petrol."},{"name":"litres","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Litres the user plans to buy. Alias of litresToBuy."},{"name":"litresToBuy","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Litres the user plans to buy."},{"name":"mpg","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":200,"default":40},"description":"Vehicle fuel economy in UK miles per gallon."},{"name":"radius","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":100,"default":5},"description":"Search radius in miles when searchMode is radius."},{"name":"searchMode","in":"query","required":false,"schema":{"type":"string","enum":["radius","driveTime"],"default":"radius"},"description":"Use radius miles or a one-way drive-time limit."},{"name":"maxDriveTimeMinutes","in":"query","required":false,"schema":{"type":"number","minimum":1,"maximum":120,"default":15},"description":"One-way drive-time limit when searchMode is driveTime."}],"responses":{"200":{"description":"Ranked fuel station results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelPricesResponse"}}}},"400":{"description":"Invalid query parameters."},"500":{"description":"Fuel price lookup failed."}}}},"/api/car-mpg":{"get":{"operationId":"searchCarMpgEstimates","summary":"Search estimated MPG by car make/model","description":"Looks up estimated UK MPG values for common cars. Values are estimates and should be presented as overrideable.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Car make/model search text, for example ford fiesta diesel."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"Maximum number of matches."}],"responses":{"200":{"description":"Car MPG search results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarMpgResponse"}}}}}}}},"components":{"schemas":{"CanonicalFuelPricesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"query":{"type":"object","properties":{"input_location":{"type":["string","null"]},"resolved_location":{"type":["string","null"]},"lat":{"type":"number"},"lng":{"type":"number"},"fuel":{"type":"string","enum":["petrol","diesel","e10"]},"litres":{"type":"number"},"mpg":{"type":"number","description":"UK imperial miles per gallon."},"radius_miles":{"type":"number"},"search_mode":{"type":"string","enum":["radius","driveTime"]},"max_drive_time_minutes":{"type":["number","null"]}}},"generated_at":{"type":"string","format":"date-time"},"data_source":{"type":"string"},"station_count":{"type":"integer"},"cheapest_pump":{"anyOf":[{"$ref":"#/components/schemas/CanonicalFuelResult"},{"type":"null"}]},"cheapest_true_cost":{"anyOf":[{"$ref":"#/components/schemas/CanonicalFuelResult"},{"type":"null"}]},"same_station":{"type":"boolean","description":"Whether cheapest_pump and cheapest_true_cost refer to the same station."},"results_by_true_cost":{"type":"array","items":{"$ref":"#/components/schemas/CanonicalFuelResult"}},"results_by_pump_price":{"type":"array","items":{"$ref":"#/components/schemas/CanonicalFuelResult"}},"units":{"type":"object"},"notes":{"type":"array","items":{"type":"string"}}}},"CanonicalFuelResult":{"type":"object","properties":{"rank":{"type":"integer","description":"Rank by FuelRank true cost."},"pump_price_rank":{"type":"integer","description":"Rank by pump price when present in results_by_pump_price."},"station_id":{"type":"string"},"station_name":{"type":"string"},"brand":{"type":["string","null"]},"address":{"type":"string"},"postcode":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"price_pence_per_litre":{"type":"number"},"pump_cost_gbp":{"type":"number"},"distance_miles":{"type":"number","description":"One-way driving distance in miles."},"round_trip_distance_miles":{"type":"number"},"drive_time_minutes":{"type":"number","description":"One-way drive time in minutes."},"drive_time_source":{"type":"string","enum":["route","estimate"]},"estimated_journey_fuel_litres":{"type":"number"},"journey_cost_gbp":{"type":"number","description":"Estimated round-trip travel fuel cost."},"true_cost_gbp":{"type":"number","description":"Pump cost plus estimated round-trip journey cost."},"effective_price_pence_per_litre":{"type":"number"},"price_updated_at":{"type":"string","format":"date-time"}}},"FuelPricesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"},"userLocation":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"preferences":{"$ref":"#/components/schemas/UserPreferences"},"stations":{"type":"array","items":{"$ref":"#/components/schemas/StationCalculation"}},"dataSource":{"type":"string"}},"required":["success","count","userLocation","preferences","stations"]},"UserPreferences":{"type":"object","properties":{"mpg":{"type":"number"},"fuelType":{"type":"string","enum":["petrol","diesel","e10"]},"litresToBuy":{"type":"number"},"radius":{"type":"number"},"searchMode":{"type":"string","enum":["radius","driveTime"]},"maxDriveTimeMinutes":{"type":"number"}}},"StationCalculation":{"type":"object","properties":{"rank":{"type":"integer"},"station":{"$ref":"#/components/schemas/FuelStation"},"distance":{"type":"number","description":"One-way miles."},"driveTimeMinutes":{"type":"number","description":"One-way minutes."},"driveTimeSource":{"type":"string","enum":["route","estimate"]},"pumpPrice":{"type":"number","description":"Pence per litre."},"travelCost":{"type":"number","description":"Round-trip travel cost in GBP."},"effectivePrice":{"type":"number","description":"Pence per litre including travel cost spread across litres bought."},"totalCost":{"type":"number","description":"Pump fuel plus round-trip travel cost in GBP."}}},"FuelStation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brand":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"address":{"type":"string"},"postcode":{"type":"string"}}},"prices":{"type":"object","properties":{"petrol":{"type":"number"},"diesel":{"type":"number"},"e10":{"type":"number"}}},"lastUpdated":{"type":"string","format":"date-time"}}},"CarMpgResponse":{"type":"object","properties":{"success":{"type":"boolean"},"cars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"variant":{"type":"string"},"years":{"type":"string"},"fuelType":{"type":"string","enum":["petrol","diesel"]},"mpg":{"type":"number"},"source":{"type":"string"}}}}}}}},"externalDocs":{"description":"FuelRank agent guide","url":"https://www.fuelrank.co.uk/llms-full.txt"}}