We now have the facility to set up a Home Assistant sensor free of charge.
We have previously blocked HomeAssistant as, well, we were being hammered by it with calls every few seconds! However we would like to help the community who just want basic info about the price of heating oil.
To reduce pressure, we may cache results a little. Please try to respect the service as if it is hit too often, we may need to start returning error codes or disable it entirely. There should be no need to call this service more than once an hour, ideally once a day.
Returns the cheapest and average heating oil price per litre (pence) based on 900-litre quotes.
https://www.cheapestoil.co.uk/homeassistant/oilprice
| Parameter | Type | Description | |
|---|---|---|---|
| postcode | string | optional |
A Northern Ireland postcode. Either the outcode (BT11) or a full postcode (BT11 1AB) — the inward part is ignored.
If omitted, returns prices across all of Northern Ireland.
Only BT postcodes are accepted.
|
| Field | Type | Description |
|---|---|---|
| cheapest_ppl | number | Lowest price per litre in pence, rounded to 2 decimal places. |
| average_ppl | number | Mean price per litre across all matching suppliers, rounded to 2 decimal places. |
| postcode | string | null | The resolved outcode used to filter results. null when no postcode was supplied. |
| for_litres | number | The order quantity the prices are based on. Always 900. |
| last_updated | string (ISO 8601 UTC) | The time this data was fetched from the database. Results are cached for up to 1 hour, so this reflects when the cache was last populated, not the current time. |
| Status | Condition | Body |
|---|---|---|
| 400 | Postcode supplied but is not a Northern Ireland (BT) postcode, or cannot be parsed. |
{"error": "Only Northern Ireland postcodes (BT...) are accepted"} |
| 404 | No prices found for the given postcode area. | {"error": "No prices found"} |
Responses are cached server-side for 60 minutes. The last_updated field shows when the current cached value was computed.
Add one or more rest sensors to your configuration.yaml. Each sensor below polls the endpoint and extracts a single field.
last_updated as a separate sensorTip: Set scan_interval: 3600 (1 hour) to match the server-side cache. Polling more frequently will return the same cached value and add unnecessary load.