# Carbon Intensity API — Global Grid CO2 Data (`jenko_systems/carbon-intensity-api`) Actor

Real-time and historical carbon intensity (gCO2eq/kWh) for 45+ countries/regions. Built from raw grid operator data (ENTSO-E, EIA, NESO, ONS) with lifecycle and consumption-based calculations following IPCC AR6 and the ECON-PowerCI methodology (Nature 2025).

- **URL**: https://apify.com/jenko\_systems/carbon-intensity-api.md
- **Developed by:** [Jenko Systems](https://apify.com/jenko_systems) (community)
- **Categories:** Integrations, Automation, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$99.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🌍 Carbon Intensity API v2.0

**Real-time and historical electricity carbon intensity (gCO₂eq/kWh), wholesale prices, load, and cross-border flows for 73 countries and grid regions worldwide.**

🔓 **Zero API keys. Zero registration. Zero tokens.** All data sources are public.

***

### 🆕 v2.0 — Expanded coverage (45 → 73 regions)

| Region | v1.0 | v2.0 | Change |
|---|---|---|---|
| **Europe (Fraunhofer)** | 30 countries | **35 countries** | +5 (Cyprus + Bosnia + Kosovo + Moldova + Georgia) |
| **United States (EIA-930)** | 10 BAs | **34 BAs** | +24 (full Western, Southeast, federal admins) |
| **United Kingdom (NESO)** | GB | GB | — |
| **Brazil (ONS)** | 4 submarkets | 4 submarkets | — |
| **TOTAL** | **45** | **73** | **+62% coverage** |

***

### 🇬🇧 English

#### What this delivers

For each hour and region, all the fields below — calculated, normalized, cross-source:

| Field | Description |
|---|---|
| `carbon_intensity_gco2_kwh` | gCO₂eq per kWh of electricity |
| `renewable_pct` | % wind + solar + hydro + biomass + geothermal |
| `fossil_free_pct` | renewable + nuclear |
| `total_generation_mwh` | total electricity generated |
| `fossil_only_intensity_gco2_kwh` | CI of fossil portion only |
| `generation_mix_mw` | per-source breakdown (wind, solar, gas, coal, nuclear, hydro, biomass, oil) |
| `load_mw` | total system demand |
| `net_load_mw` | load minus variable renewables |
| `day_ahead_price` | wholesale spot market price |
| `day_ahead_price_currency` | EUR / USD / GBP / BRL |
| `day_ahead_price_zone` | bidding zone code |
| `cross_border_flows_mw` | list of imports/exports with neighbours |

Four calculation methods available (`method` field):

- **production\_lifecycle** (default) — IPCC AR6 lifecycle factors, domestic generation only
- **production\_operational** — combustion-only factors
- **consumption\_lifecycle** — flow-traced through cross-border imports, lifecycle factors
- **consumption\_operational** — flow-traced, operational factors

#### Coverage detail

**Europe — 35 countries (Fraunhofer Energy-Charts, validated working):**

- EU-26: AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, NL, PL, PT, RO, SE, SI, SK
- Non-EU: CH, NO
- Western Balkans: BA, MK, RS, XK
- Eastern Europe & Caucasus: MD, GE
- UK: GB (via NESO, more granular)

**United States — 34 balancing authorities (EIA-930 bulk CSV):**

- Major ISOs/RTOs: US-CISO, US-ERCO, US-MISO, US-PJM, US-NYIS, US-ISNE, US-SWPP
- Federal admins: US-BPAT, US-TVA
- Southeast: US-SOCO, US-FPL, US-FPC, US-DUK, US-CPLE, US-SC, US-SCEG, US-AECI
- West: US-PACE, US-PACW, US-PSEI, US-IPCO, US-AZPS, US-NEVP, US-AVA, US-LDWP, US-PSCO, US-PNM, US-WACM, US-WAUW
- Other: US-NW, US-SE, US-TEC, US-JEA, US-TAL

**United Kingdom (NESO):** GB

**Brazil (ONS):** BR-SE (Sudeste/CO), BR-S (Sul), BR-NE (Nordeste), BR-N (Norte)

#### Input

```json
{
  "mode": "latest",
  "hours": 48,
  "method": "production_lifecycle",
  "countries": ["DE", "FR", "GB", "US-CISO", "BR-SE"]
}
```

**Modes:**

- `latest` — last N hours (default 48h)
- `today` — current UTC day so far
- `yesterday` — full previous UTC day
- `full_refresh` — entire history since 2015 (long run)

**Optional skip flags:** `skip_europe`, `skip_us`, `skip_uk`, `skip_brazil`

#### Output (one record per region × hour × method)

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "region": "europe",
  "source": "fraunhofer",
  "timestamp_utc": "2026-05-13T14:00:00+00:00",
  "method": "production_lifecycle",
  "carbon_intensity_gco2_kwh": 312.4,
  "renewable_pct": 47.2,
  "fossil_free_pct": 52.8,
  "total_generation_mwh": 58420.5,
  "generation_mix_mw": {
    "wind": 16850.2, "solar": 7106.4, "nuclear": 3268.5,
    "gas": 13088.4, "coal": 8358.2, "hydro": 3855.7,
    "biomass": 2400.0, "oil": 290.1
  },
  "load_mw": 60140.0,
  "net_load_mw": 29928.5,
  "day_ahead_price": 86.43,
  "day_ahead_price_currency": "EUR",
  "day_ahead_price_zone": "DE-LU",
  "cross_border_flows_mw": [
    { "counterparty": "FR", "flow_mw": 5200.0, "direction": "import" },
    { "counterparty": "PL", "flow_mw": 1100.0, "direction": "import" },
    { "counterparty": "AT", "flow_mw":  800.0, "direction": "export" }
  ]
}
```

#### Methodology

**Production-based:**

```
CI_production = Σ(generation_i × emission_factor_i) / Σ(generation_i)
```

**Consumption-based (flow-traced):**
For interconnected grids, what matters is *what you consume*, not *what you produce*. Solved per hour via linear system:

```
(G_i + IM_i) · x_i = own_emissions_i + Σⱼ(flow_jᵢ × x_j)
```

Solved with `numpy.linalg.solve`. Method follows [ECON-PowerCI (Nature 2025)](https://www.nature.com/articles/s41597-025-05978-7).

**Emission factors (IPCC AR6 WG3, Annex III median values):**

| Source | Lifecycle (gCO₂eq/kWh) | Operational |
|---|---:|---:|
| Wind | 11 | 0 |
| Solar | 48 | 0 |
| Nuclear | 12 | 0 |
| Hydro | 24 | 0 |
| Biomass | 230 | 90 |
| Gas | 490 | 370 |
| Coal | 820 | 760 |
| Oil | 650 | 580 |

#### Use cases

- **ESG / Scope 2 carbon accounting** — accurate hourly CI for corporate reporting
- **Climate tech & green software** — schedule loads when grid is cleanest
- **AI infrastructure planning** — pick datacenter regions by real-time grid quality
- **Energy trading** — backtesting and signal generation
- **Academic research** — replicable, IPCC-aligned dataset

***

### 🇧🇷 Português

#### O que é

API de intensidade de carbono elétrica (gCO₂eq/kWh) em tempo real e histórica + preços wholesale + carga + fluxos transfronteiriços para **73 países e regiões** globais.

🔓 **ZERO chaves de API**. Fontes 100% públicas: Fraunhofer (Europa), EIA-930 (EUA), NESO (UK), ONS (Brasil).

#### v2.0 — Cobertura expandida

```
Europa:       30 → 35 países (+Cyprus, Bosnia, Kosovo, Moldova, Georgia)
EUA:          10 → 34 BAs (+todo o oeste, sudeste, federais)
Reino Unido:  GB (mantido)
Brasil:       4 submercados SIN (mantido)
─────────────────────────────────────────────
TOTAL:        45 → 73 regiões (+62% cobertura)
```

#### Atribuição

Dados:

- **Fraunhofer Energy-Charts** (Europa) — CC BY 4.0
- **EIA Hourly Electric Grid Monitor** (EUA) — domínio público
- **NESO Carbon Intensity API** (UK) — CC BY 4.0
- **ONS Dados Abertos** (Brasil) — CC BY

Metodologia: IPCC AR6 (WG3, Annex III) + ECON-PowerCI (Nature Scientific Data 2025).

***

### 🛠️ Local development

```bash
pip install -r requirements.txt
python carga_inicial.py --mode latest --hours 24
```

***

### 🔄 Schedule

Apify scheduler can run this actor every hour. Output is idempotent by `(country, timestamp, method)`.

***

Built by [Jenko Systems](https://jenkosystems.com).

# Actor input Schema

## `mode` (type: `string`):

How much data to fetch on this run.

## `hours` (type: `integer`):

Number of hours to fetch back from now. Only used when mode=latest.

## `method` (type: `string`):

Which carbon intensity method to return in the dataset. All four are calculated and stored regardless.

## `countries` (type: `array`):

Optional list of region codes. Leave empty for all 73. Europe: AT,BE,BG,CY,CZ,DE,DK,EE,ES,FI,FR,GR,HR,HU,IE,IT,LT,LU,LV,NL,PL,PT,RO,SE,SI,SK,CH,NO,BA,MK,RS,XK,MD,GE,GB. US: US-CISO,US-ERCO,US-MISO,US-PJM,US-NYIS,US-ISNE,US-BPAT,US-SWPP,US-SOCO,US-FPL,US-TVA,US-DUK,US-CPLE,US-FPC,US-SC,US-SCEG,US-AECI,US-PACE,US-PACW,US-PSEI,US-IPCO,US-AZPS,US-NEVP,US-AVA,US-LDWP,US-PSCO,US-PNM,US-WACM,US-WAUW,US-NW,US-SE,US-TEC,US-JEA,US-TAL. Brazil: BR-SE,BR-S,BR-NE,BR-N.

## `skip_europe` (type: `boolean`):

Skip the European data source if you only need US/UK/BR.

## `skip_us` (type: `boolean`):

Skip US data fetch.

## `skip_uk` (type: `boolean`):

Skip UK data fetch.

## `skip_brazil` (type: `boolean`):

Skip Brazil data fetch.

## Actor input object example

```json
{
  "mode": "latest",
  "hours": 48,
  "method": "production_lifecycle",
  "countries": [],
  "skip_europe": false,
  "skip_us": false,
  "skip_uk": false,
  "skip_brazil": false
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with hourly records — one per (country × hour × method) — including carbon\_intensity\_gco2\_kwh, renewable\_pct, fossil\_free\_pct, generation\_mix\_mw, load\_mw, net\_load\_mw, day\_ahead\_price, cross\_border\_flows\_mw.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("jenko_systems/carbon-intensity-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("jenko_systems/carbon-intensity-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call jenko_systems/carbon-intensity-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jenko_systems/carbon-intensity-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/03O0Tov9AGqf84nJv/builds/M9PNKz29anIhjvC1I/openapi.json