# Spain Fuel Prices + Cheapest Stop on Your Route (`oatpage/spain-fuel-prices`) Actor

Current fuel prices for every gas station in Spain from the Ministry open data service. Filter by province, town, brand, fuel type, max price or radius; sort by price. No login, no proxy.

- **URL**: https://apify.com/oatpage/spain-fuel-prices.md
- **Developed by:** [Oatpage](https://apify.com/oatpage) (community)
- **Categories:** Travel, Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 gas stations

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

Independent tool. Not an official service and not endorsed, sponsored or supported by the Ministry. Current prices of every fuel station in Spain (about 11,500) from the Ministry open data service, filtered and sorted for you.

**Data source:** Fuente de los datos: Ministerio para la Transición Ecológica y el Reto Demográfico, Geoportal de Gasolineras (open data, reuse with attribution, Ley 37/2007 on reuse of public sector information). Prices are as published by the stations and updated by the Ministry several times a day; the field `sourceTimestamp` shows the Ministry's last-update timestamp. The actor only filters, sorts and structures the data; it does not change prices.

### Cheapest stop on your route

Give an origin, a destination (and waypoints if you like) and the actor ranks the stations along the way by what the stop **really costs you**: liters x price + the detour to reach it. A station that is 3 cents cheaper but 10 km off the road can end up costing more, and one that is closed right now is a wasted trip.

Input (`openNow: true` keeps only stations open at that moment):

```json
{"fuel":"gasoleo_a","routePoints":[{"latitude":40.4168,"longitude":-3.7038},{"latitude":39.4699,"longitude":-0.3763}],"corridorKm":3,"tankLiters":40,"consumptionL100km":6,"openNow":true}
```

Output (real run, Madrid to Valencia, diesel, open stations, 11-10-2026): a `summary` record and then one record per station, cheapest total first.

```json
{"type":"summary","fuel":"gasoleo_a","stations":169,"avgPrice":1.873,"minPrice":1.69,"maxPrice":2.049,"medianPrice":1.889,"cheapest":{"stationId":"13871","brand":"ELDISSER","town":"PATERNA","province":"VALENCIA / VALÈNCIA","price":1.69}}
{"type":"station","stationId":"13871","brand":"ELDISSER","town":"PATERNA","province":"VALENCIA / VALÈNCIA","prices":{"gasoleo_a":1.69},"routeDistanceKm":2.85,"detourKm":5.7,"alongRouteKm":295.93,"routeLengthKm":304.32,"fillCostEur":67.6,"detourCostEur":0.58,"totalCostEur":68.18,"savingVsCorridorAverageEur":6.73,"isOpenNow":true}
```

- `savingVsCorridorAverageEur` compares with filling the same liters at the average price of the stations in the corridor.
- The route is the straight line between your points (add waypoints to follow the road). The detour is estimated as twice the distance from the route line to the station. It is an estimate, not navigation.
- `isOpenNow` is read from the opening hours the Ministry publishes (Spanish local time; `null` if the text cannot be read). Hours can be out of date.
- Any search (not only routes) can use `openNow` and returns the `summary` record when `fuel` is set; the summary is not billed.

### Input

| Field | Meaning | Default |
|---|---|---|
| `provinces` | Province names (e.g. `MADRID`); empty = all Spain | none |
| `municipality` | Exact town name, accents ignored | none |
| `brand` | Brand contains (e.g. `REPSOL`) | none |
| `fuel` | `gasoleo_a`, `gasolina_95_e5`, `gasolina_95_e10`, `gasolina_98_e5`, `glp`, `adblue`... | `gasoleo_a` |
| `maxPricePerLiter` | Upper price limit in EUR (needs `fuel`) | none |
| `latitude`, `longitude`, `radiusKm` | Stations within a radius | none |
| `sortBy` | `price`, `distance` or `none` | `price` |
| `routePoints`, `corridorKm`, `tankLiters`, `consumptionL100km` | Route mode (see above) | none, 3 km, 40 l, 6 l/100 km |
| `openNow` | Only stations open now | `false` |
| `includeSummary` | Add the summary record (not billed) | `true` |
| `maxItems` | 1-20,000 | 100 |

### Output (one record per station)

```json
{"stationId":"16440","brand":"BALLENOIL","address":"CALLE PUERTO COTOS, 25","postalCode":"28935","town":"MOSTOLES","municipality":"Móstoles","province":"MADRID","latitude":40.351694,"longitude":-3.876639,"schedule":"L-D: 24H","saleType":"public","prices":{"gasoleo_a":1.689,"gasolina_95_e5":1.589},"fetchedAt":"2026-10-10T10:21:24Z","sourceTimestamp":"10/10/2026 12:21:20"}
```

Prices are EUR per liter. Fuels a station does not sell are absent from `prices`.

### Pricing (pay per event)

- Run start: $0.005
- Station: $0.001 (100 stations = $0.10)

### Limits

- Spain only (mainland, Balearic and Canary Islands). Marine stations are not included.
- Prices are those published by the Ministry; they can be a few hours old. Not a guarantee of the price at the pump.
- Brand names appear only as data of each station; their owners are not affiliated with this tool.

### Data protection

Only business data of stations (address, schedule, prices). No personal data.

# Actor input Schema

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

Province names as in the Ministry data, e.g. MADRID, BARCELONA, ALBACETE. Empty = all Spain.

## `municipality` (type: `string`):

Exact name, accents ignored.

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

e.g. REPSOL, CEPSA, BALLENOIL.

## `fuel` (type: `string`):

Required to use max price and sort by price.

## `maxPricePerLiter` (type: `number`):

Only return stations whose price for the chosen fuel is at or below this value, in euros per liter.

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

Latitude of the search center in decimal degrees. Use together with longitude and a radius.

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

Longitude of the search center in decimal degrees. Use together with latitude and a radius.

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

Needs latitude and longitude.

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

How to order the results, for example by price or by distance.

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

Maximum number of stations to return. Each station is billed as one event.

## `routePoints` (type: `array`):

Optional. Two or more points {"latitude":..,"longitude":..}: origin, optional waypoints, destination. The actor returns the stations within the corridor of that line, ranked by the REAL cost of filling up there (liters x price + the cost of the detour). Needs 'fuel'. The line joins your points in a straight line: add waypoints to follow the road.

## `corridorKm` (type: `number`):

Maximum distance from the route line to a station (route mode).

## `tankLiters` (type: `number`):

Used to compute the cost of the fill-up (route mode).

## `consumptionL100km` (type: `number`):

Used to price the detour: 2 x distance to the route x consumption x price (route mode).

## `openNow` (type: `boolean`):

Skips stations whose published opening hours say they are closed right now (Spanish local time). Stations whose hours cannot be read are kept.

## `includeSummary` (type: `boolean`):

With 'fuel' set, adds one record (type 'summary') with average, minimum, maximum and median price of the selection and its cheapest station. It is not billed.

## Actor input object example

```json
{
  "provinces": [
    "MADRID"
  ],
  "fuel": "gasoleo_a",
  "sortBy": "price",
  "maxItems": 100,
  "routePoints": [
    {
      "latitude": 40.4168,
      "longitude": -3.7038
    },
    {
      "latitude": 39.4699,
      "longitude": -0.3763
    }
  ],
  "corridorKm": 3,
  "tankLiters": 40,
  "consumptionL100km": 6,
  "openNow": false,
  "includeSummary": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "provinces": [
        "MADRID"
    ],
    "routePoints": [
        {
            "latitude": 40.4168,
            "longitude": -3.7038
        },
        {
            "latitude": 39.4699,
            "longitude": -0.3763
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("oatpage/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 = {
    "provinces": ["MADRID"],
    "routePoints": [
        {
            "latitude": 40.4168,
            "longitude": -3.7038,
        },
        {
            "latitude": 39.4699,
            "longitude": -0.3763,
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("oatpage/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 '{
  "provinces": [
    "MADRID"
  ],
  "routePoints": [
    {
      "latitude": 40.4168,
      "longitude": -3.7038
    },
    {
      "latitude": 39.4699,
      "longitude": -0.3763
    }
  ]
}' |
apify call oatpage/spain-fuel-prices --silent --output-dataset

```

## MCP server setup

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