API de Graus-dia — graus-dia sobre qualquer base, desde 1950

Q: Suportam DJU unifiés / Costic?

Sim — method=costic. Usa apenas o mínimo e o máximo diários com uma ponderação empírica para os dias que atravessam a base, que é aquilo em que os contratos franceses de desempenho energético se fixam. Execute /v1/degree-days/compare-methods sobre um período de que já tenha valores. Se o Costic os reproduzir, use Costic. Essa verificação custa um pedido e evita a discussão.

Q: Posso exportar para CSV ou Excel?

Acrescente format=csv a qualquer pedido de graus-dia num plano pago. Recebe as linhas agregadas — nunca a série horária — com o mesmo intervalo máximo da chamada JSON, a quatro vezes os créditos. Esse limite é deliberado e não a contragosto: o arquivo é aquilo que está a pagar, e uma exportação sem limite é a forma como um concorrente o adquire numa tarde. É o limite que permite ao formato existir.

Desloque a temperatura base

Base °C

18.0

Aquec. / ano

660

Arref. / ano

1 267

Argel · um ano de temperatura média diária Azul necessidade de aquecimento Laranja necessidade de arrefecimento

A área sombreada é o grau-dia. Arraste a base e veja os dois totais trocarem de lugar — essa troca é toda a razão pela qual a base tem de ser a sua. Esta figura usa o método da média diária para poder correr no seu navegador; a API integra a série horária e reproduz estes totais na base 18.

1950 →

76 anos, horário. O concorrente especializado começa em 2000.

4

Métodos de cálculo, porque quem decide é o seu contrato, não nós.

9 km

Malha, em toda a superfície terrestre — sem estação necessária por perto.

livre

Temperatura base, decimais incluídos, resolvida no pedido.

Porque é que os graus-dia gratuitos são normalmente inúteis

A base

A base 18 é a resposta de um só edifício

Pré-calcular graus-dia na base 18 é o atalho óbvio, e é o que torna a maioria dos conjuntos gratuitos comercialmente inúteis. Um escritório bem isolado com ganhos internos equilibra-se mais perto dos 15 °C; um armazém com infiltrações mais perto dos 19. Com uma série na base 18, ambos recebem um número que não descreve nenhum deles.

Guardamos em vez disso a temperatura horária e fazemos a integração quando pede. A base é um parâmetro da consulta.

A média

Uma média diária esconde o dia

Um dia que oscilou entre 8 °C e 22 °C tem uma média de 15 °C. Contra uma base de 18 parece um dia ameno com necessidade modesta de aquecimento. Na realidade o edifício aqueceu com força toda a noite e à tarde não precisou de nada.

Integrar hora a hora preserva isso. É um número diferente, e é o certo — a menos que o seu contrato diga outra coisa, e nesse caso veja abaixo.

Quatro métodos, porque quem decide é o seu contrato

É o detalhe que fecha negócios B2B. A nossa integração horária é a mais fiel fisicamente — e inútil para um cliente cujo contrato está escrito sobre Costic, porque os números dele não vão bater certo. Por isso o método é um parâmetro.

Métodos de graus-dia comparados sobre os mesmos dados, Argel, base 18 °C
method=	Aquec. 18 °C	Arref. 18 °C	Quando usar
`hourly`	781.9	1331.6	Por omissão. Integra o défice ou o excesso horário — o mais fiel fisicamente.
`costic`	741.7	1349.5	DJU unifiés francês. Exigido pelos contratos franceses de desempenho energético.
`mean`	659.9	1267.8	Média diária contra a base. A convenção internacional mais difundida.
`eurostat`	587.7	656.6	Estatística europeia. As bases são fixadas pela definição e ignoram `base`.

Mesmos dados, mesma base, mesmo ano, mesmo lugar — e 18 % de diferença entre a primeira e a terceira linha. Quem lhe entrega «os graus-dia» sem dizer com que método entregou-lhe um número que não vai conseguir reconciliar. /v1/degree-days/compare-methods devolve os quatro de uma vez, para encontrar aquele que reproduz os valores já presentes no seu contrato antes de se comprometer com um plano.

Quatro decisões que aparecem nas suas faturas

Calendário

Dias locais, não dias UTC

Um grau-dia é uma propriedade de um dia de calendário no sítio onde o edifício está. Agrupar por UTC move uma fatia de cada noite para o dia errado e enviesa em silêncio os totais mensais. Cada pedido toma o desvio do local e agrupa em conformidade; os pontos de entrada por cidade conhecem o seu próprio fuso.

