Référence · v1

Référence de l’API

L’API carbon-fr expose l’intensité carbone de l’électricité française en gCO₂eq/kWh, au pas quart d’heure, pour le national et les 12 régions métropolitaines. Une surface REST, lisible, dont chaque réponse porte sa méthodologie et son millésime.

Base URL https://carbon-fr-api.kovelt.fr/v1

Introduction

carbon-fr re-traite la donnée ouverte RTE/éCO2mix (via ODRÉ) et la sert depuis sa propre base : vous interrogez une API stable, sans subir le quota ni la forme brute de la source. Les réponses de succès sont en application/json (UTF-8) ; les erreurs suivent le format Problem Details (RFC 9457) en application/problem+json.

Format JSON Unité gCO₂eq/kWh Pas 15 min Horodatages UTC

↳ Deux natures d’endpoints cohabitent : le repackaging de données existantes (/intensity/now, /mix, /intensity/date) et la valeur créée par modélisation (/intensity/forecast, /greenest-window), qui n’existe pas dans la source.

Authentification & quota

Les endpoints de lecture sont publics : aucune clé n’est requise au lancement. Le quota de 50 000 appels/mois imposé par la source est absorbé par construction — un poller unique alimente la base, l’API sert tous les clients depuis la base. Vous n’héritez jamais de ce plafond.

i Une limite d’équité (fair-use) côté API pourra s’appliquer par IP pour préserver le service. Seuls les webhooks (/v1/webhooks) exigent une clé d’API (Authorization: Bearer) ; le contrat de lecture reste public.

Conventions

Trois notions traversent toute l’API. Les comprendre, c’est lire correctement n’importe quelle réponse.

Unité & horodatage

L’intensité est toujours exprimée en gCO₂eq/kWh (entier). Chaque point porte un timestamp RFC 3339 en UTC (suffixe Z) ; un from/to reçu avec un décalage (+02:00) est accepté et renvoyé en UTC. Les durées (horizon, fenêtre, intervalle) suivent ISO 8601 : PT15M, PT48H, PT2H.

Méthodologie

Un chiffre n’est comparable que si sa méthode est explicite. Chaque réponse porte un objet methodology (identifiant + version sémantique). Une nouvelle méthode est une nouvelle version — jamais une modification silencieuse.

methodology.id	Statut	Description
rte-direct	disponible	Estimation RTE reprise telle quelle : émissions directes de la production d’électricité en France. Comparable à éCO2mix.
acv-ademe	disponible	Cycle de vie (Base Carbone ADEME), national et 12 régions : `version=1` basée production (défaut), `version=2` basée consommation (imports ENTSO-E + pertes, national). Coexiste avec `rte-direct` (ADR-0010).

Millésime (vintage)

La donnée RTE est révisée dans le temps. Chaque mesure porte un vintage ; l’API sert toujours la meilleure version connue et l’expose, pour que vous sachiez si vous lisez du provisoire ou du définitif.

vintage	Qualité	Disponibilité
tr	temps réel — télémesures + estimations	au fil de l’eau
consolidated	vérifiée et complétée	~ milieu du mois M+1
definitive	comptages vérifiés	année A+1

Ordre de qualité : definitive > consolidated > tr.

Régions

Le paramètre region accepte national (défaut) ou l’un des 12 slugs régionaux métropolitains ci-dessous (les codes INSEE sont également acceptés) — catalogue servi par GET /v1/regions.

Auvergne-Rhône-Alpesauvergne-rhone-alpes

Bourgogne-Franche-Comtébourgogne-franche-comte

Bretagnebretagne

Centre-Val de Loirecentre-val-de-loire

Grand Estgrand-est

Hauts-de-Francehauts-de-france

Île-de-Franceile-de-france

Normandienormandie

Nouvelle-Aquitainenouvelle-aquitaine

Occitanieoccitanie

Pays de la Loirepays-de-la-loire

