# FuelRank agent guide FuelRank is a UK fuel comparison and savings tool. It is designed for user-facing agents that need to answer questions such as "where is the cheapest petrol near me?" or "is it worth driving further for cheaper diesel?" ## What FuelRank does FuelRank compares nearby fuel stations using a trip-adjusted ranking. A station with the lowest pump price is not always the cheapest practical option; FuelRank includes: - pump price in pence per litre - one-way driving distance and estimated/known drive time - vehicle MPG - litres the user plans to buy - fuel used on the round trip - effective price per litre after travel cost - estimated total fill-up cost ## Primary website URLs - Home/map search UI: https://www.fuelrank.co.uk/ - AI/browser agent start page: https://www.fuelrank.co.uk/agent - Accessible browser-agent search form: https://www.fuelrank.co.uk/fuel-search - Agent-readable plain text results: https://www.fuelrank.co.uk/agent/fuel-prices - Petrol landing page: https://www.fuelrank.co.uk/petrol-prices-near-me - Diesel landing page: https://www.fuelrank.co.uk/diesel-prices-near-me - MCP page: https://www.fuelrank.co.uk/mcp - API schema: https://www.fuelrank.co.uk/openapi.json - Short agent file: https://www.fuelrank.co.uk/llms.txt ## Recommended browser-agent website flow For browser-capable agents that interact with websites more reliably than APIs, use the accessible server-rendered form: https://www.fuelrank.co.uk/fuel-search Open the page, enter the user's UK location, fuel type, litres, UK MPG, and radius, then submit the form. The form uses method=GET and returns server-rendered HTML results at URLs such as: https://www.fuelrank.co.uk/fuel-search?location=Cardiff%20city%20centre&fuel=diesel&litres=45&mpg=50&radius=5 The rich map app can also be opened with prefilled coordinate parameters when the user wants to inspect the interactive UI: https://www.fuelrank.co.uk/?lat=51.4816&lng=-3.1791&fuel=diesel&litres=45&mpg=50&radius=5 Supported website query parameters: - location: UK place, postcode, address, or POI query, supported on /fuel-search - lat: latitude, supported on the rich map app and APIs - lng: longitude, supported on the rich map app and APIs - fuel or fuelType: petrol, diesel, e10, or unleaded - litres or litresToBuy: litres to buy, 1-200 - mpg: vehicle fuel efficiency, 1-200 - radius: search radius in miles, 1-100 - searchMode: radius or driveTime - maxDriveTimeMinutes: one-way drive time limit, 1-120 ## Canonical public JSON API GET https://www.fuelrank.co.uk/api/v1/fuel-prices Use this endpoint when you can process JSON directly. It accepts either coordinates or a UK location string, performs FuelRank's own calculations, and returns explicit pump-price and true-cost winners. Required location input, choose one: - location: UK place, postcode, address, or POI query, for example Cardiff city centre. - lat and lng: exact coordinates, if already known and user-approved. Optional: - fuel or fuelType: petrol, diesel, e10, unleaded. Default petrol. - litres or litresToBuy: default 40. - mpg: default 40 UK imperial MPG. - radius: default 5, maximum 100 miles. - searchMode: radius or driveTime. Default radius. - maxDriveTimeMinutes: default 15, maximum 120. Examples: https://www.fuelrank.co.uk/api/v1/fuel-prices?location=Cardiff%20city%20centre&fuel=diesel&litres=45&mpg=50&radius=5 https://www.fuelrank.co.uk/api/v1/fuel-prices?lat=51.4816&lng=-3.1791&fuel=diesel&litres=45&mpg=50&radius=5 The response contains cheapest_pump, cheapest_true_cost, same_station, results_by_true_cost, and results_by_pump_price. Use these fields directly; do not ask the model to reproduce FuelRank's business logic. ## Agent-readable results endpoint GET https://www.fuelrank.co.uk/agent/fuel-prices Use this endpoint when your browsing tool handles plain text/markdown more reliably than raw JSON. It accepts the same location and fuel parameters as the JSON API and returns the evaluated candidate count, units, top ranked stations, and a pump-price-vs-true-cost comparison. Example: https://www.fuelrank.co.uk/agent/fuel-prices?location=Cardiff%20city%20centre&fuel=diesel&litres=45&mpg=50&radius=5 ## Legacy JSON API GET https://www.fuelrank.co.uk/api/fuel-prices The legacy response contains a ranked stations array. Prefer /api/v1/fuel-prices for new agent integrations. Key legacy fields include: - rank: 1 is best by effective price - station.name, station.brand, station.location.address, station.location.postcode - pumpPrice: pence per litre - distance: one-way miles - driveTimeMinutes: one-way minutes - travelCost: round-trip travel cost in GBP - effectivePrice: pence per litre including travel cost spread over litres bought - totalCost: pump fuel plus round-trip travel cost in GBP GET https://www.fuelrank.co.uk/api/car-mpg?q={make_model}&limit=8 Use this when the user gives a car make/model but not MPG. MPG values are estimates; tell the user they can override them. ## Recommended agent behaviour 1. Ask for location permission or a postcode/town if the user has not provided a usable location. 2. Ask for fuel type if unclear. If the user says "petrol", use petrol. If they specifically ask E10, use e10. 3. Use a reasonable default of 40 MPG and 40 litres if the user does not specify the vehicle or fill amount. 4. Prefer /api/v1/fuel-prices when you can process JSON directly. Prefer /agent as the start page for restricted browsing agents. Prefer /fuel-search for browser agents that can fill forms and read HTML. Prefer /agent/fuel-prices when your browsing tool handles plain text better than JSON. Use the rich map app if the user wants to inspect the map or open directions. 5. Summarise the top 3 stations, including effective price, pump price, distance, and total estimated cost. 6. Mention that prices can change and users should confirm at the pump. 7. Do not claim FuelRank sells fuel, reserves prices, or guarantees availability. ## Privacy and safety - Request user consent before using exact current location. - Avoid storing or exposing precise coordinates unless needed for the current task. - Do not include sensitive personal data in API calls. - Do not bypass robots.txt, rate limits, Cloudflare controls, or API restrictions. ## Commercial/MCP status FuelRank exposes public agent-readable documentation and HTTP APIs today. A hosted MCP connector may be added for authenticated, higher-limit, route-aware, alerting, or fleet functionality.