API de Grados-día

Grados-día#

Parámetros

{
  "location": {
    "latitude": 36.75, "longitude": 3.06,
    "grid_cell": { "latitude": 36.7, "longitude": 3.1,
                   "distance_km": 6.61, "resolution_km": 9 }
  },
  "parameters": {
    "base_temperature_c": 18.0, "method": "hourly",
    "start": "2025-07-01", "end": "2026-06-30"
  },
  "totals": { "hdd": 781.86, "cdd": 1331.61 },
  "quality": {
    "days": 365, "coverage": 1.0,
    "missing_hours": 0, "provisional_days": 0
  },
  "breakdown": [ { "year": 2025, "month": 7, "hdd": 0.0, "cdd": 289.4, "days": 31 } ]
}

Qué es un grado-día, en un párrafo

Un grado-día de calefacción mide cuánto por debajo de una temperatura base estuvo el aire exterior, y durante cuánto tiempo. Con base 18 °C, una hora a 16 °C aporta (18 − 16) / 24 = 0.083 GDC. Sume las horas y tendrá una cifra proporcional a la energía que un edificio necesitó. Los grados-día de refrigeración son el espejo: cuánto por encima de la base. Es la forma normalizada de comparar una temporada de calefacción con otra una vez retirada la meteorología de la comparación.

Varias bases, una solicitud, un solo precio#

Leer y descodificar la serie horaria constituye todo el coste de una respuesta de grados-día. Una vez ese array está en memoria, una base más es solo una resta sobre él: pedir sesenta cuesta lo que cuesta pedir una.

La respuesta gana un array by_base con cada base en el orden en que usted las enumeró. totals y breakdown siguen describiendo la primera, de modo que el código escrito antes de que esto existiera sigue funcionando sin cambios.

"by_base": [
  {"base": 15.0,  "hdd": 402.11, "cdd": 1731.4},
  {"base": 15.5,  "hdd": 431.02, "cdd": 1706.3},
  {"base": 18.0,  "hdd": 781.86, "cdd": 1331.6}
]

Útil cuando aún no sabe qué base reproduce las cifras de un contrato, o cuando el mismo edificio se liquida con bases distintas por partes distintas — un arrendador con 15,5 y una comercializadora con 18 tienen ambos razón, y esto devuelve ambas en una sola llamada.

Métodos de cálculo#

El método es un parámetro porque lo decide su contrato, no nosotros. Los mismos datos, la misma base, el mismo año, en Argel:

eurostat ignora base por completo: la definición fija sus propios umbrales, y respetar su parámetro produciría una cifra que no es un grado-día de Eurostat mientras dice serlo.

/v1/methods no necesita clave. Úselo para poblar un selector de método en su interfaz sin gastar nada y sin incrustar una lista que quedará obsoleta.

Grados-día por ciudad#

Aplica dos correcciones que una coordenada pelada no permite: el huso horario de la ciudad, para que los días se corten localmente, y su desplazamiento por isla de calor urbana calibrado.

El reanálisis subestima las zonas edificadas en 1 a 3 °C. Eso sesga a la baja los grados-día de refrigeración — relevante si está dimensionando un aire acondicionado, e invisible si no sabe que hay que buscarlo.

Grados-día para su edificio, no para la celda de la malla#

Una estación meteorológica está a la altitud a la que está, y nadie puede subirla 600 m por la ladera del valle por usted. Nuestra fuente es un modelo: la altitud del terreno de la celda es, pues, una cifra del archivo, y la diferencia es aritmética — 0,65 °C por cada 100 m. A lo largo de una temporada de calefacción eso no es un error de redondeo.

Es opcional, y la respuesta dice exactamente qué hizo:

"elevation": {
  "applied": true,
  "model_elevation_m": 42.0,
  "location_elevation_m": 1200,
  "temperature_offset_c": -7.53,
  "caveat": "Lapse-rate correction. It assumes temperature falls smoothly with
             height, which a valley floor under a winter inversion does not."
}

La advertencia viaja en la respuesta y no solo en esta página, porque quien lea ese JSON dentro de seis meses no es quien leyó la documentación.

