# Cheapest Fuel Prices & Gas Near Me API - ES, FR, IT & US (`rolescout/fuelscout-cheapest-fuel-prices`) Actor

Cheapest fuel prices near any location: station-level diesel, petrol (e5, e10, sp98) and LPG prices from Spanish, French and Italian government open data, plus official US EIA weekly regional averages. Smart ranking weighs the detour against the pump price. JSON/CSV rows, pay per query.

- **URL**: https://apify.com/rolescout/fuelscout-cheapest-fuel-prices.md
- **Developed by:** [Dave Fergins](https://apify.com/rolescout) (community)
- **Categories:** Travel, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 80.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$20.00 / 1,000 query answereds

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

Cheapest fuel prices near any point as plain JSON or CSV rows: station-level diesel, petrol (e5, e10, sp98) and LPG prices for Spain, France and Italy from each government's official open-data price feed, and the official EIA weekly average for the US as a whole, a PADD region or a covered state or city. One query is one country, one fuel grade and one point (or one US region); the answer is the cheapest stations around that point, cheapest first, or the one regional average. Prices are official open data and may be delayed; confirm at the pump.

The Actor is a thin client: it sends each query you give it to the fuel price service, charges one event per query the service answers, and writes the answer to the dataset as one summary row plus one row per station. A run takes seconds and uses 256 MB. You need no API key or account with any data provider; the Actor carries its own credential.

### Cheapest fuel stations near a point: Spain, France and Italy

For `country` ES, FR or IT the query is `lat`, `lon` and a `grade`, with an optional `radius` in km (the service's default is 10) and `limit` on the number of stations (default 10, at most 100). Each station row carries `brand`, `address`, `locality`, `lat`, `lon`, `dist_km` (straight-line distance from your point), `price` per litre in `currency` (EUR) and `rank`, cheapest first. The summary row for the query carries `kind` = stations, `count`, `country`, `grade` and `currency`.

Set `smart` to true to rank by all-in cost instead of pump price: the fuel you buy plus the fuel burned and the time spent on the round-trip detour. Five optional fields shape that estimate: `liters` you will buy (service default 40), vehicle `economy` in L/100 km (7), average detour `speed` in km/h (30), minutes of `wait` at the pump (3) and `time_value`, the value of your time per hour in the local currency (12). With smart ranking each station row adds `effective`, the all-in cost in the local currency, and rows are ordered by it.

### US fuel prices: official EIA weekly regional averages

For `country` US there are no station prices; the answer is the official US Energy Information Administration weekly average for a `region`: US for the national average, a PADD region, or a covered state or city such as CA, TX or NY. The summary row carries `kind` = regional_average, `region`, `region_id` (EIA's code), `price`, `prev_price` (the previous week), `change`, `period` (the week, YYYY-MM-DD), `unit` (for example $/GAL) and a `note` explaining why it is an average. The US has no `lpg` or `diesel_premium` series, and US diesel exists only for US, the PADD regions and California; the Actor refuses those combinations before sending anything.

### Several points or regions in one run

The top-level fields are the first query (when they name a point or a US region) and the defaults for every other. Add `points` as a list of "lat,lon" strings for more locations with the same country and grade, or `queries` as a list of objects using the same field names for anything else: a mix of countries, grades and points, or several US regions. A `queries` object that names its own point or region does not inherit the top-level one; one that only changes a setting (another grade, say) runs at the top-level point. A run may hold at most 25 queries, and each query the service answers is one billable event.

### Example input

```json
{
    "country": "ES",
    "lat": 40.4168,
    "lon": -3.7038,
    "grade": "diesel",
    "radius": 10,
    "limit": 10,
    "smart": true,
    "liters": 40,
    "economy": 7,
    "speed": 30,
    "wait": 3,
    "time_value": 12,
    "points": ["41.3874,2.1686"],
    "queries": [{ "country": "US", "region": "CA", "smart": false }]
}
```

That run is three queries: diesel around central Madrid with smart ranking, the same around Barcelona, and the EIA weekly diesel average for California. Field names are the service's own, so a `queries` object is exactly the query it sends.

### Output: example rows, CSV views and the OUTPUT record

Every row starts with the same eight columns: `scout`, `row_type` (summary or station), `query_index` (1-based position in the run), `query` (the normalised query as sent), `as_of` (when the first station's price was updated, or the EIA week), `receipt`, `source` (the attribution the open-data licence requires) and `disclaimer`. Then the row's own fields. A station row from Spain looks like this:

```json
{
    "scout": "fuel",
    "row_type": "station",
    "query_index": 1,
    "query": { "country": "ES", "grade": "diesel", "lat": 40.4168, "lon": -3.7038, "smart": "1" },
    "as_of": "2026-10-08T06:00:00Z",
    "receipt": "",
    "source": "Ministerio para la Transición Ecológica (MITECO) open data",
    "disclaimer": "Fuel prices are sourced from official government open data ...",
    "rank": 1,
    "brand": "REPSOL",
    "address": "CALLE DE ALCALA, 120",
    "locality": "MADRID",
    "lat": 40.4232,
    "lon": -3.6755,
    "dist_km": 2.5,
    "price": 1.409,
    "effective": 59.45,
    "currency": "EUR",
    "country": "ES",
    "grade": "diesel"
}
```

The dataset has two table views: `summary` (one line per query) and `stations` (one line per station). Filter on `row_type` when you export both as one CSV. The run's `OUTPUT` key-value record holds the service's response for every query verbatim, keyed q1, q2, ..., each with the query it answered, plus an `errors` map for any query that failed.

### Pricing: pay per query answered

One `query-answered` event per query the service answered, whatever the number of stations: one point is one event, ten points is ten events. Rows are never billed individually, so `limit` changes the size of the dataset, not the price. A query the service refuses (a point outside Spain, France or Italy, a grade the US has no series for, the service warming up) is not charged, and the run still succeeds with the queries that worked; only a run where every query failed ends as failed. Price: $0.02 per query answered, on every Apify plan. Example: a daily schedule of three points is about 90 queries a month, $1.80.

### Use cases: fuel price monitoring, fleet routing and spreadsheets

- Fuel price monitoring: schedule the run for the points you care about and read the dataset as JSON or CSV, with `as_of` on every row so a stale price is distinguishable from a fresh one.
- Fleet and delivery routing: smart ranking turns a pump price into the all-in cost of the detour for your vehicle's consumption and your time, per station.
- US fuel price tracking: the EIA weekly averages by state, city and PADD region in one table, with the previous week and the change.
- Spreadsheets and dashboards: export the `stations` view as CSV or attach Apify's Google Sheets integration so every scheduled run appends its rows.
- AI agents and automations: like any public Actor it can be called through the Apify API, a webhook or Apify's MCP server, with the same input and the same dataset.

### Data sources and attribution

Station prices come from the official open-data fuel price feeds published by the Spanish, French and Italian governments; US averages come from the US Energy Information Administration's weekly series. Every row carries the exact attribution the licence requires in `source`, and the service's disclaimer verbatim:

> Fuel prices are sourced from official government open data and may be delayed; confirm the price at the pump before purchasing. This is factual reference data, not advice.

### FAQ

**Which countries have station-level prices?** Spain, France and Italy, from each government's official open-data feed. The US has official weekly regional averages from the EIA, not station prices.

**Which fuel grades are available?** e5, e10, sp98, diesel, diesel_premium and lpg. The US has no lpg or diesel_premium series, and US diesel exists only for the national average, the PADD regions and California.

**How fresh are the prices?** Each answer carries `as_of`, the time the first station's price was updated in the government feed (or the EIA week for the US). Official open data can lag the pump by hours or days.

**What does smart ranking do?** It ranks stations by the all-in cost of filling up there: the fuel you buy at that pump price, plus the fuel burned and the time spent on the round-trip detour, from your litres, consumption, detour speed, pump wait and the value of your time. The `effective` field is that cost.

**Can I check several locations in one run?** Yes: `points` for more "lat,lon" locations with the same settings, or `queries` for a list of full query objects. At most 25 queries per run, one event each.

**Is the distance a driving distance?** No. `dist_km` is the straight-line distance from your point; smart ranking's detour estimate uses it with your average detour speed.

**Do I need an API key?** No. The Actor carries its own credential for the fuel price service; you only give it the queries.

**Why did one query fail while the others worked?** The service answers each query on its own; a query it cannot answer (a point with no stations in range, an unsupported grade for the US, a service still warming up) is recorded in the status message and the `OUTPUT` record's `errors` map, skipped without charge, and the rest continue. A query the service never answers (unreachable, or a gateway error) is retried once; after two such queries in a row the remaining ones are skipped rather than waited for.

**What happens with an empty input?** The run succeeds with one unbilled `status` row (`status: needs_input`) that names the missing fields, gives a hint and repeats the example input. Nothing is sent to the service and nothing is charged. Any field that is present must still be valid.

# Actor input Schema

## `country` (type: `string`):

ES, FR or IT for station-level prices near lat/lon; US for the official EIA weekly average of a region.

## `lat` (type: `number`):

Decimal degrees. Required for ES, FR and IT; ignored for US.

## `lon` (type: `number`):

Decimal degrees. Required for ES, FR and IT; ignored for US.

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

The US has no lpg or diesel_premium series, and US diesel exists only for US, the PADD regions and California.

## `region` (type: `string`):

Country US only, e.g. CA: US for the national average, a PADD region, or a covered state or city such as CA, TX or NY. Leave empty for the national average; it must stay empty for ES, FR and IT.

## `radius` (type: `number`):

Around lat/lon. The service's own default is 10 km.

## `limit` (type: `integer`):

Stations returned per query, 1 to 100. The service's own default is 10. It changes the dataset size, not the price.

## `smart` (type: `boolean`):

Rank stations by all-in cost: pump price plus the fuel burned and the time spent on the round-trip detour, using the five fields below.

## `liters` (type: `number`):

Only with smart ranking, e.g. 40; leave empty otherwise. The service's own default is 40.

## `economy` (type: `number`):

Only with smart ranking, e.g. 7; leave empty otherwise. The service's own default is 7.

## `speed` (type: `number`):

Only with smart ranking, e.g. 30; leave empty otherwise. The service's own default is 30.

## `wait` (type: `number`):

Only with smart ranking, e.g. 3; leave empty otherwise. The service's own default is 3.

## `time_value` (type: `number`):

Only with smart ranking, in the local currency, e.g. 12; leave empty otherwise. The service's own default is 12.

## `points` (type: `array`):

Extra "lat,lon" points, one query each, with the fields above as defaults. Each is one billable event; at most 25 queries per run.

## `queries` (type: `array`):

A list of query objects using the same field names as above, each merged over the top-level fields: mix countries, grades and points in one run. At most 25 queries per run in total.

## Actor input object example

```json
{
  "country": "ES",
  "lat": 40.4168,
  "lon": -3.7038,
  "grade": "diesel",
  "radius": 10,
  "limit": 10,
  "smart": false,
  "points": [
    "41.3874,2.1686"
  ],
  "queries": [
    {
      "country": "FR",
      "lat": 48.8566,
      "lon": 2.3522,
      "grade": "e10"
    }
  ]
}
```

# Actor output Schema

## `rows` (type: `string`):

Summary and station rows for every query, with the query object on each.

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

One line per query. Filter on row_type = summary.

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

One line per station, cheapest first per query. Filter on row_type = station.

## `answers` (type: `string`):

The service's response for each query verbatim, keyed q1, q2, ..., plus an errors map for any query that failed.

# 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 = {
    "country": "ES",
    "lat": 40.4168,
    "lon": -3.7038,
    "grade": "diesel"
};

// Run the Actor and wait for it to finish
const run = await client.actor("rolescout/fuelscout-cheapest-fuel-prices").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 = {
    "country": "ES",
    "lat": 40.4168,
    "lon": -3.7038,
    "grade": "diesel",
}

# Run the Actor and wait for it to finish
run = client.actor("rolescout/fuelscout-cheapest-fuel-prices").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 '{
  "country": "ES",
  "lat": 40.4168,
  "lon": -3.7038,
  "grade": "diesel"
}' |
apify call rolescout/fuelscout-cheapest-fuel-prices --silent --output-dataset

```

## MCP server setup

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

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/UFJYds6EXMq1L095C/builds/ODrBY2KloPwPJbdzN/openapi.json