Frescura de los datos

Los precios se actualizan dos veces al día, hacia las 8:00 y las 20:00 (hora peninsular), cuando Gasolina hoy recoge los datos que las gasolineras han comunicado al Ministerio. No son en tiempo real: entre dos actualizaciones, la API devuelve siempre los mismos precios, y una gasolinera puede haber cambiado el suyo en el surtidor.

Los campos de frescura

Cada respuesta (y cada resultado del MCP) lleva en meta:

Campo	Ejemplo	Para qué sirve
last_updated	2026-10-07T06:12:00.000Z	Cuándo se actualizaron los datos. Muéstralo siempre, en hora de Madrid (en el ejemplo, las 8:12).
next_update	2026-10-07T18:10:00.000Z	Cuándo está prevista la próxima actualización (en el ejemplo, las 20:10 de Madrid). Úsalo para cachear.
data_age_seconds	7430	Antigüedad de los datos en segundos en el momento de responder.
stale	false	true si se sirve la última copia buena porque la fuente no respondió.

Las fechas van en UTC (sufijo Z). En horario de verano, Madrid va dos horas por delante (UTC+2) y en invierno, una (UTC+1).

Nota

next_update es la hora prevista. La actualización tarda unos minutos y puede retrasarse; si al volver a pedir los datos last_updated no ha cambiado, espera unos minutos.

Histórico

• El histórico diario (/v1/history, /v1/stations/{id}/history) tiene un punto por día. El valor definitivo del día anterior se completa una vez al día, por la mañana.
• La serie mensual (/v1/history/monthly) viene del Boletín Petrolero de la UE y se actualiza periódicamente, no dos veces al día.
• Los informes (/v1/reports) solo existen para meses cerrados.

Caché alineada con las actualizaciones

La API guarda cada respuesta con precios hasta la próxima actualización: la cabecera Cache-Control de esas respuestas es public, max-age=<segundos hasta next_update, como mucho 3600>, stale-while-revalidate=300. Haz lo mismo en tu aplicación: guarda la respuesta hasta meta.next_update y no vuelvas a pedirla antes. Ver Integrar en tu web.

stale: cuando la fuente no responde

Si la base de datos de la que lee la API falla o va lenta, o si la API está protegiéndose (ver Límites), no se deja de responder: se sirve la última copia buena de esa misma respuesta (se guarda hasta 7 días) con meta.stale: true, X-Cache: stale y Cache-Control: public, max-age=60. Los datos son correctos, pero pueden ser de una actualización anterior: muestra last_updated y vuelve a pedirlos en un minuto. Si no hay copia, la API responde 503 (TEMPORARILY_UNAVAILABLE) con Retry-After.

Cómo decirlo en tu interfaz

• «Precios del Ministerio actualizados hoy a las 8:12.»
• «Datos de las 20:10. Próxima actualización hacia las 8:00.»
• En asistentes: «según los datos del Ministerio de esta mañana…», nunca «ahora mismo».