# Referencia de la API REST

> Versión Markdown de https://docs.preciosgasolina.es/referencia/ · Actualizado: 2026-10-07 · Índice para LLM: https://docs.preciosgasolina.es/llms.txt

URL base, sobre { data, meta }, campos de meta, errores RFC 9457, límites, cabeceras de caché y lista de los 30 endpoints de la API de Gasolina hoy.

La API REST de Gasolina hoy es **de solo lectura, gratuita y sin clave**. Devuelve JSON con los precios oficiales de los carburantes de unas 11.500 gasolineras de España y otros datos derivados (histórico, rankings, carreteras, rutas, contenido y calculadoras).

|                |                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| URL base       | `https://api.preciosgasolina.es/v1`                                                                                                          |
| Especificación | [OpenAPI 3.1](https://api.preciosgasolina.es/v1/openapi.json) (`application/vnd.oai.openapi+json`) · [Referencia generada](https://docs.preciosgasolina.es/referencia/api/) |
| Formato        | JSON UTF-8; errores en `application/problem+json` (RFC 9457)                                                                                 |
| Métodos        | `GET` y `HEAD` (y `OPTIONS` para CORS); `POST` solo en `/v1/route/fuel`                                                                      |
| Autenticación  | Ninguna                                                                                                                                      |
| CORS           | Cualquier origen (`Access-Control-Allow-Origin: *`), sin credenciales                                                                        |
| Versión        | `v1` (en la ruta y en `meta.api_version`)                                                                                                    |

`GET https://api.preciosgasolina.es/` devuelve un índice con la lista de endpoints, la URL del OpenAPI, la del MCP y la de esta documentación.

## Sobre de respuesta

Toda respuesta correcta es un objeto `{ "data": …, "meta": { … } }`. `data` cambia según el endpoint (sus campos están en la [referencia generada](https://docs.preciosgasolina.es/referencia/api/)); `meta` es siempre igual:

| Campo                   | Tipo                    | Significado                                                                                                            |
| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `meta.api_version`      | texto                   | Versión de la API que ha respondido (`v1`).                                                                            |
| `meta.request_id`       | texto                   | Identificador de la petición (también en la cabecera `X-Request-Id`). Inclúyelo si nos escribes por un error.          |
| `meta.last_updated`     | texto ISO 8601 o `null` | Fecha y hora (UTC) de la última actualización de los datos.                                                            |
| `meta.next_update`      | texto ISO 8601          | Fecha y hora prevista de la próxima actualización.                                                                     |
| `meta.data_age_seconds` | entero o `null`         | Antigüedad de los datos, en segundos.                                                                                  |
| `meta.stale`            | booleano                | `true` si la fuente no respondió y se sirve la última copia buena (los datos pueden ser de la actualización anterior). |
| `meta.source`           | texto                   | Fuente de los precios: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras).       |
| `meta.attribution`      | texto                   | Texto de atribución que debes mostrar junto a los datos.                                                               |
| `meta.license`          | URL                     | Licencia de reutilización (CC BY 4.0).                                                                                 |
| `meta.web_url`          | URL o `null`            | Página equivalente en preciosgasolina.es, para citar y enlazar.                                                        |

Convenciones de `data`: precios en euros con tres decimales (`€/L`, o `€/kg` con GNC, indicado en `unit`), porcentajes como número (`-1.28` = −1,28 %), fechas ISO 8601 y, en cada gasolinera o territorio, su `web_url`.

## Peticiones

- **Parámetros estrictos.** Un parámetro desconocido, repetido o con un valor fuera de rango devuelve `400` (`INVALID_PARAMETER`) con el motivo en `detail`. Los endpoints sin parámetros no admiten ninguno.
- **Booleanos:** `true`, `false`, `1` o `0`.
- **Coordenadas:** WGS84 dentro de España; se redondean a 3 decimales (≈ 100 m).
- **URL:** 2.048 caracteres como máximo (`414` si es más larga).
- **Cuerpo (solo `POST /v1/route/fuel`):** JSON con `Content-Type: application/json`, 32 KB como mucho.

## Paginación y tamaño

La API no pagina: cada endpoint de listas acepta `limit` (de 1 a 50; por defecto 10, salvo donde se indique) y filtros (`level`/`code`, `fuel`, `brand`, `open_24h`…). Para obtener **todas** las gasolineras o series completas, descarga los [datos abiertos](https://preciosgasolina.es/datos/) en CSV o JSON.

## Errores

Los errores siguen el RFC 9457:

Ejemplo ilustrativo

```json
{
  "type": "https://docs.preciosgasolina.es/conceptos/errores/#station-not-found",
  "title": "No encontrado",
  "status": 404,
  "detail": "No existe la gasolinera 99999999 (o ya no vende al público).",
  "code": "STATION_NOT_FOUND",
  "request_id": "e74dbaec2b574590",
  "instance": "/v1/stations/99999999"
}
```

Comprueba `code` (estable) en tu código, no `title` ni `detail` (textos que pueden cambiar). Lista completa: [Errores](https://docs.preciosgasolina.es/conceptos/errores/).

## Cabeceras

| Cabecera           | Cuándo                       | Significado                                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cache-Control`    | siempre                      | Datos con precios: `public, max-age=<segundos hasta la próxima actualización, máx. 3600>, stale-while-revalidate=300`. Contenido y catálogos: 6 horas. Territorios y ahorro: 1 día. `/v1/route/fuel`, `/v1/status` y errores: `no-store`. Respuestas con `meta.stale`: 60 s. |
| `X-Request-Id`     | siempre                      | Identificador de la petición (= `meta.request_id` o `request_id` del error).                                                                                                                                                                                                 |
| `X-Cache`          | respuestas correctas         | `hit`, `miss` o `stale` (caché de la API).                                                                                                                                                                                                                                   |
| `RateLimit-Policy` | respuestas correctas y `429` | Límite aplicado: `"rest";q=120;w=60` y, en las consultas pesadas, también `"heavy";q=30;w=60`.                                                                                                                                                                               |
| `Retry-After`      | `429` y `503`                | Segundos que debes esperar antes de reintentar.                                                                                                                                                                                                                              |

Las respuestas llevan además `X-Robots-Tag: noindex`, `X-Content-Type-Options: nosniff` y `Strict-Transport-Security`.

## Límites

Por IP: **120 peticiones por minuto** (y 20 cada 10 segundos); **consultas pesadas, 30 por minuto**. Las pesadas son `GET /v1/stations/nearby`, `GET /v1/stations/{id}/history`, `GET /v1/routes/{slug}` y `POST /v1/route/fuel`. Todo sobre límites, topes y reintentos en [Límites de uso](https://docs.preciosgasolina.es/conceptos/limites/).

## Endpoints

Los 30 endpoints, agrupados como en el OpenAPI. Cada enlace lleva a su página de referencia con parámetros, respuestas y ejemplos.

### Precios

| Método y ruta                                                              | Qué hace                                      | Límite | MCP               |
| -------------------------------------------------------------------------- | --------------------------------------------- | ------ | ----------------- |
| [`GET /v1/prices`](https://docs.preciosgasolina.es/referencia/api/operations/prices/)                     | Precio medio de hoy por carburante            | normal | `get_fuel_prices` |
| [`GET /v1/rankings/regions`](https://docs.preciosgasolina.es/referencia/api/operations/rankings_regions/) | Comunidades o provincias ordenadas por precio | normal | `compare_regions` |

### Gasolineras

| Método y ruta                                                                | Qué hace                                                       | Límite          | MCP                  |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------- | -------------------- |
| [`GET /v1/stations/nearby`](https://docs.preciosgasolina.es/referencia/api/operations/stations_nearby/)     | Gasolineras cerca de unas coordenadas                          | pesada (30/min) | `find_fuel_near`     |
| [`GET /v1/stations/cheapest`](https://docs.preciosgasolina.es/referencia/api/operations/stations_cheapest/) | Las gasolineras más baratas                                    | normal          | `find_cheapest_fuel` |
| [`GET /v1/stations/{id}`](https://docs.preciosgasolina.es/referencia/api/operations/station/)               | Ficha de una gasolinera                                        | normal          | `get_station`        |
| [`GET /v1/search`](https://docs.preciosgasolina.es/referencia/api/operations/search/)                       | Buscar municipios, códigos postales, territorios y gasolineras | normal          | `search_places`      |

### Histórico

| Método y ruta                                                                  | Qué hace                           | Límite          | MCP                 |
| ------------------------------------------------------------------------------ | ---------------------------------- | --------------- | ------------------- |
| [`GET /v1/stations/{id}/history`](https://docs.preciosgasolina.es/referencia/api/operations/station_history/) | Histórico diario de una gasolinera | pesada (30/min) | `get_price_history` |
| [`GET /v1/history`](https://docs.preciosgasolina.es/referencia/api/operations/history/)                       | Histórico diario de un territorio  | normal          | `get_price_history` |
| [`GET /v1/history/monthly`](https://docs.preciosgasolina.es/referencia/api/operations/history_monthly/)       | Serie mensual de España desde 2005 | normal          | `get_price_history` |

### Territorios

| Método y ruta                                                    | Qué hace                             | Límite | MCP |
| ---------------------------------------------------------------- | ------------------------------------ | ------ | --- |
| [`GET /v1/territories`](https://docs.preciosgasolina.es/referencia/api/operations/territories/) | Comunidades, provincias y municipios | normal | —   |

### Marcas

| Método y ruta                                                | Qué hace                            | Límite | MCP              |
| ------------------------------------------------------------ | ----------------------------------- | ------ | ---------------- |
| [`GET /v1/brands`](https://docs.preciosgasolina.es/referencia/api/operations/brands/)       | Marcas de gasolineras y sus precios | normal | `compare_brands` |
| [`GET /v1/brands/{slug}`](https://docs.preciosgasolina.es/referencia/api/operations/brand/) | Ficha de una marca                  | normal | `compare_brands` |

### Productos

| Método y ruta                                                  | Qué hace                                    | Límite | MCP                  |
| -------------------------------------------------------------- | ------------------------------------------- | ------ | -------------------- |
| [`GET /v1/products/{id}`](https://docs.preciosgasolina.es/referencia/api/operations/product/) | AdBlue, gasóleo B, HVO, GNL y gasolinas E10 | normal | `get_product_prices` |

### Carreteras y rutas

| Método y ruta                                                                | Qué hace                     | Límite          | MCP                     |
| ---------------------------------------------------------------------------- | ---------------------------- | --------------- | ----------------------- |
| [`GET /v1/roads`](https://docs.preciosgasolina.es/referencia/api/operations/roads/)                         | Carreteras con gasolineras   | normal          | `find_fuel_on_road`     |
| [`GET /v1/roads/{slug}/stations`](https://docs.preciosgasolina.es/referencia/api/operations/road_stations/) | Gasolineras de una carretera | normal          | `find_fuel_on_road`     |
| [`GET /v1/routes`](https://docs.preciosgasolina.es/referencia/api/operations/routes/)                       | Rutas por carretera          | normal          | `find_routes`           |
| [`GET /v1/routes/{slug}`](https://docs.preciosgasolina.es/referencia/api/operations/route/)                 | Una ruta y dónde repostar    | pesada (30/min) | `get_route`             |
| [`POST /v1/route/fuel`](https://docs.preciosgasolina.es/referencia/api/operations/route_fuel/)              | Dónde repostar en tu ruta    | pesada (30/min) | `find_fuel_along_route` |

### Contenido

| Método y ruta                                                               | Qué hace                                      | Límite | MCP                  |
| --------------------------------------------------------------------------- | --------------------------------------------- | ------ | -------------------- |
| [`GET /v1/content`](https://docs.preciosgasolina.es/referencia/api/operations/content/)                    | Buscar guías, artículos y rutas               | normal | `search_content`     |
| [`GET /v1/content/{type}/{slug}`](https://docs.preciosgasolina.es/referencia/api/operations/content_item/) | Una guía, un artículo o una ruta completos    | normal | `get_article`        |
| [`GET /v1/reports`](https://docs.preciosgasolina.es/referencia/api/operations/reports/)                    | Informes mensuales disponibles                | normal | `get_monthly_report` |
| [`GET /v1/reports/{month}`](https://docs.preciosgasolina.es/referencia/api/operations/report/)             | Informe de un mes                             | normal | `get_monthly_report` |
| [`GET /v1/taxes`](https://docs.preciosgasolina.es/referencia/api/operations/taxes/)                        | Impuestos de los carburantes y rebaja vigente | normal | `explain_fuel_price` |

### Calculadoras

| Método y ruta                                                                | Qué hace                                  | Límite | MCP                     |
| ---------------------------------------------------------------------------- | ----------------------------------------- | ------ | ----------------------- |
| [`GET /v1/calc/trip-cost`](https://docs.preciosgasolina.es/referencia/api/operations/calc_trip/)            | Coste en combustible de un viaje          | normal | `calculate_trip_cost`   |
| [`GET /v1/calc/tank-cost`](https://docs.preciosgasolina.es/referencia/api/operations/calc_tank/)            | Cuánto cuesta llenar el depósito          | normal | `calculate_trip_cost`   |
| [`GET /v1/calc/savings`](https://docs.preciosgasolina.es/referencia/api/operations/calc_savings/)           | Ahorro al repostar más barato             | normal | `calculate_savings`     |
| [`GET /v1/calc/vehicle-costs`](https://docs.preciosgasolina.es/referencia/api/operations/calc_vehicle/)     | Gasolina o diésel, eléctrico o combustión | normal | `compare_vehicle_costs` |
| [`GET /v1/calc/adblue`](https://docs.preciosgasolina.es/referencia/api/operations/calc_adblue/)             | Gasto en AdBlue                           | normal | `calculate_adblue`      |
| [`GET /v1/calc/price-breakdown`](https://docs.preciosgasolina.es/referencia/api/operations/calc_breakdown/) | Desglose del precio: impuestos y producto | normal | `explain_fuel_price`    |

### Servicio

| Método y ruta                                          | Qué hace                        | Límite | MCP |
| ------------------------------------------------------ | ------------------------------- | ------ | --- |
| [`GET /v1/status`](https://docs.preciosgasolina.es/referencia/api/operations/status/) | Estado de la API y de los datos | normal | —   |

> **Estado del servicio**
>
> `GET /v1/status` devuelve la versión de la API, la fecha de los datos y la próxima actualización, sin caché. Úsalo para comprobar que la API responde (sin abusar: cuenta en los límites).

[Referencia generada desde el OpenAPI](https://docs.preciosgasolina.es/referencia/api/)Parámetros, esquemas de respuesta, errores y ejemplos en curl y JavaScript de cada endpoint.