# Spain Fuel Prices - Ministry Open Data (unofficial) (`rianone/spain-fuel-prices`) Actor

Fuel prices for ~11,500 Spanish service stations from the official Ministry open-data feed (MINCOTUR). Find the cheapest station near any coordinates or filter by province, brand and fuel. Refreshed every 30 min; ready-to-open CSV/Excel included. Unofficial: not affiliated with the Spanish Ministry.

- **URL**: https://apify.com/rianone/spain-fuel-prices.md
- **Developed by:** [Riccardo Pongetti](https://apify.com/rianone) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 station results

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

## Spain Fuel Prices API – Official Gas Station Data

Query **official Spanish fuel prices** for 11,000+ gasolineras across Spain. This Apify Actor reads the Ministry's public MINCOTUR feed, filters the feed, and returns one structured result per matching station.

Use it for **precio gasolina** lookups, fuel-price monitoring, location-based search, spreadsheets, automations, and AI agents. No third-party scraping, API key, cookies, or affiliation with the Ministry is required.

### What this Actor does

- Finds the cheapest fuel near latitude/longitude coordinates.
- Filters by radius, province, municipality, brand, fuel, and maximum price.
- Downloads one official province source file when `provinceIds` contains exactly one ID.
- Returns a complete Spain-wide dataset when no province optimization is selected.
- Includes price statistics in a free `SUMMARY` key-value record.
- Creates ready-to-open CSV and XLSX files for every run by default.
- Works with Apify API calls, n8n, Make, MCP-based agents, and custom applications.

The source feed is refreshed by the Ministry approximately every 30 minutes. Each station result includes its source attribution and the source update timestamp.

### Pricing

Pay only for the value returned:

| Charge | Price |
|---|---:|
| Execution start | $0.00005 once per run (Apify synthetic event) |
| `station-result` | $0.0005 per station returned ($0.50 per 1,000) |
| Maximum billable station results | 4,000 per run |
| `SUMMARY`, CSV, XLSX | Free |

Examples:

- 20 nearby stations: **20 × $0.0005 + $0.00005 = $0.01005 ≈ $0.01**.
- Madrid province (862 stations in the latest smoke test): **862 × $0.0005 + $0.00005 = $0.43105 ≈ $0.43**.
- Complete Spain query: **about $2.00 maximum** — 4,000 × $0.0005 + $0.00005 = $2.00005 ≈ $2.00.

Apify displays event prices per 1,000 events, so `station-result` appears as **$0.50 / 1,000 results**. Apify's pricing table does not display the Actor's 4,000-charge limit per execution; that cap is enforced by the Actor and documented here.

The first 4,000 matching stations are billed and all matching stations are delivered. `provinceIds` only optimizes which official source file is downloaded; it never changes the price. If the user spending limit is reached, the Actor stops cleanly and does not return unbilled station results.

### Quick start

#### Nearby cheapest gasolineras

```json
{
  "searchMode": "nearest",
  "products": ["gasolina95", "gasoleo_a"],
  "latitude": 40.4168,
  "longitude": -3.7038,
  "radiusKm": 5,
  "priceProduct": "gasolina95",
  "maxResults": 20
}
```

#### One province

```json
{
  "searchMode": "cheapest",
  "provinceIds": ["28"],
  "products": ["gasoleo_a"],
  "priceProduct": "gasoleo_a",
  "maxResults": 0
}
```

`28` is the official province ID for Madrid. Use `provinces` when you want name-based filtering or multiple provinces.

#### Complete Spain export

```json
{
  "searchMode": "all",
  "products": ["gasolina95", "gasoleo_a", "gasolina98"],
  "onlyWithPrices": true,
  "exportFiles": ["csv", "xlsx"],
  "exportLanguage": "en",
  "maxResults": 0
}
```

The same three inputs are available in `examples/input-cheapest-nearby.json`, `examples/input-province-cheapest.json`, and `examples/input-all-spain.json`.

### Inputs

- `searchMode`: `cheapest`, `nearest`, or `all`.
- `latitude`, `longitude`, `radiusKm`: location and radius filters.
- `provinces`, `municipalities`, `brands`, `excludeBrands`: accent-insensitive text filters.
- `provinceIds`: one official province ID to optimize the source download.
- `products`: fuel types to include in each station's `prices` object.
- `priceProduct`, `maxPrice`, `requireProducts`: price and availability filters.
- `maxResults`: `0` returns every matching station; a positive value limits the returned set.
- `exportFiles`: `csv`, `xlsx`, or both.
- `exportLanguage`: `es` or `en` for file headers and sheet names.

### Output

The default dataset contains one item per returned station:

```json
{
  "stationId": "15210",
  "brand": "PETROPRIX",
  "address": "AVENIDA DE LOS REYES, 2",
  "town": "COLMENAR VIEJO",
  "province": "MADRID",
  "postalCode": "28770",
  "latitude": 40.656917,
  "longitude": -3.754472,
  "prices": {"gasoleo_a": 1.769},
  "cheapestProduct": "gasoleo_a",
  "cheapestPrice": 1.769,
  "cheapestUnit": "EUR/litre",
  "distanceKm": 2.4,
  "priceUpdatedAt": "20/09/2026 11:11:03"
}
```

A `SUMMARY` record is also saved in the run's key-value store. Its `billing` block reports the actual billing state:

```json
{
  "stationsReturned": 20,
  "stationsCharged": 20,
  "capApplied": false,
  "userLimitReached": false
}
```

Price statistics include count, minimum, quartiles, median, maximum, and average for the selected reference fuel. Fuels with different units, such as EUR/litre and EUR/kg, are not compared as if they were equivalent.

### Exported files

With the default `exportFiles` setting, the run's key-value store contains:

- `stations-es.csv` or `stations-en.csv`: RFC-4180 CSV with comma delimiters, dot decimals, and UTF-8 encoding.
- `stations-es.xlsx` or `stations-en.xlsx`: Excel workbook with numeric price cells, frozen headers, autofilter, a station sheet, a provincial summary, and source information.

These exports are free and do not create additional billable events.

### Use cases

- **Cheapest fuel nearby:** power a mobile, fleet, or travel workflow with the cheapest gasolineras around coordinates.
- **Province and brand monitoring:** compare Repsol, Cepsa, Ballenoil, Plenoil, or any other brand by province.
- **National Excel export:** create a current Spain-wide fuel-price workbook for analysis or reporting.
- **n8n and Make:** trigger an Actor run, read the dataset or exported file, and send alerts or update a spreadsheet.
- **AI agents via MCP:** let an agent answer questions such as “find the cheapest precio gasolina near Madrid” using structured station results.

### FAQ

#### Is this data official?

The Actor consumes the public MINCOTUR fuel-price feed and preserves source attribution. It is an independent, unofficial integration and is **not affiliated with, endorsed by, or operated by the Spanish Ministry**.

#### Are CSV and Excel files charged separately?

No. `SUMMARY`, CSV, and XLSX exports are included at no additional charge.

#### Does `provinceIds` reduce the price?

No. It only selects a smaller official source download. Billing is based on station results returned.

#### What happens at the 4,000-result cap?

The first 4,000 station results are billed; all matching stations are still delivered. The cap is per execution.

#### Which fuels are supported?

Gasóleo A/B/Premium, Gasolina 95/98 and blends, GLP, GNC, GNL, AdBlue, hydrogen, biodiesel, bioethanol, methanol, and the other products exposed by the official catalogue.

### Source and disclaimer

Source: Spanish Ministry public fuel-price data (MINCOTUR). This Actor is an independent data product. Verify critical commercial, legal, or safety decisions against the official source.

# Actor input Schema

## `searchMode` (type: `string`):

How to build the list of stations.

## `sortBy` (type: `string`):

Vacío = usa el orden propio del modo elegido. 'source' conserva el orden del fichero oficial.

## `products` (type: `array`):

Only these fuels are returned in the `prices` object.

## `provinceIds` (type: `array`):

Select exactly one official province id (e.g. 28 = Madrid, 08 = Barcelona) to download a smaller official source file. This only optimizes the download; pricing depends on returned station results, not on provinceIds. Use Provinces by name for one or more names after the source download.

## `provinces` (type: `array`):

Filter by one or more province names, accents optional (e.g. Madrid, Alava, Malaga). provinceIds can optimize a single-province source download, but it does not change pricing.

## `municipalities` (type: `array`):

Filter by municipality or town name (partial match, accents optional).

## `brands` (type: `array`):

Partial match on the station brand, e.g. Repsol, Cepsa, Ballenoil, Plenoil.

## `excludeBrands` (type: `array`):

Brands to exclude (partial match).

## `latitude` (type: `number`):

Centre point for the nearest / radius search.

## `longitude` (type: `number`):

Longitude for the nearest / radius search.

## `radiusKm` (type: `number`):

Only used together with latitude + longitude.

## `maxPrice` (type: `number`):

Drop stations above this price for the reference fuel type.

## `priceProduct` (type: `string`):

Reference fuel for sorting, maxPrice and statistics. Los 23 combustibles del catálogo son seleccionables. Ojo: `cheapestProduct`/`cheapestPrice` solo comparan combustibles de la MISMA unidad (EUR/litro vs EUR/kg no se pueden comparar); el resto de unidades van en `cheapestByUnit`.

## `requireProducts` (type: `array`):

Keep only stations that sell all of these fuels.

## `exportFiles` (type: `array`):

Writes downloadable files to the run's key-value store: a standard CSV (comma separated, dot decimals) and an Excel workbook with price columns as real numbers, autofilter and a per-province summary. Free of charge - they do not add events.

## `exportLanguage` (type: `string`):

Column headers and sheet names for the export files.

## `chargeReport` (type: `boolean`):

Kept for backward-compatible input only. Price statistics are included in every run at no extra event.

## `onlyWithPrices` (type: `boolean`):

Drop stations with no price at all.

## `cacheMinutes` (type: `integer`):

Reuses a previously downloaded Ministry file if it is younger than this. Keeps the load on the public endpoint low (its legal notice reserves the right to act against abusive or robotic use). Use 0 to always fetch fresh.

## `maxResults` (type: `integer`):

Default 0 returns every matching station. Set a positive integer when you deliberately want a smaller result set; only returned station results are billable, with a maximum of 4,000 charged results per execution.

## Actor input object example

```json
{
  "searchMode": "cheapest",
  "products": [
    "gasolina95",
    "gasoleo_a"
  ],
  "radiusKm": 5,
  "priceProduct": "gasolina95",
  "exportFiles": [
    "csv",
    "xlsx"
  ],
  "exportLanguage": "es",
  "chargeReport": true,
  "onlyWithPrices": true,
  "cacheMinutes": 30,
  "maxResults": 0
}
```

# Actor output Schema

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

Station records with prices for the products selected in the input.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rianone/spain-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("rianone/spain-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 '{}' |
apify call rianone/spain-fuel-prices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rianone/spain-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/YfEaX4Elf3HaWFPYO/builds/R8zZiwBLXQVXDal1W/openapi.json