{
 "ok": true,
 "service": "carbon-intensity",
 "version": 1,
 "title": "Grid carbon-intensity API — current + forecast AVERAGE intensity by zone, one schema",
 "what_it_is": "Per-call average carbon intensity (gCO2/kWh) for six zones in one schema, each answer carrying its upstream timestamp, cache state, and full provenance with the zone's licence attribution. Values are computed or relayed only from the official source named per zone; real-time values are estimates subject to consolidation by the sources. The catalog is free view-mode: zone metadata and the computed-zone factor set only — NO live data values.",
 "endpoints": [
  {
   "path": "/zones",
   "method": "GET",
   "price_usd": 0,
   "description": "This catalog: every zone's source, licence, attribution string, coverage and state, plus the full emission-factor set used by computed zones."
  },
  {
   "path": "/intensity",
   "method": "POST",
   "price_usd": 0.005,
   "description": "Current average intensity: {zone} -> average_intensity_gco2_per_kwh + generation mix where the source carries it + as_of + cache state + provenance."
  },
  {
   "path": "/intensity/forecast",
   "method": "POST",
   "price_usd": 0.01,
   "description": "Forecast average intensity: {zone} -> timestamped forecast points (24-48h where the source publishes that horizon), every point labelled forecast."
  },
  {
   "path": "/health",
   "method": "GET",
   "price_usd": 0,
   "description": "Liveness + per-zone last-fetch/cache state."
  },
  {
   "path": "/criteria",
   "method": "GET",
   "price_usd": 0,
   "description": "The published carbon-intensity criteria (criteria id carbon/v1): what is checked, the zone and factor rules, caps, and prices."
  }
 ],
 "pricing": {
  "intensity_usd": 0.005,
  "forecast_usd": 0.01,
  "model": "Per call, no subscription, no account, no minimum."
 },
 "zones": [
  {
   "code": "FR",
   "name": "France",
   "source": "RTE via ODRE — dataset eco2mix-national-tr",
   "licence": "Licence Ouverte v2.0 (Etalab)",
   "attribution": "Source: RTE / ODRE, dataset eco2mix-national-tr (Licence Ouverte v2.0).",
   "coverage": {
    "current": true,
    "forecast": false
   },
   "state": "live"
  },
  {
   "code": "DE",
   "name": "Germany",
   "source": "Bundesnetzagentur SMARD — generation by energy source",
   "licence": "CC BY 4.0",
   "attribution": "Bundesnetzagentur | SMARD.de",
   "coverage": {
    "current": true,
    "forecast": false
   },
   "state": "live"
  },
  {
   "code": "GB",
   "name": "Great Britain",
   "source": "NESO Carbon Intensity API",
   "licence": "CC BY 4.0",
   "attribution": "NESO — Carbon Intensity API (CC BY 4.0). GB is served only as one zone of this multi-region product.",
   "coverage": {
    "current": true,
    "forecast": true
   },
   "state": "live"
  },
  {
   "code": "IE",
   "name": "Ireland (all-island)",
   "source": "EirGrid Group Smart Grid Dashboard — CO2 intensity (all-island)",
   "licence": "EirGrid Open Data Licence",
   "attribution": "Supported by EirGrid Group Data",
   "coverage": {
    "current": true,
    "forecast": true
   },
   "state": "live"
  },
  {
   "code": "DK",
   "name": "Denmark",
   "source": "Energinet Energi Data Service — CO2Emis / CO2EmisProg",
   "licence": "CC BY 4.0",
   "attribution": "Source: Energinet (www.energidataservice.dk)",
   "coverage": {
    "current": true,
    "forecast": true
   },
   "state": "live"
  },
  {
   "code": "US",
   "name": "United States (US48 aggregate)",
   "source": "U.S. EIA — Form EIA-930 via the EIA Open Data API v2",
   "licence": "Public domain (U.S. EIA)",
   "attribution": "Source: U.S. Energy Information Administration (EIA).",
   "coverage": {
    "current": false,
    "forecast": false
   },
   "state": "live"
  }
 ],
 "factor_set": {
  "version": "fleet-factors-v1",
  "citation": "IPCC Fifth Assessment Report (AR5), Working Group III, Annex III, Table A.III.2 (Schloemer et al., 2014) — median lifecycle emission intensities by generation technology.",
  "unit": "gCO2eq per kWh generated",
  "factors_gco2_per_kwh": {
   "coal": 1095,
   "lignite": 1095,
   "natural_gas": 490,
   "biomass": 245,
   "solar": 48,
   "hydro": 24,
   "nuclear": 12,
   "wind_onshore": 11,
   "wind_offshore": 12,
   "pumped_storage": 24,
   "other_conventional": 490,
   "other_renewable": 245
  },
  "proxies": {
   "lignite": "coal median (AR5 publishes one coal figure)",
   "solar": "utility-scale PV median",
   "pumped_storage": "hydropower median",
   "other_conventional": "natural-gas median — residual conventional remainder is predominantly gas-fired",
   "other_renewable": "biomass median — residual renewable remainder is predominantly biogenic"
  },
  "note": "Emission factors are a modelling choice, not a measurement: computed intensities are estimates from the source's generation mix and this published factor set, identical across computed zones so cross-zone comparisons stay meaningful."
 },
 "honest_limits": [
  "AVERAGE intensity only: total emissions attributable to a zone's electricity in a period, divided by the electricity consumed in that period. Nothing here is a per-increment signal and no answer supports avoided-emissions arithmetic.",
  "Real-time values are estimates subject to consolidation: sources retrospectively replace real-time readings with consolidated values, so a previously served value can be revised. Every answer carries as_of (the upstream data timestamp) and the cache state; a stale answer is labelled stale, never dressed as fresh.",
  "Computed zones (DE; US when configured) are estimates from the source's generation mix and the published fleet-factors-v1 set — a modelling choice, versioned and identical across computed zones, cited in every computed answer.",
  "DK is published per price area (DK1/DK2), not nationally: the zone value is the unweighted mean of the two area values, disclosed in the answer; the per-area values travel with it.",
  "Forecast horizons are the sources' own (GB up to 48h; IE about 32h; DK about 30h at first fetch) and are never padded. FR publishes no CO2 forecast and DE publishes no full-mix forecast, so both answer forecast_not_available rather than a fabricated curve.",
  "US is gated on an EIA API key (free registration, the operator's own step): until it is set, the zone answers a free not_configured error before any payment gate — never a charge for a zone that cannot answer.",
  "GB is served only as one zone inside this multi-region product, with NESO attribution on every GB-bearing answer.",
  "Changes feed: not supported in v1 — values are live-cached upstream readings; freshness is disclosed per answer instead."
 ],
 "positioning": "Per-call average grid carbon intensity by zone — one schema across regions, with per-zone provenance and licence attribution on every answer.",
 "envelope": {
  "v": 1,
  "service": "carbon-intensity",
  "as_of": "2026-11-14T14:49:36.037Z",
  "source": "RTE/ODRE (FR), Bundesnetzagentur SMARD (DE), NESO (GB), EirGrid Group (IE), Energinet (DK), U.S. EIA (US, gated)",
  "grade": "official",
  "changes": {
   "supported": false
  }
 }
}