Provence-Alpes-Côte d’Azurprovence-alpes-cote-d-azur

intensité

GET `/v1/intensity/date`

série historique sur un intervalle [from, to) (RFC 3339), national par défaut.

GET `/v1/intensity/index`

catalogue du barème de l'index qualitatif (ADR-0033, index@1) : les cinq bandes very-low → very-high, leurs bornes ([min, max[, gCO₂eq/kWh) et la source de chaque borne. Même rôle que /v1/factors pour l'ACV : la légende est auditable ; la carte /hydrogene la lit au chargement au lieu de coder ses classes en dur.

GET `/v1/intensity/now`

dernière intensité carbone connue.

GET `/v1/intensity/now/all`

dernière intensité de chaque région en un appel (plan I8, PROD-API-2) : une requête au read-model pour national + 12 régions, au lieu de 13 appels à /v1/intensity/now.

GET `/v1/intensity/stats`

résumé (moyenne/min/ max) sur [from, to), et série agrégée par pas si interval=hour|day.

mix

GET `/v1/mix`

mix de production de la dernière mesure.

échanges

GET `/v1/exchanges`

échanges transfrontaliers : flux net signé par frontière (> 0 = import vers la France) + intensité carbone du voisin (ADR-0017). Donnée ENTSO-E déjà ingérée pour acv-ademe@2, servie au pas quart d'heure, alignée sur la dernière mesure nationale. 404 si aucun snapshot frais (≤ 1 h de la dernière mesure) n'est disponible — un contexte périmé (panne d'ingestion) n'est pas servi comme courant.

GET `/v1/exchanges/date`

série historique des échanges transfrontaliers sur un intervalle RFC 3339 (fenêtre ≤ 92 jours, série dense), au pas quart d'heure (ADR-0017).

météo

GET `/v1/weather`

météo nationale courante (vent à 100 m, irradiance ; moyenne 7 points), ADR-0012/0018. Données Open-Meteo (CC-BY 4.0, attribuées).

GET `/v1/weather/date`

série météo historique (vent + irradiance) sur un intervalle RFC 3339 (fenêtre ≤ 92 jours, série dense), ADR-0012/0018.

renouvelable

GET `/v1/renewable`

production renouvelable estimée depuis la météo courante (modèle calibré au démarrage, ADR-0018) + facteur de charge. Le moat rendu visible : « given le vent/soleil actuels, voici la production attendue ». 503 si le modèle n'a pas pu être calibré (historique insuffisant).

prix

GET `/v1/cost-reference`

couche comparative LCOE (ADR-0024).

GET `/v1/price`

décomposition complète du prix payé (ADR-0023).

GET `/v1/price/date`

série de décompositions de prix sur un intervalle RFC 3339 (fenêtre ≤ 92 jours), pour la primitive « cheapest + greenest window » (ADR-0023). National uniquement. Les créneaux sans prix spot frais (≤ 6 h) sont omis — jamais de report d'un prix périmé (trou d'ingestion ENTSO-E).

éligibilité

GET `/v1/eligibility/rulesets`

catalogue des cadres et rulesets versionnés d'éligibilité électrolyseur (ADR-0025/0026). Vérifiabilité + neutralité.

prévision

GET `/v1/intensity/forecast`

série d'intensité prévue sur l'horizon, par le modèle climatology@1 (ADR-0009).

GET `/v1/intensity/greenest-window`

créneau le plus bas-carbone à venir, sur la prévision climatology@1 (ADR-0009). Avec ?eligibility=, annote chaque créneau d'un verdict d'éligibilité électrolyseur (ADR-0025/0026).

usage

GET `/v1/intensity/below`

tous les créneaux prévus d'intensité sous threshold (gCO₂eq/kWh) sur l'horizon (ADR-0014).

GET `/v1/intensity/stream`

flux live (Server-Sent Events) des mises à jour du read-model, poussées à la cadence du poller (ADR-0014 §2).