Fijar una celda para que una línea de base siga siendo comparable#

Cualquier otra forma de indicar un lugar vuelve a lanzar la búsqueda de la celda más próxima en cada solicitud: la respuesta depende, pues, de lo que el archivo contenga hoy. Es el comportamiento adecuado por defecto para una consulta puntual, y el equivocado para una línea de base — una comparación a varios años solo es una comparación si cada año procede del mismo sitio.

A medida que el archivo se amplía, la celda más próxima a un emplazamiento dado cambia — una mejora de la cobertura que, de otro modo, llegaría a sus datos como un escalón inexplicado.

# una vez, en la instalación
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# cada vez a partir de entonces
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km vale 0 en una solicitud fijada por construcción: usted nombró la celda, así que no se sustituyó nada. Una celda que ya no existe devuelve 404 cell_not_found en lugar de recurrir en silencio a una vecina — lo que reintroduciría exactamente la sustitución que usted fijó para evitar.

Periodos de desglose#

Cada respuesta de grados-día lleva un array breakdown agregado al periodo que usted pida. Los contratos se liquidan sobre periodos distintos, así que los cuatro están disponibles en la misma solicitud al mismo precio.

Cada intervalo lleva además days, de modo que un mes parcial en el borde de su rango es visible en lugar de quedarse corto en silencio. Un febrero con "days": 12 es un febrero que no debería comparar con uno completo.

Totales mensuales de un año#

Un atajo para el caso habitual: ?lat=&lon=&year=2025 y vuelven doce filas. Los mismos datos que /v1/degree-days?breakdown=monthly sobre el mismo intervalo; menos parámetros que equivocar.

/v1/coverage informa del primer y el último día del archivo y de su resolución, no necesita clave, y es lo que conviene comprobar antes de pedir un periodo cercano al borde presente — ERA5-Land va unos cinco días por detrás, y provisional_days en su respuesta es la consecuencia.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // último día que CONTIENE datos
  "axis_end": "2026-12-31",   // hasta dónde dejará de crecer esta pasada
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Exportación CSV#

Añada format=csv a cualquier solicitud de grados-día. Obtendrá las filas de breakdown como archivo CSV, con un nombre basado en el lugar y las fechas, de modo que siga siendo identificable seis meses después en una carpeta de descargas.

year,month,hdd,cdd,days,t_mean,coverage,provisional
2024,1,205.03,2.88,31,11.48,1.0,false
2024,2,168.44,4.10,29,12.31,1.0,false

Solo planes de pago, y acotado: el mismo intervalo máximo que una solicitud JSON, solo filas agregadas — nunca la serie horaria — y cuesta cuatro créditos por cada uno que cuesta la llamada JSON equivalente. Una clave gratuita recibe 402 export_not_in_plan.

Es deliberado, y no una concesión a regañadientes. Lo que usted paga es el archivo, y una exportación sin límites es la forma en que un competidor lo adquiere en una tarde. Son esos límites los que permiten que el formato exista siquiera.

Histórico horario#

Parámetros

El mismo archivo con el que se construyen los grados-día, servido directamente: horario, hasta 1950, sobre una malla de 9 km, en toda la superficie terrestre. Mismo host y mismo scope dju — si puede llamar a los grados-día, puede llamar a esto.

Para valores diarios sobre un periodo largo, o para normales y tendencias, use en su lugar la API de Clima — tiene los campos diarios ya derivados, no tiene frontera de 9 km ni de 1950, y responde a toda una climatología en una sola llamada.

Histórico por ciudad#

Dos cosas que una coordenada no puede llevar: el huso horario de la ciudad, para que los días se corten donde la ciudad los vive realmente, y su corrección calibrada por isla de calor urbana. daily vale true por defecto aquí, porque una solicitud por ciudad es casi siempre una solicitud sobre días.

Variables disponibles#

Enumera lo que el archivo contiene en este momento, con unidades, y qué campos son derivados en lugar de almacenados. Un archivo ingerido solo para grados-día contiene únicamente la temperatura, y este endpoint lo dice sin rodeos en lugar de devolver columnas de null.