Gratis · sin clave · JSON · licencia CC BY 4.0
API REST gratuita de precios de carburantes
La API REST de Gasolina hoy devuelve en JSON los precios oficiales de unas 11.500 gasolineras de España: las más baratas de cada territorio, las cercanas a un punto, el histórico, las carreteras, las rutas y las calculadoras. Es gratuita, no pide clave, es de solo lectura y se actualiza dos veces al día, hacia las 8:00 y las 20:00.
URL base
https://api.preciosgasolina.es/v1
Especificación OpenAPI 3.1
curl "https://api.preciosgasolina.es/v1/stations/cheapest?fuel=diesel&level=province&code=28&limit=5"¿Qué ofrece la API?
9 grupos de rutas, todas de solo lectura
Precios
Precio medio de cada carburante por territorio y ranking de comunidades y provincias.
- GET /v1/prices
- GET /v1/rankings/regions
Gasolineras
Gasolineras cercanas a unas coordenadas, las más baratas de un territorio, la ficha de cada una y el buscador de lugares.
- GET /v1/stations/nearby
- GET /v1/stations/cheapest
- GET /v1/stations/{id}
- GET /v1/search
Histórico
Serie diaria de 90 días por territorio y por gasolinera, y serie mensual de España desde 2005.
- GET /v1/history
- GET /v1/stations/{id}/history
- GET /v1/history/monthly
Territorios
Lista de territorios con sus identificadores.
- GET /v1/territories
Marcas
Marcas de gasolineras y la ficha de cada una.
- GET /v1/brands
- GET /v1/brands/{slug}
Productos
AdBlue, gasóleo B, HVO, GNL y gasolinas E10: precio medio y gasolineras que comunican su precio.
- GET /v1/products/{id}
Carreteras y rutas
Gasolineras de cada carretera, rutas por carretera y dónde repostar en un recorrido propio (POST).
- GET /v1/roads
- GET /v1/roads/{slug}/stations
- GET /v1/routes
- GET /v1/routes/{slug}
- POST /v1/route/fuel
Contenido
Guías, artículos del blog, informes mensuales e impuestos de los carburantes.
- GET /v1/content
- GET /v1/content/{type}/{slug}
- GET /v1/reports
- GET /v1/reports/{month}
- GET /v1/taxes
Calculadoras
Las mismas fórmulas que las calculadoras de la web: viaje, depósito, ahorro, coste por vehículo, AdBlue y desglose del precio.
- GET /v1/calc/trip-cost
- GET /v1/calc/tank-cost
- GET /v1/calc/savings
- GET /v1/calc/vehicle-costs
- GET /v1/calc/adblue
- GET /v1/calc/price-breakdown
Los parámetros y las respuestas de cada ruta están en la referencia de la API y en la especificación OpenAPI 3.1, que puedes importar en Postman, Insomnia o un generador de clientes.
¿Cómo se hace la primera petición?
Sin clave: copia el ejemplo en una terminal
Parámetros del ejemplo
GET /v1/stations/cheapest
- fuel=diesel
- Carburante (identificadores en la tabla de abajo).
- level=province
- Nivel del territorio: en este caso, provincia.
- code=28
- Código INE de la provincia: 28 es Madrid.
- limit=5
- Número de resultados (hasta 50; por defecto, 10).
| fuel | Carburante | Unidad |
|---|---|---|
| gasoline_95 | Gasolina 95 | €/L |
| gasoline_98 | Gasolina 98 | €/L |
| diesel | Gasóleo A (diésel) | €/L |
| diesel_premium | Gasóleo premium | €/L |
| lpg | GLP (autogás) | €/L |
| cng | GNC (gas natural comprimido) | €/kg |
¿Qué devuelve cada respuesta?
Un sobre JSON con los datos y sus metadatos
| Campo | Qué contiene |
|---|---|
| data | El resultado pedido: un objeto o una lista, según la ruta. |
| meta.api_version | Versión de la API que ha respondido. |
| meta.request_id | Identificador de la petición. Inclúyelo si nos escribes por un error. |
| meta.last_updated | Fecha y hora de la última actualización de los datos. |
| meta.next_update | Fecha y hora prevista de la próxima actualización. |
| meta.data_age_seconds | Antigüedad de los datos, en segundos. |
| meta.stale | true si la fuente no respondió y se sirve la última copia buena (los datos pueden ser de la actualización anterior). |
| meta.source | Fuente de los precios: el Ministerio para la Transición Ecológica y el Reto Demográfico. |
| meta.attribution | Texto de atribución que debes mostrar junto a los datos. |
| meta.license | Licencia de reutilización (CC BY 4.0). |
| meta.web_url | Página equivalente en preciosgasolina.es, para citar y enlazar. |
- Precios numéricosCon punto decimal (por ejemplo, 1.459), en EUR y por L o kg.
- Errores estándarRFC 9457 (
application/problem+json) concodeyrequest_id. - Enlace a la web
web_urlapunta a la página de preciosgasolina.es: la ficha de la gasolinera, el territorio o la guía.
¿Qué límites tiene la API?
Por IP, para que funcione bien para todos
| Qué | Límite |
|---|---|
| API REST | 120 peticiones por minuto y por IP (y 20 cada 10 segundos) |
| Consultas pesadas (coordenadas, rutas propias, histórico de una gasolinera) | 30 por minuto |
| Servidor MCP | 60 mensajes por minuto, de ellos 30 llamadas a herramientas |
| Resultados por petición (limit) | Hasta 50 (por defecto, 10) |
| Radio de búsqueda (radius) | Hasta 50 km |
| Histórico (days) | Hasta 90 días |
Si superas un límite, la API responde 429 con la cabecera Retry-After (segundos que hay que esperar). Para descargar todas las gasolineras o las medias de todos los territorios, usa los datos abiertos en CSV. Más detalles en límites.
¿Cada cuánto se actualizan los datos?
Dos veces al día, hacia las 8:00 y las 20:00 (hora peninsular)
Los precios son los que cada gasolinera comunica al Ministerio para la Transición Ecológica y el Reto Demográfico, que los publica en su Geoportal de Gasolineras. Los cargamos dos veces al día: no son precios en tiempo real. Cada respuesta indica la última actualización (last_updated), la próxima (next_update) y la antigüedad de los datos (data_age_seconds). Más en frescura de los datos.
Atribución obligatoria · CC BY 4.0
Fuente: Gasolina hoy (preciosgasolina.es), con datos del Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras).
Muéstrala junto a los datos con un enlace a preciosgasolina.es (o a web_url). Licencia Creative Commons Reconocimiento 4.0 Internacional (CC BY 4.0); atribución y licencia.
Más para desarrolladores
Servidor MCP, asistentes, descargas y widget
Preguntas frecuentes
¿Necesito una clave o registrarme para usar la API?
No. La API es gratuita, no pide registro ni clave y es de solo lectura: basta con hacer peticiones GET (y POST en /v1/route/fuel) a https://api.preciosgasolina.es/v1.
¿Qué límites tiene la API?
120 peticiones por minuto y por IP (y 20 cada 10 segundos); las consultas pesadas, como las de coordenadas, las rutas propias o el histórico de una gasolinera, 30 por minuto. Si te pasas, la respuesta es 429 con la cabecera Retry-After. Cada petición devuelve como mucho 50 resultados, con un radio de hasta 50 km y hasta 90 días de histórico.
¿Cómo devuelve los errores la API?
Con el formato estándar RFC 9457 (application/problem+json), que incluye un campo code con el tipo de error y request_id, el identificador de la petición.
¿En qué formato van los precios?
Como números con punto decimal (por ejemplo, 1.459), en euros (EUR) y por litro (L) o por kilo (kg, en el GNC y el GNL), con impuestos incluidos, tal como los comunica cada gasolinera al Ministerio.
¿Cuánto histórico de precios hay?
La serie diaria de los últimos 90 días de cada gasolinera y de cada territorio, y la serie mensual de España desde 2005.
¿Cómo descargo todas las gasolineras de una vez?
Con los datos abiertos: el CSV de gasolineras de hoy trae todas las gasolineras con sus precios, y las medias diarias de 90 días están en CSV y JSON por España, comunidad y provincia. La API está pensada para consultas concretas, no para descargas completas.
¿Por qué Canarias, Ceuta y Melilla salen aparte en las más baratas?
Porque no pagan el Impuesto sobre Hidrocarburos, así que sus precios no se pueden comparar con los de la península y Baleares. Por eso los rankings de las gasolineras más baratas, en la API y en la web, las muestran aparte.
Fuente de los precios: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras), actualizados dos veces al día, hacia las 8:00 y las 20:00 (hora peninsular). Página revisada el .