# Spain Fuel Station Prices - MINCOTUR, Per Station (`nexgensignal/es-fuel-station-price-records`) Actor

Spain fuel prices (MINCOTUR) as clean per-record data - one wide record per station with brand, location and 23 fuel-price columns kept verbatim. 11,470 stations. Source + date cited (Ley 37/2007). $0.05 per record.

- **URL**: https://apify.com/nexgensignal/es-fuel-station-price-records.md
- **Developed by:** [NexGen Signal](https://apify.com/nexgensignal) (community)
- **Categories:** Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $33.50 / 1,000 fuel station price records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Spain Fuel Station Prices - MINCOTUR, Per Station

Spain's fuel prices from the official **MINCOTUR** service as clean, per-station records in the source's own
wide shape - one record per station with 23 fuel-price columns kept verbatim, plus the station's brand, location
and the data date.

### What one record represents

The source is the **MINCOTUR** Precios de Carburantes service (`sedeaplicaciones.minetur.gob.es`), the Spanish
government fuel-price register, delivered as a single JSON download. Each record is **one station**: its id,
brand (Rotulo), address, locality, municipality, province, coordinates, margin, schedule and sale type, plus
**23 fuel-price columns** (Gasoleo A, Gasolina 95 E5, GLP, GNC, hydrogen and the rest) kept in the source's own
wide layout, and the data extraction date.

### Coverage and volume

The register holds **11,470 stations** - measured live at build time.

**Sol's Wave-4 index put this door at 11,471 stations; measured live at build time the register holds 11,470
stations - matching the index.**

### Licence and attribution

Re-use is governed by the conditions of Ley 37/2007. The full notice travels on every record:

> Precios de Carburantes (MINCOTUR), Spain. Re-use under Ley 37/2007 conditions: free re-use, including commercial, provided the source and the retrieval date are cited (both are stamped on every record). No modification that distorts the data.

To honour those conditions, both the **data extraction date** (from the feed) and the **retrieval timestamp**
are stamped on every record, and the source is cited on every record.

### Person-data policy

`Rotulo` is the station **brand** (an organisation) and is kept; the feed carries **no owner or operator person
field**. A per-record assertion rejects any owner/operator/person field as a matter of form. No natural-person
data is processed.

### Interpretation caveat

One record per Spanish fuel station (11,470 stations) in the source's own wide shape: station id, brand (Rotulo), address, municipality, province, coordinates, and 23 fuel-price columns kept verbatim (Spanish comma decimals, unmodified). The data extraction date and retrieval timestamp are on every record. Rotulo is the brand; the feed carries no owner/operator-person field.

Values are reproduced verbatim from the feed; the Actor never rewrites a field, and the **23 fuel-price columns
are kept in the source's own wide shape** - no reshaping to a long format, and the prices are the source's own
Spanish comma-decimal strings, unmodified. A fuel a station does not sell is left empty.

### Provenance and compliance

Every run reads the door host's `robots.txt` at runtime; the gate result (URL, status, byte length and, where a
policy is served, its SHA-256) is written to the run's `RUN_RECEIPT`. Where the host serves no applicable
robots rule, the gate records that (flagged) and proceeds on the licence, which grants re-use. The endpoint is
keyless. The Actor never bypasses a block or fetches through a mirror.

### Data quality and freshness

Boolean columns are delivered as real booleans and numeric columns as real numbers. Delivery is keyed on a
stable id, so the dataset is safe to diff, deduplicate or upsert. Every run re-reads the live door, so the data
is as fresh as the source publishes, and each record's `observed_at` stamp dates the snapshot. The run's
`RUN_RECEIPT` records the source URL and how many records were delivered and charged, and confirms
`charge_equals_delivered`.

### Billing, delivery and joins

