L'API d'intensité carbone de l'électricité française — souveraine, open source et dev-first.
L'équivalent français de carbonintensity.org.uk, bâti sur les données ouvertes RTE / éCO2mix via ODRÉ.
L'intensité carbone du réseau électrique français (en gCO₂eq/kWh) est une donnée publique précieuse — pour décaler une recharge de véhicule, planifier un batch de calcul, ou afficher l'empreinte d'un service. Mais la source officielle reste brute, plafonnée en appels, et sans prévision d'intensité.
carbon-fr la rend directement consommable par des développeurs et des machines :
- 🇫🇷 Souverain & auto-hébergeable — aucune dépendance propriétaire obligatoire, licences OSI.
- 🚀 Dev-first — API REST lisible et versionnée (
/v1), OpenAPI 3.1 + Swagger UI servis, collection Bruno, SDK TypeScript (sdk/typescript/). - 🛡️ Résilient au quota — un poller unique alimente la base ; l'API sert tous les clients depuis ce read-model : la consommation du quota ODRÉ est fixe (~1 350 appels/jour au total, dont ~1 150 sur le jeu régional, soit ≈ 70 % de son plafond de 50 000 appels/mois — le quota ODRÉ est compté par jeu de données et par client), quel que soit le nombre de clients.
- 🔬 Méthodologie versionnée — chaque mesure porte sa méthode de calcul (
rte-directetacv-ademe— cycle de vie production et consommation), jamais de changement silencieux. - 🔮 Prévision comme valeur ajoutée — l'intensité prévisionnelle n'existe pas à la source :
carbon-frla modélise derrière un port dédié (climatology@1, gardée par backtest). - ⏱️ Carbon-aware & live — primitives de scheduling (créneau sous échéance, lowest-k, seuil, économie), flux SSE, et webhooks signés (sur clé API).
Aucune installation : l'instance hébergée répond tout de suite. L'intensité carbone courante du réseau national, en une requête :
curl https://carbon-fr-api.kovelt.fr/v1/intensity/now{
"region": "national",
"timestamp": "2026-06-17T06:30:00Z",
"intensity": { "value": 20.0, "unit": "gCO2eq/kWh" },
"index": "low",
"methodology": "rte-direct",
"methodology_version": 1,
"vintage": "tr"
}Ajoute ?methodology=acv-ademe pour le cycle de vie, et ?region=<slug>&methodology=acv-ademe pour l'une des 12 régions — le défaut rte-direct est national uniquement : sans methodology, une région répond 404 no_data sur /v1/intensity/now (comme sur /mix, /intensity/stats et la prévision), et /v1/intensity/date renvoie une série vide (cf. Fonctionnalités). Le champ index est la lecture qualitative de intensity — very-low à very-high, bornes basses incluses, donc low pour 20 g (barème et sources : « Index qualitatif », même section). Les réponses sont compressées à la demande (Accept-Encoding: gzip ou br, soit curl --compressed) — un an d'historique national rte-direct (le défaut) sur /v1/intensity/date passe d'environ 2 Mo à moins de 100 Ko (en acv-ademe, valeurs non arrondies : ≈ 2,4 Mo → ≈ 320 Ko) ; le flux SSE n'est jamais compressé (ni les réponses de quelques octets comme /health, ni /metrics).
📊 En CSV — l'historique (/v1/intensity/date, fenêtre ≤ 366 jours) s'exporte pour un tableur ou pandas : envoie l'en-tête Accept: text/csv ou ajoute ?format=csv (pratique pour les outils qui ne règlent pas les en-têtes). format prime sur Accept ; sans l'un ni l'autre, ou avec format=json, la réponse reste du JSON. La réponse CSV est une pièce jointe text/csv écrite en flux — une ligne d'en-tête timestamp,intensity,unit,region,methodology,methodology_version,vintage,index puis une ligne par mesure, mêmes valeurs que le JSON ; methodology_version (entier) distingue acv-ademe production (1) et consommation (2), rte-direct vaut 1 ; index (dernière colonne) est l'index qualitatif du point, comme dans le JSON. Les erreurs restent en application/problem+json, même quand le CSV est demandé.
curl -H 'Accept: text/csv' 'https://carbon-fr-api.kovelt.fr/v1/intensity/date?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z'
# ou, enregistré sous le nom proposé par le serveur (carbon-fr_intensity_national_20260101T000000Z_20260201T000000Z.csv) :
curl -OJ 'https://carbon-fr-api.kovelt.fr/v1/intensity/date?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z&format=csv'🌐 Dans le navigateur — explore et essaie tous les endpoints depuis la Swagger UI : carbon-fr-api.kovelt.fr/docs.
📦 En TypeScript / JavaScript — le SDK officiel (@carbon-fr/sdk, zéro dépendance runtime) :
npm install @carbon-fr/sdkimport { CarbonFr } from "@carbon-fr/sdk";
const cf = new CarbonFr(); // instance hébergée par défaut
const now = await cf.intensityNow();
console.log(now.intensity.value, now.intensity.unit); // 20 gCO2eq/kWh🦀 En Rust — le cœur métier est publié sur crates.io (bibliothèques pures, sans IO : calculs d'intensité, méthodologies, prévision, éligibilité électrolyseur) : carbonfr-core (docs.rs) et carbonfr-eligibility (docs.rs), MSRV 1.88, politique de publication dans l'ADR-0030. Pour interroger l'API depuis Rust : le client HTTP typé et asynchrone carbonfr-sdk (docs.rs, ADR-0031), en parité avec le SDK TypeScript, flux temps réel compris (feature stream).
cargo add carbonfr-sdk # client HTTP de l'API /v1 ; ajouter --features stream pour le flux SSE
cargo add carbonfr-core # domaine pur, sans IO| Endpoint | Nature | Statut |
|---|---|---|
GET /v1/intensity/now |
Intensité courante (national + 12 régions) | ✅ |
GET /v1/intensity/now/all |
Intensité courante de toutes les régions en un appel (?methodology=acv-ademe pour les 13 ; national seul en rte-direct) |
✅ |
GET /v1/intensity/index |
Barème de l'index qualitatif index (very-low → very-high, bornes sourcées 20 · 64,8 · 100 · 200 gCO₂eq/kWh — ADR-0033) porté par /intensity/now, /now/all, /date (JSON et dernière colonne CSV), /forecast et le flux SSE |
✅ |
GET /v1/mix |
Mix de production par filière (MW) + parts de production shares |
✅ |
GET /v1/regions |
Catalogue des régions servies (slug, libellé, code INSEE) — les valeurs de ?region= |
✅ |
GET /v1/exchanges |
Échanges transfrontaliers par frontière (flux signé + carbone du voisin, ENTSO-E) | ✅ |
GET /v1/exchanges/date?from=&to= |
Série historique des échanges transfrontaliers | ✅ |
GET /v1/weather · /weather/date |
Météo nationale (vent 100 m + irradiance, Open-Meteo CC-BY) | ✅ |
GET /v1/renewable |
Production renouvelable estimée depuis la météo + facteur de charge (ADR-0018) | ✅ |
GET /v1/intensity/date?from=&to= |
Historique sur un intervalle (millésimes tr / consolidated / definitive) — JSON, ou CSV en flux (?format=csv ou Accept: text/csv) |
✅ |
GET /v1/intensity/stats?from=&to=[&interval=hour|day] |
Résumé (moyenne/min/max) + série agrégée | ✅ |
GET /v1/intensity/forecast |
Prévision d'intensité (climatology@1 ; acv-ademe@2 via ?methodology=acv-ademe&version=2) |
✅ |
GET /v1/intensity/greenest-window |
Créneau le plus bas-carbone (+ overlay électrolyseur ?eligibility=rfnbo|low-carbon, ADR-0025/0026) |
✅ |
GET /v1/eligibility/rulesets |
Catalogue des cadres d'éligibilité électrolyseur (rulesets versionnés, servis + planifiés) | ✅ |
GET /v1/schedule · /schedule/slots · /intensity/below |
Scheduling carbon-aware (échéance, lowest-k, seuil + économie) | ✅ |
GET /v1/intensity/stream |
Flux live (Server-Sent Events) | ✅ |
GET /v1/methodologies · /factors |
Catalogue des méthodes + table des facteurs (vérifiabilité) | ✅ |
GET /v1/price · /price/date |
Décomposition du prix payé ancrée sur le TRV (énergie spot ENTSO-E + TURPE + taxes + résidu, ADR-0023) | ✅ |
GET /v1/cost-reference |
Couche comparative LCOE (coût de production), estimation en fourchette, jamais soustraite du marché (ADR-0024) | ✅ |
POST/GET/DELETE /v1/webhooks |
Abonnements webhook signés (clé API requise), désactivés automatiquement après une série de livraisons échouées (status) puis purgés après CARBONFR_WEBHOOK_PURGE_DAYS jours (défaut 30) |
✅ |
GET /v1/stats · POST /v1/stats/visit |
Compteur de consultation (IP jamais stockée, empreinte salée) | ✅ |
Les endpoints d'intensité (/intensity/now, /intensity/date, /intensity/stats, /mix) acceptent ?region=<slug> (national par défaut ; slugs listés par /v1/regions et énumérés dans l'OpenAPI) et ?methodology=<id> : rte-direct (estimation RTE, combustion directe — défaut, national uniquement) ou acv-ademe (cycle de vie ADEME, national + 12 régions, ADR-0008) ; &version=2 (vue consommation, national uniquement) est acceptée par /intensity/now, /intensity/date et /intensity/stats (fenêtre ramenée à 92 jours en vue consommation) ainsi que par /intensity/forecast, mais refusée (400) par /mix (le mix servi est celui de production), /intensity/now/all, /intensity/greenest-window, /intensity/below, /schedule et /schedule/slots. Les endpoints de prix, coût, échanges, météo, renouvelable et catalogue (/price, /cost-reference, /exchanges, /weather, /renewable, /methodologies, /factors) n'ont pas de dimension régionale : /price renvoie 400 hors national ; /exchanges, /weather et /renewable sont nationaux ; /cost-reference mêle sources françaises et LCOE mondiaux IRENA (champ geography) ; les catalogues /methodologies et /factors valent pour le national comme pour les régions.
Index qualitatif (ADR-0033, barème index@1) : /intensity/now, chaque entrée de /intensity/now/all, chaque point de /intensity/date (JSON, et dernière colonne index du CSV) et de /intensity/forecast (calculé sur expected), ainsi que chaque événement du flux SSE, portent un champ index — very-low, low, moderate, high ou very-high — qui se lit sans connaître l'unité. Un seul barème absolu sert toutes les méthodologies et toutes les régions, bornes basses incluses et hautes exclues (une valeur égale à une borne tombe dans la bande supérieure), chaque borne étant sourcée : < 20 gCO₂eq/kWh = very-low (mix nucléaire, hydraulique et éolien : facteurs ACV ADEME) ; < 64,8 = low (18 gCO₂eq/MJ × 3,6, seuil RFNBO de la zone de dépôt, règl. délégué (UE) 2023/1184 art. 4 §2) ; < 100 = moderate (seuil de la taxonomie européenne, règl. délégué (UE) 2021/2139) ; < 200 = high (≈ la moitié du facteur gaz en cycle combiné, 406 g selon l'ADEME) ; ≥ 200 = very-high. Le catalogue GET /v1/intensity/index sert ce barème — bandes, bornes et source de chaque borne — pour qu'il reste auditable, comme /v1/factors l'est pour l'ACV. L'index est calculé à la lecture, jamais stocké, et n'existe ni sur /intensity/stats (l'index d'une moyenne n'est pas la moyenne des index) ni sur /intensity/greenest-window. C'est la même lecture à cinq bandes que l'index de carbonintensity.org.uk (libellés en kebab-case ici, comme tous les identifiants de l'API), mais pas les mêmes seuils : ceux de NESO, l'opérateur du réseau britannique, sont programmés à la baisse année par année jusqu'en 2030, les nôtres sont fixes. Limites : en France, le national est very-low ou low la quasi-totalité du temps, donc l'index ne dit pas quand consommer — pour choisir une heure, utiliser /intensity/forecast, /intensity/greenest-window, /intensity/below ou /schedule ; et comme le régional acv-ademe est basé production (ADR-0008), une région importatrice peut être high ou very-high quand ses centrales de pointe tournent, alors que sa consommation est en grande partie décarbonée.
/intensity/greenest-window accepte en plus ?eligibility=rfnbo|low-carbon (overlay « électrolyseur », ADR-0025/0026) : chaque créneau de la fenêtre est annoté de son éligibilité au regard du cadre choisi — rfnbo (part renouvelable ≥ 90 % ou prix day-ahead ≤ 20 €/MWh, Règl. UE 2023/1184) ou low-carbon (intensité ≤ seuil indicatif dérivé de l'acte délégué 2025/2359) — en réponse additive (rien ne change sans le paramètre), avec verdicts pass/fail/indeterminate et disclaimer de neutralité. Le catalogue des rulesets versionnés est servi par /v1/eligibility/rulesets. Aucune des quatre méthodes de comptabilisation de l'électricité réseau définies par l'annexe du 2025/2359 n'est mise en œuvre par carbon-fr — ni par ce seuil indicatif, ni par la prévision, ni par la technologie marginale estimée de /v1/price : l'alignement et les écarts, méthode par méthode (les méthodes horaires (b)/(d) exigent une donnée publiée par le GRT, (a) repose sur la Table 5 officielle, (c) sur un comptage d'heures pleine charge non implémenté), sont documentés dans l'addendum O1 de l'ADR-0026.
La spécification OpenAPI 3.1 (dérivée du code via utoipa) est servie sous GET /v1/openapi.json, et une Swagger UI sous GET /docs. Une collection Bruno versionnée (dossier bruno/) couvre les endpoints /v1 (cas nominaux + erreurs) et les sondes /health*, hors flux SSE /v1/intensity/stream ; la carte /hydrogene (hors /v1) n'y figure pas.
Une carte « électrolyseurs × carbone live » est servie sous GET /hydrogene (hors contrat /v1, comme /docs) : les 233 électrolyseurs européens géolocalisés (European Hydrogen Observatory, instantané semestriel) croisés avec l'intensité carbone régionale live et les fenêtres d'éligibilité rfnbo/low-carbon (ADR-0029). Sa légende est celle de l'index qualitatif : ses cinq bandes sont lues au chargement dans GET /v1/intensity/index (une seule échelle dans le produit). Page auto-contenue — aucun CDN, aucune tuile externe.
Les horodatages (timestamp, from/to, start/end, y compris dans le CSV et le flux SSE) sont des instants RFC 3339 en UTC (suffixe Z). Les paramètres from, to et deadline acceptent n'importe quel décalage — 2026-10-25T02:00:00%2B02:00 désigne le même instant que 2026-10-25T00:00:00Z — mais le + doit être encodé %2B dans une query string (un + brut y est lu comme une espace et répond 400) ; la réponse rend toujours l'instant en UTC.
Les erreurs suivent RFC 9457 (application/problem+json) : type/title/status/detail + un champ code court et stable (no_data, bad_request…) sur lequel s'aligner. Côté disponibilité, l'API peut répondre 503 (unavailable) quand une donnée dérivée n'est pas encore prête — p. ex. /v1/renewable si le modèle n'est pas calibré, ou /health/ready si la base est injoignable —, au-delà du plafond de connexions SSE simultanées sur /v1/intensity/stream (300 par défaut, CARBONFR_SSE_MAX_CONNECTIONS, avec un en-tête Retry-After), ou sur toute route dont le traitement dépasse le délai de requête (60 s par défaut, CARBONFR_REQUEST_TIMEOUT_SECS) — et /v1/price renvoie 404 si aucune source de prix spot n'est configurée (token ENTSO-E absent).
Tier hébergé & clés API (ADR-0015, opt-in) : par défaut l'API est anonyme et sans quota (parité avec l'auto-hébergement). L'opérateur peut activer une limite de débit (CARBONFR_RATELIMIT_ENABLED=1) — anonyme 60 req/min, clé Free 600 req/min, en-têtes RateLimit-*, 429 (rate_limited) au dépassement. Une clé API (Bearer, requise pour les webhooks) se délivre côté serveur via la sous-commande mint-key : l'empreinte est stockée, la clé n'est affichée qu'une seule fois.
Un compteur de consultation sobre est exposé (GET /v1/stats, POST /v1/stats/visit) : l'IP n'est jamais stockée — seule une empreinte SHA-256 salée sert à dédupliquer (unique par IP/jour), RGPD-friendly.
Couverture National + 12 régions métropolitaines. Le
taux_co2publié par RTE (rte-direct) n'existe qu'au national ; l'intensité régionale est dérivée viaacv-ademe(cycle de vie appliqué au mix régional, ADR-0008).acv-ademe@1est basée production ;acv-ademe@2consumption-based (imports valorisés à l'intensité du voisin via ENTSO-E + pertes T&D, ADR-0010) est servie au national via?methodology=acv-ademe&version=2.
carbon-fr suit une architecture hexagonale (ports & adapters) stricte : le domaine ne dépend de rien, les dépendances pointent vers l'intérieur. Changer de source de données, de base, ou de modèle de prévision = un nouvel adapter, sans toucher au cœur métier.
Adapters entrants Adapters sortants
(API axum, CLI…) (ODRÉ · PostgreSQL · ForecastModel)
│ ▲
▼ appelle les cas d'usage │ implémentent les ports
┌────────────────────────────────────────────────────────────┐
│ core (lib pure, zéro IO) │
│ application/ cas d'usage ports/ traits sortants │
│ domain/ intensité, régions, mesures, méthodologie │
└────────────────────────────────────────────────────────────┘
▲ assemble tout
bin/server (composition root)
Le détail — vision, contraintes, modèle de données, quota — vit dans docs/ARCHITECTURE.md. Le « pourquoi » des choix structurants est tracé dans les ADR.
carbon-fr/
├── Cargo.toml # workspace Cargo
├── crates/
│ ├── core/ # ✅ domaine + cas d'usage + ports (lib PURE, zéro IO)
│ ├── eligibility/ # ✅ éligibilité électrolyseur rfnbo/low-carbon (lib PURE, ADR-0026)
│ ├── adapter-odre/ # ✅ impl Eco2mixSource/Eco2mixArchive (ODRÉ)
│ ├── adapter-postgres/ # ✅ impl repositories (sqlx/Postgres)
│ ├── adapter-http/ # ✅ API axum + OpenAPI + auth + SSE (adapter entrant)
│ ├── adapter-forecast/ # ✅ impl ForecastModel (climatology@1, acv-ademe@2)
│ ├── adapter-meteo/ # ✅ impl WeatherForecastSource (Open-Meteo)
│ ├── adapter-entsoe/ # ✅ impl CrossBorderSource + SpotPriceSource (ENTSO-E)
│ ├── adapter-webhook/ # ✅ impl Notifier (livraison signée, anti-SSRF)
│ ├── adapter-gbdt/ # ✅ impl ForecastModel ML (GBDT, exploré — non servi)
│ └── sdk/ # carbonfr-sdk : client HTTP Rust (hors hexagone, ne dépend pas de core), publié sur crates.io
├── bin/
│ └── server/ # ✅ composition root : adapters + poller
├── bruno/ # collection Bruno (requêtes .bru versionnées)
├── sdk/typescript/ # SDK client TypeScript (@carbon-fr/sdk)
├── deploy/ # exemples self-host (Caddyfile, systemd) + README (prod Traefik)
├── Dockerfile # image de prod multi-stage
├── .env.example # variables d'environnement documentées
└── docs/
├── ARCHITECTURE.md
└── adr/ # Architecture Decision Records
Pour travailler sur carbon-fr lui-même (et non simplement consommer l'API). Prérequis : Rust ≥ 1.94 pour construire le workspace (sqlx 0.9 l'exige ; edition 2024) — les crates publiées carbonfr-core, carbonfr-eligibility et carbonfr-sdk gardent, elles, une MSRV de 1.88 vérifiée en CI.
git clone git@github.com:Kovelt/carbon-fr.git
cd carbon-fr
cargo check --workspace # compile tout le workspace
cargo test --workspace # lance les tests (le core se teste sans IO)
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --allLe crate core se teste entièrement en mémoire, avec des fakes implémentant les ports — c'est le bénéfice direct de l'hexagonal (voir crates/core/tests/use_cases.rs).
Le serveur a besoin d'un PostgreSQL ; un conteneur jetable suffit (podman ou docker, même syntaxe). Les migrations sont appliquées au démarrage.
# 1. PostgreSQL jetable (publié sur localhost seulement ; données perdues avec le conteneur)
# Port 5432 déjà pris ? Changer le port hôte (ex. 5433:5432) et DATABASE_URL en conséquence.
podman run -d --name carbonfr-pg \
-e POSTGRES_USER=carbonfr -e POSTGRES_PASSWORD=carbonfr -e POSTGRES_DB=carbonfr \
-p 127.0.0.1:5432:5432 docker.io/library/postgres:17-alpine
# 2. L'API et son poller (premier terminal)
export DATABASE_URL=postgres://carbonfr:carbonfr@localhost:5432/carbonfr
export CARBONFR_VISIT_SALT=dev # sel du hachage des IP visiteurs : valeur libre en local
cargo run -p server
# 3. Deuxième terminal
curl -s localhost:8080/health/ready # → ready
curl -s localhost:8080/v1/intensity/now # → {"region":"national","timestamp":"…","intensity":{"value":19.0,…},"index":"very-low","methodology":"rte-direct",…}- Variables : seule
DATABASE_URLest requise ;CARBONFR_VISIT_SALT(sel du hachage des IP visiteurs) évite l'avertissement « sel par défaut » au démarrage — valeur libre en local, secret à haute entropie en production, obligatoire avecCARBONFR_TRUST_PROXY=1. Le serveur ne charge aucun fichier.env:.env.exampleest une référence à exporter dans le shell (set -a; . ./.env; set +a). Il écoute sur0.0.0.0:8080par défaut (CARBONFR_BIND=127.0.0.1:8080pour rester local). Inutile d'attendre PostgreSQL : le serveur retente la connexion (10 × 2 s). - Première donnée : le poller tourne dans le même processus et ingère dès le démarrage (≈ 2 s : national, 12 régions, charge, météo), puis toutes les 15 min — avant cela,
/v1/intensity/nowrépond404 no_data. Il interroge ODRÉ (RTE) et Open-Meteo : l'accès réseau sortant est requis (~1 350 appels ODRÉ par jour si le serveur reste allumé, sur un quota de 50 000 appels/mois par jeu de données et par client —docs/ARCHITECTURE.md§3). - Historique : le poller ne relit que les dernières heures (fenêtre glissante de 3 h) et l'auto-réparation quotidienne les 7 derniers jours nationaux (régional avec
CARBONFR_SELF_HEAL_REGIONAL=1)./v1/intensity/date,/v1/intensity/statset la prévision (qui s'appuie sur ~10 semaines en amont) supposent l'historique, rapatrié par la sous-commandebackfill(export de masse ODRÉ, jamais l'API paginée) — par exemple un mois, en quelques secondes :CARBONFR_BACKFILL_FROM=2025-01-01T00:00:00Z CARBONFR_BACKFILL_TO=2025-02-01T00:00:00Z cargo run -p server -- backfill(sans bornes : tout l'historique national depuis 2012 ;CARBONFR_BACKFILL_SCOPE=ally ajoute le mixacv-ademedes 12 régions (archive régionale depuis 2013 ;regionalne rapatrie que ce mix régional),CARBONFR_BACKFILL_SOURCE=realtimeprend le jeu temps réel pour les mois que RTE n'a pas encore consolidés). Les autres sous-commandes (mint-key,backtest*…) et toutes les variables sont décrites dans la docstring debin/server/src/main.rs(référence exhaustive) ;.env.exampleen donne l'essentiel (service, calibration, backfill) etdocs/ARCHITECTURE.mdun résumé (§3 ingestion et backfill, §9 service et sous-commandes). - Explorer : Swagger UI sur http://localhost:8080/docs (spec :
/v1/openapi.json), carte sur http://localhost:8080/hydrogene, et la collection Bruno (bru run --env Local) pour balayer les endpoints. - Arrêter :
Ctrl-C(arrêt gracieux,SIGTERMaussi) ;podman rm -f -v carbonfr-pgsupprime la base jetable (-vretire aussi son volume).
Image de production via le Dockerfile multi-stage (binaire --release, runtime Debian slim, utilisateur non-root). Chaque tag git vX.Y.Z publie l'image sur GHCR (ghcr.io/kovelt/carbon-fr:X.Y.Z, publique, ADR-0019) — en prod, épingler une version exacte. En bare-metal, une unité systemd (deploy/carbonfr.service) avec Restart=on-failure. Dans les deux cas, placer l'API derrière un reverse proxy TLS (deploy/Caddyfile, exemple self-host) et activer CARBONFR_TRUST_PROXY=1. L'instance hébergée (carbon-fr-api.kovelt.fr) tourne comme un service de la stack Kovelt derrière Traefik (PostgreSQL dédié) ; détails dans deploy/README.md.
docker build -t carbon-fr .
docker run -e DATABASE_URL=postgres://… -e CARBONFR_VISIT_SALT=… -p 8080:8080 --ulimit nofile=65536:524288 carbon-frConfiguration via variables d'environnement — voir .env.example. Sondes : GET /health (liveness) et GET /health/ready (vérifie la base). Métriques Prometheus sous GET /metrics (fraîcheur du poller, volume ingéré, appels amont — à restreindre au scrapeur côté proxy en prod). Les migrations sont appliquées au démarrage.
Outre le serveur, le binaire expose des sous-commandes one-shot : backfill (rapatrie l'historique par export de masse — prérequis de /intensity/date, /intensity/stats et de la prévision), mint-key (délivre une clé API), list-keys / revoke-key (liste les clés par empreinte, révoque une clé et ses abonnements webhook), les backtest* (backtest, -acv, -sweep, -bands, -renewable, -share, -share-meteo) / train / analyze-renewable-signal (évaluation, entraînement et gates des modèles de prévision) et --version.
- Unité canonique : gCO₂eq/kWh.
- Périmètre :
National+ 12 régions métropolitaines (couverture éCO2mix régional). - Méthodologie MVP :
rte-direct— reprise de l'estimation RTE (émissions de la production française), directement comparable à éCO2mix. Versionnée et portée par chaque mesure (ADR-0005). - Révisions : la donnée RTE est révisée (
tr→consolidated→definitive). L'ingestion fait un upsert conditionnel au millésime : on sert toujours la meilleure version (ADR-0006). - Source citée, jamais appropriée :
carbon-frre-traite et cite RTE/ODRÉ, il ne s'y substitue pas.
Données amont : RTE éCO2mix, publiées en open data via ODRÉ sous licence ouverte.
- Cadrage — ADR, architecture, modèle de domaine.
- Phase 1 — Socle :
core· adapters ODRÉ / Postgres / HTTP · poller ·/intensity/now+/mix(national). - Phase 2 — Historique & régional : backfill par export de masse ·
/intensity/date· rollups +/intensity/stats· régional viaacv-ademe(12 régions) · OpenAPI 3.1 + Bruno. - Phase 3 — Prévision :
climatology@1(backtest, calibration des intervalles) →/forecast+/greenest-window. - Phase 4 — Enrichissement & usage :
acv-ademe@2consumption-based (ENTSO-E) · prévisionacv-ademe· scheduling carbon-aware + SSE · clés API + quota · webhooks signés. (ML GBDT exploré, gardé par backtest ; raffinements ouverts.) - Phase 5 — Enrichissement, déploiement & SDK : échanges transfrontaliers (
/v1/exchanges), météo (/v1/weather), dérivation renouvelable (/v1/renewable) ; prix de l'électricité (/v1/price, décomposition TRV, ADR-0023) + couche comparative LCOE (/v1/cost-reference, ADR-0024) ; déployé sur VPS FR/EU (Traefik + PostgreSQL) ; SDK TypeScript (@carbon-fr/sdk). - Extension hydrogène carbon-aware (v0.4.0) : couche A « électrolyseur » — éligibilité RFNBO / bas-carbone par créneau au-dessus de
/greenest-window(?eligibility=) + catalogue/v1/eligibility/rulesets(ADR-0025, ADR-0026). - Suite hydrogène (v0.5.0–v0.6.0) : part renouvelable prévue
share-clim@1dans l'overlayrfnbo(ADR-0028 ; variante météoshare-meteo@2mesurée, non servie) · carte « électrolyseurs × carbone live »GET /hydrogene(ADR-0029). - Phase 7 — Fiabilité & écosystème Rust (phase 6 = couche hydrogène des deux puces ci-dessus, numérotation de
docs/ARCHITECTURE.md§8 ; v0.7.0 → v0.11.0, août–octobre 2026 : audit 2026-08 puis itérations I0→I9 du plan, dont, hors plan, la collecte fiabilisée après la panne ODRÉ d'août (v0.9.4–v0.9.5) ; plus, en v0.11.1 (2026-11-02), les premiers items d'I10 : parité SDK TS ↔ OpenAPI, exemples et en-têtes OpenAPI, prévision du cache ré-ancrée surfrom(#161), horodatages/v1en UTC) :- Exploitation vérifiable : audit 2026-08 (poller et arrêt robustes, fraîcheur bornée des jointures, cache TTL des prévisions, sécurité de bord) ; ingestion par fenêtre glissante (
IngestRecent) + auto-réparation quotidienne (national, puis régional) ; quota ODRÉ réel lu dans les en-têtes et exposé dans/metricsavec alertes ; plafond SSE (300), délais HTTP entrants et plafond de connexions ; compression gzip/brotli ; restauration de sauvegarde testée ; CI en PostgreSQL 17 ; révocation de clés (revoke-key), désactivation puis purge automatiques des webhooks en échec. - Écosystème Rust :
carbonfr-coreetcarbonfr-eligibilitypubliées sur crates.io à chaque tagv*(ADR-0030 : MSRV 1.88,cargo-semver-checkset rustdoc en CI, Trusted Publishing) ; SDK Rustcarbonfr-sdk(29 opérations dont le flux SSE avec reconnexion, ADR-0031) ; montées majeures isolées (utoipa6,reqwest0.13 avec un seul providerring,sqlx0.9). - Donnée : millésime TRV
2026-H2pour/v1/price; historique régionalacv-ademecomblé par export de masse (CARBONFR_BACKFILL_SCOPE) ; partitionnement demeasurementmesuré et non retenu (addendum ADR-0004) ; chemins ENTSO-E rejoués en live. - API & DX :
GET /v1/intensity/now/all,GET /v1/regions, partssharesdans/v1/mix,serversdans l'OpenAPI, puis (v0.11.1) exemples de réponse et en-têtes des middlewares ; index qualitatifindex+GET /v1/intensity/index(ADR-0033) ; export CSV de l'historique ; SDK TypeScript 0.5.0 (reconnexion SSE, index) et tests de parité SDK ↔ OpenAPI en CI — Rust dèscarbonfr-sdk0.1 (ADR-0031), TypeScript depuis la v0.11.1 (ADR-0032) ; parcours local documenté ; environnement Bruno « Production » ; site vitrine statique (https://carbon-fr.kovelt.fr, dépôt séparé, sans SSG — item « site / doc / playground » de l'ADR-0007 clos par son addendum du 2026-11-02) : référence OpenAPI, registre ADR et journal des versions rendus en direct depuis les sources, playground sur l'API de production, rafraîchi pour la v0.11.1 le 2026-11-02. - Gouvernance : ruleset de
main(ADR-0027, en place depuis juin 2026) porté de 5 à 8 contrôles requis, CI à moindre privilège avec actions épinglées,GOUVERNANCE.md/SECURITY.mdremis à jour en I8.
- Exploitation vérifiable : audit 2026-08 (poller et arrêt robustes, fraîcheur bornée des jointures, cache TTL des prévisions, sécurité de bord) ; ingestion par fenêtre glissante (
- À venir — itération I10 en cours (→ v0.12.0 : revue LCOE du 2026-12-15, backfill consolidé de juillet–septembre 2026, millésime TRV 2027-H1 ; détail dans le plan par itérations) ; chantiers en attente d'un déclencheur (conditions dans le plan) :
UsageMeterpersistant (premier consommateur commercial qui sature le quota) ; suite hydrogène (roadmap dédiée : rulesetrfnbo:2026-revisionquand le droit sera adopté ; branche EUA en réserve ; bascule horaire du 2030-01-01 déjà paramétrée, recalée si le texte révisé change la date) .
Les contributions sont les bienvenues — lire d'abord CONTRIBUTING.md et les conventions de code dans CLAUDE.md. En résumé : cargo fmt + cargo clippy -D warnings doivent passer, le core reste sans IO, et toute décision structurante passe par un ADR. La branche main est protégée (PR obligatoire, CI verte, historique linéaire — pas de push direct ; voir ADR-0027).
Distribué sous licence MIT OU Apache 2.0, au choix.
Sauf mention contraire explicite, toute contribution soumise pour inclusion dans ce dépôt — telle que définie par la licence Apache 2.0 — sera distribuée sous cette double licence, sans condition supplémentaire.