Cidades

A ilha de calor urbana, calibrada

A reanálise subestima as zonas construídas em 1–3 °C, o que puxa para baixo os graus-dia de arrefecimento — decisivo se estiver a dimensionar ar condicionado. Os pontos de entrada por cidade aplicam um desvio medido contra observações reais de estações: Argel +0,48 °C, Paris +1,13 °C.

Os pontos de entrada por coordenada não o aplicam, e dizem-no.

Períodos

Diário, semanal, mensal, anual

Os quatro no mesmo pedido, porque os contratos fixam-se em períodos diferentes. As semanas são semanas ISO, por isso 1 de janeiro de 2023 é reportado na semana 52 de 2022 — o que a sua folha de cálculo também fará. Cada balde traz o seu número de dias, para que um mês parcial na borda de um intervalo seja visível em vez de ficar curto em silêncio.

Qualidade

A cobertura, e o que é provisório

Cada resposta traz um bloco quality: horas presentes, cobertura abaixo de 1.0 quando faltam algumas, e uma contagem de provisional_days preenchidos a partir da previsão em vez da reanálise definitiva — o ERA5-Land publica com cerca de cinco dias de atraso. Vê exatamente que parte de um total ainda não é definitiva.

Um pedido, dez anos, um número

GET /v1/degree-days?lat=&lon=&base=&method=&start=&end=

# Paris, base britânica de 15,5 °C, dez anos, linhas mensais
curl -H "X-API-Key: $API_KEY" \
  "https://api.climatememory.com/v1/degree-days\
?lat=48.86&lon=2.35&base=uk&breakdown=monthly\
&start=2015-01-01&end=2024-12-31"

# O mesmo edifício, com o método que o seu contrato nomeia
curl -H "X-API-Key: $API_KEY" \
  "https://api.climatememory.com/v1/degree-days/city/fr/paris\
?base=18&method=costic&start=2024-01-01&end=2024-12-31"

import httpx

# Normalizar uma carteira pelo clima: mesma base, mesmo método, vários locais
def hdd(lat, lon, year, base=15.5, method="hourly"):
    r = httpx.get(
        "https://api.climatememory.com/v1/degree-days",
        params={"lat": lat, "lon": lon, "base": base,
                "method": method, "type": "HDD",
                "start": f"{year}-01-01", "end": f"{year}-12-31"},
        headers={"X-API-Key": API_KEY}, timeout=60,
    )
    r.raise_for_status()
    return r.json()["totals"]["hdd"]

ratio = hdd(48.86, 2.35, 2024) / hdd(48.86, 2.35, 2023)
# consumo +9 %, graus-dia +11 % -> o edifício melhorou

