# Frescura de los datos

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

Los precios de la API de Gasolina hoy se actualizan dos veces al día, hacia las 8:00 y las 20:00. Cómo leer last_updated, next_update y stale.

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](https://docs.preciosgasolina.es/guias/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](https://docs.preciosgasolina.es/conceptos/limites/#presupuesto-mensual-y-protecci%C3%B3n-del-servicio)), 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».