Get a free API key
Create your own key below and start using it straight away. No account or email needed. Each key allows 60 requests per hour. For a home dashboard, checking once an hour is plenty.
Only need the general price trend? The open price feed needs no key at all.
Make a request
The key can also travel in an X-Api-Key header instead of the query string.
| Parameter | Required | Meaning |
|---|---|---|
| key | yes | Your API key (or send it as an X-Api-Key header). |
| postcode | yes | A full UK postcode, e.g. MK40 1AA. Validated against the full UK postcode file. |
| litres | no | How much oil. Defaults to 1000. |
| fuel | no | kerosene (default, standard heating oil), premium (premium kerosene for boilers; premium_kerosene and the older gasoil mean the same), or aga (AGA / range cooker oil, kerosene with a range cooker additive). |
| tanker | no | normal (default), small or baby for restricted access. |
What comes back
Current quotes, cheapest first. Totals include 5% VAT. delivery_by is a real date - weekends, bank holidays and the 2pm cut-off are already accounted for.
If nobody delivers to that postcode yet, you get "covered": false with an honest explanation and the same order_url - the page there lets the customer leave an email address to be told when their area is covered.
Errors
| Status | Meaning |
|---|---|
| 400 | The postcode isn't a valid UK postcode. |
| 401 | Missing, unknown or disabled key. |
| 429 | The key has used its hourly allowance - try again later. |
Ground rules
- When you show a customer a price from this API, link them to the order_url that came with it - that's where they can actually order, and prices there match exactly.
- Supplier identities are deliberately not in the responses; customers see who their supplier is at checkout.
- The data is for showing people current prices, not for bulk harvesting or resale as a dataset.
Use Fueltool in ChatGPT or Claude
Fueltool has a connector for AI assistants (an MCP server). Add it once and you can ask your assistant what heating oil costs delivered to your postcode: it gets the live quotes, cheapest first, with VAT-inclusive totals, delivery dates and a link that opens Fueltool on the same prices, ready to order. No account, no key.
- Claude: Settings > Connectors > Add custom connector, then paste the address above.
- ChatGPT: turn on developer mode in Settings, then add a new connector with the address above.
- Any other MCP client: Streamable HTTP, no authentication.
Three tools: get_heating_oil_quotes (postcode and litres in, live quotes out; fuel and tanker size optional), start_heating_oil_order (prepares an order for one of those quotes and returns a link to our order page with the details filled in; nothing is ordered until the person checks it and presses Confirm there, and the link lasts 24 hours) and get_uk_heating_oil_price (today's UK average for 500 to 2,000 litres and its daily history). Supplier names are not included in the tools' answers, and no card details are taken online: the chosen supplier phones the customer to take payment. Requests are covered by our privacy policy; questions to support@fueltool.co.uk.
For AI assistants - no key
An assistant answering someone in a conversation can quote them without a key. Same prices and the same rules as the keyed API: cheapest first, VAT-inclusive totals, real delivery dates, no supplier names.
It takes the same postcode, litres, fuel and tanker parameters and returns the same shape. Each quote has its own order_url, which opens our order page on that quote, ready to confirm, with the other prices for the postcode under it; the top order_url is the cheapest one's. Links last 24 hours, and the price is checked again when the page opens. No card details are taken online: the chosen supplier phones the customer to take payment. It allows 30 requests an hour from one address, with an overall hourly cap; for anything heavier, create a free key above. Never put a person's name, address or email into a link.
Linking someone straight to their prices works without any API at all: https://www.fueltool.co.uk/results?postcode=CH71LA&litres=500
The price tracker - open, no key
The average across Fueltool's UK heating oil price listings, today and back through time, is a separate open feed - no key needed. Free to use with attribution and a link back to fueltool.co.uk. Historical figures are frozen: a past day's average never changes after the fact, so a number you quote stays quotable.
Returns today's average (pence per litre, ex VAT, standard kerosene) and what 1,000 litres costs at that price with VAT, the change over the last week and month, and a daily series (days from 7 to 730).
For one county, add county, the name from the county page's address: GET https://www.fueltool.co.uk/api/v1/price/?county=flintshire. The response gains a county object with the same figures as that county's page: from_ppl, the cheapest price a litre ex VAT for 1,000-1,499 litres across the county's postcode areas that a supplier covers today, and fill_1000_litres_gbp_inc_vat, or "local_price": false where there is no local figure today. The series is 90 days in county mode, and an unknown county is a 404.
The same figures as pages to read or link to: heating oil prices today, with the chart and a daily table, and every month since 2011 on the heating oil price history page.
Using the data in Home Assistant
Use a RESTful sensor to read either endpoint, with a polling interval of 3,600 seconds. For the open feed, read today.average_ppl. It is a general Fueltool average for standard kerosene in the 1,000-1,499 litre band, rather than a quote for your home.
For local prices, use the quote API with your postcode, usual order size and your key in the X-Api-Key header. Handle covered: false or an empty quotes list as unavailable, not as a zero price. Both feeds' pence-per-litre figures exclude VAT; quote totals include VAT.
Put the tracker on your own site
The free heating oil price box puts today's price for a county, or for the UK, on any website: pick a county on that page and copy the code. Or write it yourself:
The link is a normal link in your page. The script reads the county from it (/heating-oil/<county>; a link to /heating-oil-prices gives the UK box) and draws a small live tile around it that can't clash with your site's styling: the county's lowest price today where there is one, the UK average with its move on the week, and a 90-day price line. If the script can't run, the plain link stays. Add data-theme="dark" to the div for the dark tile. The link's words are yours to change; the box always shows the county the link points to.
The one-line version still works: <script src="https://www.fueltool.co.uk/tracker.js" async></script> on its own draws the UK tile right after the script tag, with data-theme="dark" and data-days="180" as options on the script tag.
For machines
- MCP server for AI assistants, no key: https://www.fueltool.co.uk/mcp (see Use Fueltool in ChatGPT or Claude).
- OpenAPI spec for assistants, no key: /api/v1/openapi-assistant.json - import this URL into a ChatGPT custom GPT, Claude tool definition or any agent framework with no authentication and it wires itself up.
- Full OpenAPI spec, including the keyed quote API: /api/v1/openapi.json
- Site pointer for AI crawlers: /llms.txt