API Degrés-jours

Degrés-jours#

Paramètres

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

Ce qu'est un degré-jour, en un paragraphe

Un degré-jour de chauffage mesure de combien l'air extérieur est resté sous une température de base, et pendant combien de temps. À base 18 °C, une heure à 16 °C apporte (18 − 16) / 24 = 0.083 DJU de chauffage. Sommez les heures et vous obtenez un nombre proportionnel à l'énergie dont un bâtiment a eu besoin. Les degrés-jours de refroidissement sont le miroir : de combien au-dessus de la base. C'est la façon normalisée de comparer une saison de chauffe à une autre une fois la météo retirée de la comparaison.

Plusieurs bases, une requête, un seul prix#

Lire et décoder la série horaire constitue tout le coût d'une réponse de degrés-jours. Une fois ce tableau en mémoire, une base de plus n'est qu'une soustraction dessus : en demander soixante coûte donc ce que coûte en demander une.

La réponse gagne un tableau by_base qui porte chaque base dans l'ordre où vous les avez énumérées. totals et breakdown continuent de décrire la première, si bien que le code écrit avant l'existence de cette option fonctionne toujours à l'identique.

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

Utile quand vous ne savez pas encore quelle base reproduit les chiffres d'un contrat, ou quand le même bâtiment est réglé à des bases différentes par des parties différentes — un bailleur sur 15,5 et un fournisseur d'énergie sur 18 ont tous les deux raison, et ceci renvoie les deux en un seul appel.

Méthodes de calcul#

La méthode est un paramètre parce que c'est votre contrat qui en décide, pas nous. Mêmes données, même base, même année, à Alger :

eurostat ignore complètement base : la définition fixe ses propres seuils, et honorer votre paramètre produirait un nombre qui n'est pas un degré-jour Eurostat tout en prétendant l'être.

/v1/methods ne demande aucune clé. Servez-vous-en pour alimenter un sélecteur de méthode dans votre interface sans rien dépenser, et sans inscrire en dur une liste qui se périmera.

Degrés-jours par ville#

Applique deux corrections qu'une coordonnée nue ne permet pas : le fuseau horaire de la ville, pour que les journées soient découpées localement, et son décalage d'îlot de chaleur urbain calibré.

La réanalyse sous-estime les zones bâties de 1 à 3 °C. Cela biaise les degrés-jours de refroidissement vers le bas — significatif si vous dimensionnez une climatisation, et invisible si vous ne savez pas qu'il faut le chercher.

Des degrés-jours pour votre bâtiment, pas pour la maille#

Une station météo est à l'altitude où elle est, et personne ne peut la déplacer 600 m plus haut sur le versant pour vous. Notre source est un modèle : l'altitude du sol de la maille est donc un nombre dans l'archive, et l'écart relève de l'arithmétique — 0,65 °C par 100 m. Sur une saison de chauffe, ce n'est pas une erreur d'arrondi.

Sur demande explicite, et la réponse dit exactement ce qu'elle a fait :

"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 mise en garde voyage dans la réponse plutôt que sur cette seule page, parce que la personne qui lira ce JSON dans six mois n'est pas celle qui a lu la documentation.

Épingler une maille, pour qu'une base de référence reste comparable#

Toutes les autres façons de désigner un lieu relancent la recherche de maille la plus proche à chaque requête : la réponse dépend donc de ce que l'archive contient aujourd'hui. C'est le bon comportement par défaut pour une consultation ponctuelle, et le mauvais pour une base de référence — une comparaison sur plusieurs années n'est une comparaison que si chaque année vient du même endroit.

À mesure que l'archive s'élargit, la maille la plus proche d'un site donné change — une amélioration de la couverture qui arriverait sinon dans vos données sous la forme d'une marche inexpliquée.

# une fois, à l'installation
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# à chaque fois ensuite
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km vaut 0 sur une requête épinglée, par construction : vous avez nommé la maille, rien ne lui a donc été substitué. Une maille qui n'existe plus renvoie 404 cell_not_found plutôt que de retomber en silence sur une voisine — ce qui réintroduirait exactement la substitution que l'épinglage sert à éviter.

Périodes de ventilation#

Chaque réponse de degrés-jours porte un tableau breakdown agrégé à la période que vous demandez. Les contrats se règlent sur des périodes différentes : les quatre sont donc disponibles sur la même requête au même prix.

Chaque intervalle porte également days, si bien qu'un mois partiel au bord de votre plage est visible plutôt que silencieusement écourté. Un mois de février avec "days": 12 est un février que vous ne devriez pas comparer à un février complet.

Totaux mensuels pour une année#

Un raccourci pour le cas courant : ?lat=&lon=&year=2025 et douze lignes reviennent. Mêmes données que /v1/degree-days?breakdown=monthly sur la même amplitude ; moins de paramètres à se tromper.

/v1/coverage rapporte le premier et le dernier jour de l'archive ainsi que sa résolution, ne demande aucune clé, et c'est ce qu'il faut vérifier avant de demander une période proche du bord présent — ERA5-Land accuse environ cinq jours de retard, et provisional_days dans votre réponse en est la conséquence.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // dernier jour qui CONTIENT des données
  "axis_end": "2026-12-31",   // là où ce run cessera de croître
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Export CSV#

Ajoutez format=csv à n'importe quelle requête de degrés-jours. Vous obtenez les lignes de breakdown sous forme de fichier CSV, nommé d'après le lieu et les dates, de sorte qu'il reste identifiable six mois plus tard dans un dossier de téléchargements.

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

Formules payantes uniquement, et borné : la même amplitude maximale qu'une requête JSON, les lignes agrégées seulement — jamais la série horaire — et cela coûte quatre crédits pour chaque crédit que coûte l'appel JSON équivalent. Une clé gratuite obtient 402 export_not_in_plan.

C'est délibéré, et non concédé à contrecœur. C'est l'archive que vous payez, et un export sans borne est la façon dont un concurrent se la procure en une après-midi. Ce sont ces bornes qui permettent au format d'exister.

Historique horaire#

Paramètres

L'archive même dont sont bâtis les degrés-jours, servie directement : horaire, jusqu'à 1950, sur une grille de 9 km, partout sur les terres émergées. Même hôte et même scope dju — si vous pouvez appeler les degrés-jours, vous pouvez appeler ceci.

Pour des valeurs quotidiennes sur une longue période, ou pour des normales et des tendances, utilisez plutôt l'API Climat — elle détient les champs quotidiens pré-dérivés, n'a pas de frontière à 9 km ni à 1950, et répond à toute une climatologie en un seul appel.

Historique par ville#

Deux choses qu'une coordonnée ne peut pas porter : le fuseau horaire de la ville, pour que les journées soient découpées là où la ville les vit réellement, et sa correction calibrée d'îlot de chaleur urbain. daily vaut true par défaut ici, parce qu'une requête par ville est presque toujours une requête portant sur des journées.

Variables disponibles#

Énumère ce que l'archive contient en ce moment, avec les unités, et quels champs sont dérivés plutôt que stockés. Une archive ingérée pour les seuls degrés-jours ne contient que la température, et cet endpoint le dit franchement au lieu de renvoyer des colonnes de null.