{
  "location": { "latitude": 36.75, "longitude": 3.06,
                 "grid_cell": { "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 } ]
}

# Acrescente format=csv a qualquer pedido. Só em planos pagos.
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
2024,3,131.77,9.62,31,14.05,1.0,false

# O ficheiro traz o local e as datas no nome, por isso continua
# identificável seis meses depois numa pasta de transferências.

Quem compra isto, e para quê

Contratos de desempenho energético

Fechar o ano sem discutir o tempo

Um contrato de poupança garantida tem de separar «o edifício melhorou» de «o inverno foi ameno». Os graus-dia na base e no método do próprio contrato são a forma como essa separação fica escrita — e method=costic é o que um contrato francês vai nomear.

Gestão de carteira

Comparar 400 edifícios em 12 países

Cada local recebe o seu calendário local, a sua célula e, nas cidades, a sua correção de ilha de calor — numa só base e num só método, para a comparação significar alguma coisa. Sem cobertura de estações para verificar primeiro.

Dimensionamento AVAC

Carga de frio contra um clima de frio real

Graus-dia de arrefecimento na base a que o equipamento realmente se equilibra, no centro da cidade e não no aeroporto, onde a malha de reanálise é mais fresca. 76 anos disso, para o ano de projeto ser escolhido em vez de suposto.

Fornecedores de software

Levar os graus-dia dentro do seu próprio produto

A redistribuição comercial é permitida. Ponha os números na sua plataforma de gestão de energia, no seu motor de faturação ou no seu relatório ESG; uma linha de atribuição é a única obrigação que o acompanha.

De onde vêm os números

ERA5-Land, a reanálise Copernicus. Um modelo físico corrido para trás sobre todas as observações alguma vez assimiladas, que produz um campo de temperatura horária numa malha de 9 km, em toda a superfície terrestre, de 1950 até há cerca de cinco dias.

Porque é que isso bate um registo de estação para este trabalho. Uma estação meteorológica carrega cada mudança de sítio, cada troca de instrumento e cada falha do seu historial, por isso uma tendência de trinta anos calculada a partir de uma estação é em parte uma tendência da instrumentação. Uma reanálise não tem nada disso. Também não tem buracos de cobertura: um local a 60 km da estação mais próxima é servido exatamente tão bem como um ao lado de um aeroporto.

Onde é mais fraca. Os centros urbanos, que a reanálise subestima — daí a correção calibrada nos pontos de entrada por cidade. E os últimos cinco dias, provisórios até chegar a reanálise definitiva; a resposta conta esses dias por si.

A licença, que é o que interessa. O Copernicus publica o ERA5-Land sob CC-BY-4.0: uso comercial, redistribuição e obras derivadas explicitamente permitidos. É isso que faz disto um produto e não uma transferência de investigação.

Perguntas frequentes

O que é exatamente um grau-dia?

Uma medida de quanto, e durante quanto tempo, a temperatura exterior esteve abaixo ou acima de uma referência chamada base. Os graus-dia de aquecimento acumulam-se quando está mais frio do que a base, os de arrefecimento quando está mais quente.

São a forma padrão de explicar porque é que um edifício consumiu mais energia neste janeiro do que no anterior, sem confundir o tempo com o comportamento.

Posso usar qualquer temperatura base?

Qualquer valor, decimais incluídos. Também são aceites predefinições com nome: uk (15,5 °C), ashrae (18,333 °C, ou seja 65 °F), iso, france e eurostat (18 °C).

Bases diferentes para aquecimento e arrefecimento são aceites no mesmo pedido, porque um edifício raramente se equilibra no mesmo ponto nos dois sentidos.

Suportam DJU unifiés / Costic?

Sim — method=costic. Usa apenas o mínimo e o máximo diários com uma ponderação empírica para os dias que atravessam a base, que é aquilo em que os contratos franceses de desempenho energético se fixam.

Execute /v1/degree-days/compare-methods sobre um período de que já tenha valores. Se o Costic os reproduzir, use Costic. Essa verificação custa um pedido e evita a discussão.

Até onde recua o arquivo?

A 1 de janeiro de 1950 — 76 anos, horário, em todo o mundo sobre terra, numa malha de 9 km. Um único pedido pode abranger até 10 anos; históricos mais longos são vários pedidos.

Preciso de uma estação meteorológica perto do local?

Não. A reanálise em malha cobre qualquer localização terrestre, incluindo locais sem estação num raio de 60 km. É a sua principal vantagem sobre os fornecedores de graus-dia baseados em estações, a par de não ter mudanças de instrumento nem falhas no historial.

Posso exportar para CSV ou Excel?

Acrescente format=csv a qualquer pedido de graus-dia num plano pago. Recebe as linhas agregadas — nunca a série horária — com o mesmo intervalo máximo da chamada JSON, a quatro vezes os créditos.

Esse limite é deliberado e não a contragosto: o arquivo é aquilo que está a pagar, e uma exportação sem limite é a forma como um concorrente o adquire numa tarde. É o limite que permite ao formato existir.

Quanto custa?

Os graus-dia estão incluídos desde o plano Starter a 19 € por mês: 50 000 créditos, meteorologia incluída, CSV incluído. Um pedido de graus-dia custa dois créditos até um ano, mais um por cada ano adicional.

Com 50 000 créditos são cerca de 25 000 consultas de um ano por mês — suficiente para uma carteira de algumas centenas de edifícios consultada diariamente.

Preços completos →

Posso revender os valores dentro do meu produto?

Sim. O ERA5-Land é publicado sob CC-BY-4.0, que permite uso comercial, redistribuição e obras derivadas. Mostre uma linha de atribuição onde quer que os dados apareçam — /v1/attribution devolve a redação exata e não exige chave.

Verifique contra valores que já tem

Pegue num ano com números já validados, execute compare-methods e veja que método os reproduz. É a forma honesta de comprar isto.

Começar no Starter — 19 € Referência de graus-dia

A sua temperatura base. Não a base 18.