# UK Fuel Prices API: Forecourt Prices and Every Change (`arjs1000/uk-fuel-prices-enriched`) Actor

Current pump prices for over 8,000 UK forecourts and a feed of every price change, with the forecourt's own timestamp. Plus UK weekly prices back to 2003 and Advisory Fuel Rates against real pump cost per mile.

- **URL**: https://apify.com/arjs1000/uk-fuel-prices-enriched.md
- **Developed by:** [Arjun Shankar](https://apify.com/arjs1000) (community)
- **Categories:** Travel, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UK Fuel Prices API: Forecourt Prices and Every Change

Current pump prices for over 8,000 UK forecourts, a feed of every price change as it happens,
and the national weekly series back to 2003.

Pull a full snapshot of forecourt prices by grade, or schedule the change feed and get only what
moved since your last run: forecourt, grade, old price, new price and the forecourt's own
timestamp. Fleet and finance teams also get HMRC's Advisory Fuel Rates set against real pump
cost per mile.

Run it with the default input: today's UK fuel price summary.

### Who uses it

- **App and price-comparison developers** get bulk station prices with change events, instead
  of re-downloading everything every few minutes.
- **Fleet managers and expense teams** see whether the official mileage rates cover what drivers
  pay at the pump.
- **Analysts and economists** track how Brent and duty feed through to UK pump prices since
  2003\.
- **Journalists** get a dated, sourced answer to "what did diesel cost last week".

### Input

| Field | What it does |
|---|---|
| `mode` | `energy_context` (default), `changes`, `snapshot`, `weekly_prices`, `trend_report` or `fleet_afr` |
| `grade` | `E10`, `E5`, `B7S`, `B7P`, `B10` or `HVO` |
| `since` | Changes since a date. Empty means the last 24 hours |
| `sinceLastRun` | `true` returns only changes newer than your last run. Best for schedules |
| `brand` | Filter by brand, e.g. `TESCO` |
| `sort` | Snapshot order: station id, price or most recently updated |
| `from`, `to`, `month` | Date range for `weekly_prices`, month for `trend_report` |
| `mpg` | Your fleet's MPG for `fleet_afr`. Empty uses the official figure |
| `maxItems` | Caps the rows, and so the cost |

`postcode_cheapest` (cheapest near a postcode) and `station_history` are coming soon.

### Output

Each change carries `trading_name`, `brand_name`, `postcode`, `grade`, `change_type`,
`price_before_pence`, `price_after_pence`, `delta_pence`, `effective_at` and `observed_at`.
Snapshot rows carry the forecourt's address, coordinates, amenities and a price per grade with
its own timestamp. Every row has a `price_source` and keeps a `report_discrepancy_url` for flagging
a wrong price.

A real change from 8 October 2026:

```json
{
  "trading_name": "BARNES EXPRESS",
  "brand_name": "TESCO",
  "postcode": "SW13 9EW",
  "grade": "E10",
  "change_type": "changed",
  "price_before_pence": 175.9,
  "price_after_pence": 174.9,
  "delta_pence": -1,
  "effective_at": "2026-10-08T14:49:19.000Z",
  "observed_at": "2026-10-08T14:57:04.946Z"
}
```

`energy_context` gives the latest UK weekly petrol and diesel prices with weekly and yearly
change, fuel duty, VAT, the Advisory Fuel Rates in force and Brent crude.

### Pricing

Pay per result. See the Pricing tab for current rates; `maxItems` caps the rows and so the cost. A run that finds nothing charges nothing per item.

### FAQ

**How fresh are forecourt prices?** Forecourts report changes under a statutory scheme, and each
row keeps the forecourt's own timestamp. Change history starts on 8 October
2026\.

**What if forecourt reporting goes quiet?** Prices are cross-checked every day against
independent retailer price lists, and more than nine in ten agree to the penny. If forecourt data
goes stale, stations those lists cover switch to the retailer's price, and `price_source` says
which you got.

**Will a schedule charge me twice?** Not with `sinceLastRun: true`. Each run returns only
changes you have not had.

**Does it cover Northern Ireland?** No. Great Britain only.

Contains public sector information licensed under the Open Government Licence v3.0. Brent crude
prices from public-domain U.S. government data. Every run carries the full attribution in an
`attribution` field. Runs record anonymous usage counts only, never your
inputs or results.

# Actor input Schema

## `mode` (type: `string`):

energy_context: latest of every context series in one row. weekly_prices: DESNZ UK average pump prices since June 2003. trend_report: one month's report. fleet_afr: HMRC Advisory Fuel Rates against pump cost per mile. changes, snapshot, postcode_cheapest, station_history: forecourt-level data from Fuel Finder.

## `grade` (type: `string`):

E10 and E5 petrol, B7S standard diesel, B7P premium diesel, B10, HVO. Used by changes, snapshot, postcode_cheapest, station_history and fleet_afr.

## `postcode` (type: `string`):

Full postcode or outward code in Great Britain (Northern Ireland BT postcodes are not supported). Required for postcode_cheapest; optional filter for changes and snapshot.

## `radiusKm` (type: `integer`):

Search radius around the postcode, 1 to 50 km.

## `brand` (type: `string`):

Optional filter, exact brand name as published (case-insensitive). Results are never ordered by brand.

## `sort` (type: `string`):

Objective orderings only.

## `since` (type: `string`):

Mode changes only. Date in YYYY-MM-DD. Leave empty for the last 24 hours.

## `sinceLastRun` (type: `boolean`):

Mode changes only. Turn this on for scheduled runs. Each run returns only price changes newer than the last run that had it on, so you never pay twice for the same item. The actor saves its place in a key-value store called uk-fuel-prices-enriched-cursor in your own Apify account. The first run has no saved place and uses the default window. A date in "Changes since" overrides the saved place for that run. A failed or aborted run does not move it.

## `cursorName` (type: `string`):

Used with "Only new since the last run". The name of the record that holds the saved place. Leave it empty and each mode and set of filters gets its own. Give two tasks the same name only if they should share one place.

## `nodeId` (type: `string`):

Mode station_history only. The forecourt's Fuel Finder node_id, as returned by the other modes.

## `from` (type: `string`):

station_history and weekly_prices. YYYY-MM-DD.

## `to` (type: `string`):

station_history and weekly_prices. YYYY-MM-DD.

## `month` (type: `string`):

YYYY-MM. Leave empty for the latest complete month.

## `area` (type: `string`):

Postcode area (for example SW) or outward code (for example SW1A). Applies to the forecourt-level parts.

## `mpg` (type: `number`):

Leave empty to use HMRC's own mean MPG for each engine band.

## `maxItems` (type: `integer`):

Stop after this many dataset items. Station-level modes charge one event per item; report modes charge one event per run whatever the row count.

## Actor input object example

```json
{
  "mode": "energy_context",
  "radiusKm": 5,
  "sort": "node_id",
  "sinceLastRun": false,
  "maxItems": 10
}
```

# Actor output Schema

## `stations` (type: `string`):

Current pump prices by grade for each forecourt, or the cheapest near a postcode.

## `changes` (type: `string`):

Every forecourt price change since your date or last run.

## `history` (type: `string`):

Daily prices for one forecourt over the period you choose.

## `weekly_prices` (type: `string`):

Average UK pump prices by week.

## `energy_context` (type: `string`):

This week's average pump prices and weekly change, with duty, VAT, crude oil and mileage rates.

## `fleet_afr` (type: `string`):

Mileage rates set against what fuel actually costs per mile.

## `trend_report` (type: `string`):

Month-by-month price movement by grade.

## `summary` (type: `string`):

What this run returned: mode, item count, data freshness and the cursor for your next run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("arjs1000/uk-fuel-prices-enriched").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "maxItems": 10 }

# Run the Actor and wait for it to finish
run = client.actor("arjs1000/uk-fuel-prices-enriched").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 10
}' |
apify call arjs1000/uk-fuel-prices-enriched --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arjs1000/uk-fuel-prices-enriched"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SDkmM7vz6aMZGCTGr/builds/bC6BvfCUW45vIxq44/openapi.json