GET `/v1/schedule`

planifie un job : créneau contigu le plus bas-carbone (avant une échéance optionnelle) + économie carbone vs « maintenant » (ADR-0014).

GET `/v1/schedule/slots`

les count créneaux les moins intenses sur l'horizon (job divisible, interruptibilité supposée parfaite, ADR-0014).

méthodologie

GET `/v1/factors`

table des facteurs d'émission d'une méthode (ADR-0010 §7).

GET `/v1/methodologies`

catalogue des méthodes carbone + versions (ADR-0010 §7).

régions

GET `/v1/regions`

catalogue statique des régions servies (slug, libellé, code INSEE) : les valeurs acceptées par le paramètre region (plan I8, PROD-API-5). National d'abord, puis les 12 régions métropolitaines, dans l'ordre de /v1/intensity/now/all.

opérations

GET `/health`

sonde de disponibilité (hors contrat d'API versionné).

GET `/health/ready`

sonde de readiness : vérifie l'accès à la base (lecture légère). 503 si la base est injoignable → le proxy/monitoring cesse d'y router le trafic (distinct de /health, liveness statique).

GET `/v1/stats`

statistiques de consultation.

POST `/v1/stats/visit`

enregistre une visite (unique par IP/jour, IP hachée jamais stockée) et renvoie les statistiques à jour.

webhooks

GET `/v1/webhooks`

liste les abonnements de la clé. Auth requise.

POST `/v1/webhooks`

crée un abonnement webhook (ADR-0016). Auth requise. Le secret de signature est renvoyé une seule fois.

DELETE `/v1/webhooks/{id}`

supprime un abonnement possédé par la clé.

Référence de l’API

Introduction

Authentification & quota

Conventions

intensité

GET /v1/intensity/date

GET /v1/intensity/index

GET /v1/intensity/now

GET /v1/intensity/now/all

GET /v1/intensity/stats

mix

GET /v1/mix

échanges

GET /v1/exchanges

GET /v1/exchanges/date

météo

GET /v1/weather

GET /v1/weather/date

renouvelable

GET /v1/renewable

prix

GET /v1/cost-reference

GET /v1/price

GET /v1/price/date

éligibilité

GET /v1/eligibility/rulesets

prévision

GET /v1/intensity/forecast

GET /v1/intensity/greenest-window

usage

GET /v1/intensity/below

GET /v1/intensity/stream

GET /v1/schedule

GET /v1/schedule/slots

méthodologie

GET /v1/factors

GET /v1/methodologies

régions

GET /v1/regions

opérations

GET /health

GET /health/ready

GET /v1/stats

POST /v1/stats/visit

webhooks

GET /v1/webhooks

POST /v1/webhooks

DELETE /v1/webhooks/{id}

Modèles de données

Codes d’erreur

GET `/v1/intensity/date`

GET `/v1/intensity/index`

GET `/v1/intensity/now`

GET `/v1/intensity/now/all`

GET `/v1/intensity/stats`

GET `/v1/mix`

GET `/v1/exchanges`

GET `/v1/exchanges/date`

GET `/v1/weather`

GET `/v1/weather/date`

GET `/v1/renewable`

GET `/v1/cost-reference`

GET `/v1/price`

GET `/v1/price/date`

GET `/v1/eligibility/rulesets`

GET `/v1/intensity/forecast`

GET `/v1/intensity/greenest-window`

GET `/v1/intensity/below`

GET `/v1/intensity/stream`

GET `/v1/schedule`

GET `/v1/schedule/slots`

GET `/v1/factors`

GET `/v1/methodologies`

GET `/v1/regions`

GET `/health`

GET `/health/ready`

GET `/v1/stats`

POST `/v1/stats/visit`

GET `/v1/webhooks`

POST `/v1/webhooks`

DELETE `/v1/webhooks/{id}`