Skip to content
KoveltPublic

About

API d'intensité carbone de l'électricité française (gCO₂eq/kWh) — souveraine, open source, dev-first. L'équivalent FR de carbonintensity.org.uk, sur données ouvertes RTE/ODRÉ 🇫🇷.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

carbon-fr

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É.

Release License Rust Statut Architecture


Pourquoi carbon-fr ?

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-direct et acv-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-fr la 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).

Utiliser l'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/sdk
import { 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

Fonctionnalités

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_co2 publié par RTE (rte-direct) n'existe qu'au national ; l'intensité régionale est dérivée via acv-ademe (cycle de vie appliqué au mix régional, ADR-0008). acv-ademe@1 est basée production ; acv-ademe@2 consumption-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.

Architecture

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.

Structure du workspace

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

Développer / contribuer

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 --all

Le 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).

Lancer l'API en local

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_URL est 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 avec CARBONFR_TRUST_PROXY=1. Le serveur ne charge aucun fichier .env : .env.example est une référence à exporter dans le shell (set -a; . ./.env; set +a). Il écoute sur 0.0.0.0:8080 par défaut (CARBONFR_BIND=127.0.0.1:8080 pour 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/now répond 404 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/stats et la prévision (qui s'appuie sur ~10 semaines en amont) supposent l'historique, rapatrié par la sous-commande backfill (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=all y ajoute le mix acv-ademe des 12 régions (archive régionale depuis 2013 ; regional ne rapatrie que ce mix régional), CARBONFR_BACKFILL_SOURCE=realtime prend 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 de bin/server/src/main.rs (référence exhaustive) ; .env.example en donne l'essentiel (service, calibration, backfill) et docs/ARCHITECTURE.md un 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, SIGTERM aussi) ; podman rm -f -v carbonfr-pg supprime la base jetable (-v retire aussi son volume).

Déploiement

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-fr

Configuration 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.

Méthodologie & données

  • 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-fr re-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.

Feuille de route

  • 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 via acv-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@2 consumption-based (ENTSO-E) · prévision acv-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@1 dans l'overlay rfnbo (ADR-0028 ; variante météo share-meteo@2 mesuré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 sur from (#161), horodatages /v1 en 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 /metrics avec 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-core et carbonfr-eligibility publiées sur crates.io à chaque tag v* (ADR-0030 : MSRV 1.88, cargo-semver-checks et rustdoc en CI, Trusted Publishing) ; SDK Rust carbonfr-sdk (29 opérations dont le flux SSE avec reconnexion, ADR-0031) ; montées majeures isolées (utoipa 6, reqwest 0.13 avec un seul provider ring, sqlx 0.9).
    • Donnée : millésime TRV 2026-H2 pour /v1/price ; historique régional acv-ademe comblé par export de masse (CARBONFR_BACKFILL_SCOPE) ; partitionnement de measurement mesuré et non retenu (addendum ADR-0004) ; chemins ENTSO-E rejoués en live.
    • API & DX : GET /v1/intensity/now/all, GET /v1/regions, parts shares dans /v1/mix, servers dans l'OpenAPI, puis (v0.11.1) exemples de réponse et en-têtes des middlewares ; index qualitatif index + 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ès carbonfr-sdk 0.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.md remis à jour en I8.
  • À 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) : UsageMeter persistant (premier consommateur commercial qui sature le quota) ; suite hydrogène (roadmap dédiée : ruleset rfnbo:2026-revision quand 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) .

Contribuer

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).

Licence

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.


Un projet Kovelt.

About

API d'intensité carbone de l'électricité française (gCO₂eq/kWh) — souveraine, open source, dev-first. L'équivalent FR de carbonintensity.org.uk, sur données ouvertes RTE/ODRÉ 🇫🇷.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages