Quickstart & SDK
Trois portes d’entrée vers la donnée carbone française : l’API HTTP brute, une crate Rust typée, un client TypeScript. Et un binaire unique pour tout auto-héberger.
Trois façons de consommer carbon-fr
Aucune clé d’API requise au lancement. Le quota de la source est absorbé par le service.
API HTTP
REST + JSON, lisible. Chaque réponse porte sa méthodologie et son millésime.
Crates Rust
Client async typé, erreurs RFC 9457 décodées. Ou carbonfr-core pour embarquer le domaine sans IO.
SDK TypeScript
Tous les endpoints typés, ESM + CJS. Fonctionne navigateur et Node.
Lire l’intensité carbone, maintenant
Le même appel, dans quatre langages. La réponse expose toujours intensity, methodology et vintage.
# Intensité carbone nationale, à l'instant t curl https://carbon-fr-api.kovelt.fr/v1/intensity/now # Une région, méthode cycle de vie curl "https://carbon-fr-api.kovelt.fr/v1/intensity/now?region=ile-de-france&methodology=acv-ademe"
const res = await fetch("https://carbon-fr-api.kovelt.fr/v1/intensity/now?region=ile-de-france");
const now = await res.json();
// Chaque réponse porte sa méthode et son millésime
console.log(now.intensity.value, now.methodology, now.vintage);
// → 12 "rte-direct" "tr"
use carbonfr_sdk::{CarbonFr, IntensityNowOptions, Region};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let api = CarbonFr::builder().build()?; // carbon-fr-api.kovelt.fr par défaut
let now = api
.intensity_now(IntensityNowOptions { region: Some(Region::IleDeFrance), ..Default::default() })
.await?;
println!("{} {} — {} ({:?})", now.intensity.value, now.intensity.unit, now.methodology, now.index);
Ok(())
}
import httpx
r = httpx.get("https://carbon-fr-api.kovelt.fr/v1/intensity/now",
params={"region": "grand-est"})
print(r.json()["intensity"])
Typé, async, et embarquable
Trois crates sur crates.io (MSRV 1.88, politique de publication ADR-0030) : carbonfr-sdk, le client HTTP typé et asynchrone de l’API (ADR-0031) ; carbonfr-core, le domaine pur — régions, méthodologies, millésimes, facteurs, barème de l’index, prévision — sans aucune IO ; carbonfr-eligibility, les cadres d’éligibilité électrolyseur. Régions, méthodologies et millésimes sont des types du domaine, pas des chaînes magiques.
[dependencies]
carbonfr-sdk = { version = "0.3", features = ["stream"] } # client HTTP typé (+ flux SSE)
carbonfr-core = "0.11" # domaine pur, embarquable (zéro IO)
tokio = { version = "1", features = ["full"] }
// Mix courant d'une région + créneau de 2 h le plus bas-carbone des 24 prochaines heures
use carbonfr_sdk::{GreenestWindowOptions, MixOptions};
let mix = api.mix(MixOptions { region: Some(Region::Bretagne), ..Default::default() }).await?;
println!("nucléaire {:.0} MW, éolien {:.0} MW", mix.mix.nucleaire, mix.mix.eolien);
let window = api
.greenest_window(GreenestWindowOptions { window_minutes: Some(120), ..Default::default() })
.await?;
println!("Fenêtre la plus verte : {} → {} ({:.0} {})", window.start, window.end, window.average_intensity, window.unit);
Ajoutez la dépendance — cargo add carbonfr-sdk (--features stream pour le flux SSE), ou collez le bloc Cargo.toml.
Tout est typé — Region, Methodology et Vintage sont des enums : pas de chaîne mal orthographiée qui passe en silence.
Besoin du domaine sans réseau ? carbonfr-core expose les types et les calculs purs (intensité ACV depuis un mix, barème de l’index, fenêtre la plus verte d’une série) — testables sans base ni HTTP.
Un SDK que la France n’avait pas
Des wrappers de l’API carbone britannique existent en JS, Python, Rust. @carbon-fr/sdk apporte l’équivalent français — la version 0.5.0 publiée sur npm couvre toute l’API : intensité (dont intensityNowAll, les 13 régions en un appel, et le catalogue regions), mix et parts de production, historique, statistiques, prévision, scheduling bas-carbone, échanges, météo, renouvelable, méthodologies, facteurs, barème de l’index qualitatif, décomposition du prix, coûts de référence (LCOE), éligibilité électrolyseur, webhooks et le flux SSE, avec reconnexion automatique. Sa parité avec l’OpenAPI est vérifiée en CI (ADR-0032).
npm i @carbon-fr/sdk
import { CarbonFr } from "@carbon-fr/sdk";
const cf = new CarbonFr(); // https://carbon-fr-api.kovelt.fr par défaut
const now = await cf.intensityNow({ region: "ile-de-france" });
const win = await cf.greenestWindow({ windowMinutes: 120 });
console.log(now.intensity.value, now.index, win.average_intensity);
// → 12 "very-low" 9.4
for (const r of (await cf.intensityNowAll({ methodology: "acv-ademe" })).data) {
console.log(r.region, r.intensity.value, r.index); // les 13 régions, un seul appel
}
Un binaire, une base Postgres
carbon-fr est souverain et auto-hébergeable : un binaire léger embarque l’API et le poller. Aucune dépendance propriétaire.
# Un seul binaire : l'API + le poller, derrière une base PostgreSQL docker run -p 8080:8080 \ -e DATABASE_URL=postgres://user:pass@host/carbonfr \ -e CARBONFR_VISIT_SALT=change-me \ ghcr.io/kovelt/carbon-fr:0.11.1 # épingler une version exacte (ADR-0019) ; les migrations s'appliquent au démarrage # CARBONFR_ENTSOE_TOKEN (optionnel) : active acv-ademe@2 (imports) et le prix spot