Pricing is per record: you are billed only for records the Actor actually delivers, with the charge raised after
each record is pushed (push-then-charge), so a failed or empty run costs nothing. The **Maximum records** cap
bounds every run, so you control spend precisely - sample cheaply, then raise it. Every record is a flat, typed
object keyed on a stable id, so the data loads without a cleaning pass, diffs cleanly between runs, and upserts
into a table you maintain over time; re-running keeps that table current without re-paying for rows you already
hold, and each receipt reconciles delivered against charged. Because the source's own identifiers are preserved
verbatim, the dataset joins cleanly onto other sources keyed on the same identifier.

### Scaling and scheduling

Set **Maximum records** low to sample the shape of the data cheaply, then raise it once the cell fits your use.
The Actor delivers incrementally and streams its source, so memory stays flat regardless of how many records you
request, and you are billed only for what is delivered. Because the source republishes on its own cadence, a
scheduled run keeps a downstream table current: new and changed records upsert over the old ones on the stable
key, and the `observed_at` stamp on every record tells you when each was last seen live. There is no
subscription and no minimum - the per-record price and the record cap together mean the spend on any run is
known in advance and matched exactly to the data you receive.

### Inputs

- **Maximum records** (`maxRecords`) - hard cap on station records delivered and billed.

### Output

Records land in the Actor's default dataset and export as JSON, CSV, Excel or via the Apify API. A tabular
overview surfaces station id, brand, municipality, province, key fuel prices and the data date.

### Fields in detail

The record leads with `station_id`, `brand`, `address`, `postcode`, `locality`, `municipality`, `province`,
`latitude`, `longitude`, `margin`, `schedule`, `sale_type`, then the 23 `price_*` columns and the `data_date`.
The provenance block closes every record.

### Typical uses

Fuel-price monitoring teams use this cell to track Spanish pump prices station by station - the full wide table
of every fuel at every station, with the brand and location - ready to compare by region, brand or fuel. Because
the wide shape matches the source, a downstream table maps one-to-one onto the register, and the station id lets
you follow a station over time by stacking runs. It is one of four fuel-price cells in this fleet.

### Why the wide shape is kept

The MINCOTUR feed publishes each station as one wide row with a column per fuel type, and this Actor keeps that
shape rather than pivoting to one-row-per-price. That is deliberate: the wide shape maps one-to-one onto the
source, so a downstream table matches the register exactly, and a station's full fuel menu is on a single row -
convenient for a station-level comparison. If you want a long (one-row-per-price) shape, it is a trivial unpivot
downstream; keeping the source shape means the Actor never imposes a transformation the buyer did not ask for.
The prices stay in the source's Spanish comma-decimal format, unmodified, so the record is a faithful copy of
what MINCOTUR published on the stamped data date.

### The four-country fuel family

This cell is one of four fuel-price cells in the fleet, one per country: Spain here, France in the companion
roulez-eco cell, and Italy in the two MIMIT cells. Each draws its own national open-data source at that
country's own grain, so the four do not overlap. Spain's feed is the widest of the four - a station's entire
fuel menu on one row across 23 columns - which makes it the natural choice when you want the full price picture
per station rather than a single fuel. Run the four and align them on your own schema for a multi-country
comparison; each keeps its source's identifiers so a station in one run maps to the same station in the next.

### Sibling Actors

It sits beside the France fuel-station-price cell and the two Italy fuel cells - a four-country fuel-price family. It shares its JSON engineering with the fleet's other records Actors.

# Actor input Schema

## `maxRecords` (type: `integer`):

Maximum records delivered and billed. You are billed only for records actually delivered. Raise it to pull the full set.

## Actor input object example

```json
{
  "maxRecords": 500
}
```

# Actor output Schema

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

The delivered Spain fuel station price record.

# 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 = {
    "maxRecords": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgensignal/es-fuel-station-price-records").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 = { "maxRecords": 500 }

# Run the Actor and wait for it to finish
run = client.actor("nexgensignal/es-fuel-station-price-records").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 '{
  "maxRecords": 500
}' |
apify call nexgensignal/es-fuel-station-price-records --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgensignal/es-fuel-station-price-records"
        }
    }
}
```

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/n5shzZ4C4LncnqvIT/builds/mKhliPdpsRjgRb40v/openapi.json