API Graus-dia

Graus-dia#

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 } ]
}

O que é um grau-dia, num parágrafo

Um grau-dia de aquecimento mede quanto o ar exterior esteve abaixo de uma temperatura de base, e durante quanto tempo. Na base 18 °C, uma hora a 16 °C contribui (18 − 16) / 24 = 0.083 HDD. Some as horas e tem um número proporcional à energia de que um edifício precisou. Os graus-dia de arrefecimento são o espelho: quanto acima da base. É a maneira habitual de comparar uma época de aquecimento com outra depois de se ter retirado a meteorologia da comparação.

Muitas bases, um pedido, um preço#

Ler e descodificar a série horária é o custo inteiro de uma resposta de graus-dia. Uma vez esse vetor em memória, outra base é uma subtração sobre ele, por isso pedir sessenta custa o que custa pedir uma.

A resposta ganha um vetor by_base com todas as bases pela ordem em que as listou. totals e breakdown continuam a descrever a primeira, para que o código escrito antes disto existir continue a funcionar sem alterações.

"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 quando ainda não sabe que base reproduz os valores de um contrato, ou quando o mesmo edifício é liquidado em bases diferentes por partes diferentes — um senhorio na 15,5 e um comercializador de energia na 18 têm ambos razão, e isto devolve as duas numa só chamada.

Métodos de cálculo#

O método é um parâmetro porque quem o decide é o seu contrato, não nós. Os mesmos dados, a mesma base, o mesmo ano, em Argel:

O eurostat ignora base por completo: a definição fixa os seus próprios limiares, e honrar o seu parâmetro produziria um número que não é um grau-dia Eurostat enquanto afirmava sê-lo.

/v1/methods não precisa de chave. Use-o para preencher um seletor de métodos na sua interface sem gastar nada, e sem fixar no código uma lista que vai envelhecer.

Graus-dia por cidade#

Aplica duas correções que uma coordenada nua não pode: o fuso horário da cidade, para que os dias sejam cortados localmente, e o seu desvio calibrado de ilha de calor urbana.

A reanálise subestima as zonas edificadas em 1–3 °C. Isso enviesa os graus-dia de arrefecimento por defeito — o que é material se está a dimensionar ar condicionado, e invisível se não souber que deve procurá-lo.

Graus-dia para o seu edifício, não para a célula da grelha#

Uma estação meteorológica está à altitude a que está, e ninguém a pode subir 600 m pela encosta acima por si. A nossa fonte é um modelo, por isso a altitude do terreno da célula é um número no arquivo e a diferença é aritmética: 0,65 °C por cada 100 m. Ao longo de uma época de aquecimento, isso não é um erro de arredondamento.

É opcional, e a resposta diz exatamente o que fez:

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

A ressalva viaja na resposta e não apenas nesta página, porque quem ler o JSON daqui a seis meses não é quem leu a documentação.

Fixar uma célula, para que uma referência continue comparável#

Todas as outras formas de localização voltam a correr a procura da célula mais próxima em cada pedido, pelo que a resposta depende do que o arquivo tem hoje. É o comportamento certo para uma consulta pontual, e o errado para uma referência: uma comparação plurianual só é uma comparação se cada ano vier do mesmo sítio.

À medida que o arquivo se alarga, a célula mais próxima de um dado local muda — uma melhoria de cobertura que de outro modo chegaria aos seus dados como um degrau inexplicado.

# uma vez, na configuração
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# todas as vezes depois disso
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km é 0 num pedido fixado por construção: nomeou a célula, por isso nada foi substituído. Uma célula que já não existe devolve 404 cell_not_found em vez de cair em silêncio para uma vizinha — o que reintroduziria exatamente a substituição que a fixação evita.

Períodos de detalhe#

Todas as respostas de graus-dia trazem um vetor breakdown agregado ao período que pedir. Os contratos liquidam-se em períodos diferentes, por isso os quatro estão disponíveis no mesmo pedido e ao mesmo preço.

Cada balde traz também days, para que um mês parcial no limite do seu intervalo seja visível em vez de silenciosamente curto. Um fevereiro com "days": 12 é um fevereiro que não deve comparar com um completo.

Totais mensais de um ano#

Um atalho para o caso comum: ?lat=&lon=&year=2025 e voltam doze linhas. Os mesmos dados que /v1/degree-days?breakdown=monthly sobre o mesmo intervalo; menos parâmetros para errar.

/v1/coverage reporta o primeiro e o último dia do arquivo e a sua resolução, não precisa de chave, e é o que deve verificar antes de pedir um período junto ao limite presente — o ERA5-Land anda cerca de cinco dias atrasado, e os provisional_days na sua resposta são a consequência.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // último dia que TEM dados
  "axis_end": "2026-12-31",   // até onde este run vai deixar de crescer
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Exportação CSV#

Acrescente format=csv a qualquer pedido de graus-dia. Recebe as linhas do breakdown como ficheiro CSV, com um nome que refere o local e as datas para que continue identificável seis meses depois numa pasta de transferências.

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

Só planos pagos, e com limites: o mesmo intervalo máximo de um pedido JSON, apenas linhas agregadas — nunca a série horária — e custa quatro créditos por cada um que a chamada JSON equivalente custa. Uma chave gratuita recebe 402 export_not_in_plan.

Isso é deliberado e não mesquinho. O arquivo é aquilo por que está a pagar, e uma exportação sem limites é como um concorrente o adquire numa tarde. São os limites que permitem que o formato exista de todo.

Histórico horário#

Parâmetros

O mesmo arquivo a partir do qual os graus-dia são construídos, servido diretamente: horário, desde 1950, numa grelha de 9 km, em toda a terra firme. O mesmo anfitrião e o mesmo scope dju — se pode chamar os graus-dia, pode chamar isto.

Para valores diários ao longo de um período longo, ou para normais e tendências, use antes a API Clima — tem os campos diários já derivados, não tem a fronteira dos 9 km/1950, e responde a uma climatologia inteira numa só chamada.

Histórico por cidade#

Duas coisas que uma coordenada não pode trazer: o fuso horário da cidade, para que os dias sejam cortados onde a cidade realmente os vive, e a sua correção calibrada de ilha de calor urbana. Aqui o daily vale true por omissão, porque um pedido por cidade é quase sempre um pedido sobre dias.

Variáveis disponíveis#

Lista o que o arquivo tem neste momento, com unidades, e quais os campos derivados em vez de armazenados. Um arquivo ingerido só para graus-dia tem apenas temperatura, e este endpoint di-lo com clareza em vez de devolver colunas de null.