bio-pype-carbon-intensity

Grid carbon intensity (gCO2eq/kWh); current values and forecasts from free public APIs. Built for compute.bio / bio-pype but usable standalone; the Python import name is carbon_intensity. Not affiliated with carbonintensity.org.uk or any of the upstream data providers. This package just organises their great public data. MIT licensed.

The core package has no dependencies (stdlib only). The multi-zone backend bulk path needs the backend extra:

pip install bio-pype-carbon-intensity            # worker / single-zone use
pip install bio-pype-carbon-intensity[backend]   # bulk window fetch + EU flow tracing

Usage

from carbon_intensity import get_current, get_forecast, run_window

rec = get_current("GB-LONDON")           # one or two HTTP calls
print(rec.intensity_g_per_kwh, rec.kind)

for slot in get_forecast("AU-NSW1"):     # AEMO pre-dispatch, ~40h ahead
    print(slot.start, slot.intensity_g_per_kwh, slot.extra["method"])

# backend bulk (needs [backend] extra for EU zones):
import datetime as dt
now = dt.datetime.now(dt.timezone.utc)
results = run_window(["FR", "BE", "GB", "AU-NSW1"], now - dt.timedelta(hours=4),
                     now + dt.timedelta(hours=24))

API keys via env vars: ENTSOE_API_KEY, OPENELECTRICITY_API_KEY, ELECTRICITY_MAPS_API_KEY, COMPUTE_BIO_API_URL/COMPUTE_BIO_TOKEN — or pass a ProviderConfig explicitly.

Method caveat for EU zones: get_current() / get_forecast() on an ENTSO-E zone return production intensity (single-zone fast path, labeled extra["method"] = "production_only") — they do not account for imports/exports. Consumption intensity for EU zones requires the flow-traced run_window() (or the compute_bio provider, which serves a backend's flow-traced value). Don't compare fast-path numbers against consumption-based sources such as Electricity Maps.

Forecast caveats: WEM (Western Australia) uses a 7-day hour-of-day climatology, not a physical forecast; NEM forecasts assume the current thermal mix holds. The method is labeled in each record's extra["method"].

Run the test suite: python tests/smoke.py (live UK checks need network; ENTSO-E/AU live checks run when keys are set).