Referencia de la API REST

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 (`application/vnd.oai.openapi+json`) · Referencia generada
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); 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 en CSV o JSON.

Errores

Los errores siguen el RFC 9457:

{
  "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.

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.

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`	Precio medio de hoy por carburante	normal	`get_fuel_prices`
`GET /v1/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`	Gasolineras cerca de unas coordenadas	pesada (30/min)	`find_fuel_near`
`GET /v1/stations/cheapest`	Las gasolineras más baratas	normal	`find_cheapest_fuel`
`GET /v1/stations/{id}`	Ficha de una gasolinera	normal	`get_station`
`GET /v1/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`	Histórico diario de una gasolinera	pesada (30/min)	`get_price_history`
`GET /v1/history`	Histórico diario de un territorio	normal	`get_price_history`
`GET /v1/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`	Comunidades, provincias y municipios	normal	—

Marcas

Método y ruta	Qué hace	Límite	MCP
`GET /v1/brands`	Marcas de gasolineras y sus precios	normal	`compare_brands`
`GET /v1/brands/{slug}`	Ficha de una marca	normal	`compare_brands`

Productos

Método y ruta	Qué hace	Límite	MCP
`GET /v1/products/{id}`	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`	Carreteras con gasolineras	normal	`find_fuel_on_road`
`GET /v1/roads/{slug}/stations`	Gasolineras de una carretera	normal	`find_fuel_on_road`
`GET /v1/routes`	Rutas por carretera	normal	`find_routes`
`GET /v1/routes/{slug}`	Una ruta y dónde repostar	pesada (30/min)	`get_route`
`POST /v1/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`	Buscar guías, artículos y rutas	normal	`search_content`
`GET /v1/content/{type}/{slug}`	Una guía, un artículo o una ruta completos	normal	`get_article`
`GET /v1/reports`	Informes mensuales disponibles	normal	`get_monthly_report`
`GET /v1/reports/{month}`	Informe de un mes	normal	`get_monthly_report`
`GET /v1/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`	Coste en combustible de un viaje	normal	`calculate_trip_cost`
`GET /v1/calc/tank-cost`	Cuánto cuesta llenar el depósito	normal	`calculate_trip_cost`
`GET /v1/calc/savings`	Ahorro al repostar más barato	normal	`calculate_savings`
`GET /v1/calc/vehicle-costs`	Gasolina o diésel, eléctrico o combustión	normal	`compare_vehicle_costs`
`GET /v1/calc/adblue`	Gasto en AdBlue	normal	`calculate_adblue`
`GET /v1/calc/price-breakdown`	Desglose del precio: impuestos y producto	normal	`explain_fuel_price`

Servicio

Método y ruta	Qué hace	Límite	MCP
`GET /v1/status`	Estado de la API y de los datos	normal	—

Referencia generada desde el OpenAPIParámetros, esquemas de respuesta, errores y ejemplos en curl y JavaScript de cada endpoint.

Fuente de los datos: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras). Datos de la API y del servidor MCP con licencia CC BY 4.0: cita Gasolina hoy y la fuente.