# Carbon Intensity API
> Great Britain\x27s electricity grid carbon intensity as an API, from the official National Grid ESO Carbon Intensity service. Get the live national carbon intensity in grams of CO2 per kWh with its index (very low to very high), the current generation mix showing exactly how much of the grid is gas, wind, solar, nuclear, biomass, hydro, coal and imports right now (with the renewable and zero-carbon percentages worked out for you), today\x27s half-hourly intensity timeline, the carbon intensity of all 18 GB regions, the intensity and fuel mix for any UK postcode, and the gCO2/kWh emission factor of each fuel type. This is exactly the data you need to shift EV charging, heat pumps, laundry and batteries to the greenest, cheapest half-hours. Perfect for smart-home and energy apps, EV-charging schedulers, sustainability dashboards, carbon-aware computing and climate tools. Covers Great Britain. No accounts, no upstream key.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/carbonintensity-api/..."
```

## Pricing
- **Free** (Free) — 3,400 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 44,000 calls/Mo, 5 req/s
- **Pro** ($13/Mo) — 212,000 calls/Mo, 15 req/s
- **Mega** ($38/Mo) — 1,055,000 calls/Mo, 40 req/s

## Endpoints

### Intensity

#### `GET /v1/forecast` — Today half-hourly intensity

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/forecast"
```

**Response:**
```json
{
    "data": {
        "count": 48,
        "periods": [
            {
                "to": "2026-05-31T23:30Z",
                "from": "2026-05-31T23:00Z",
                "index": "high",
                "actual": null,
                "forecast": 187
            },
            {
                "to": "2026-06-01T00:00Z",
                "from": "2026-05-31T23:30Z",
                "index": "high",
                "actual": null,
                "forecast": 183
            },
            {
                "to": "2026-06-01T00:30Z",
                "from": "2026-06-01T00:00Z",
                "index": "high",
                "actual": null,
                "forecast": 184
            },
            {
                "to": "2026-06-01T01:00Z",
                "from": "2026-06-01T00:30Z",
                "index": "high",
                "actual": null,
                "forecast": 183
            },
            {
                "to": "2026-06-01T01:30Z",
                "from": "2026-06-01T01:00Z",
                "index": "high",
                "actual": null,
                "forecast": 183
            },
            {
                "to": "2026-06-01T02:00Z",
                "from": "2026-06-01T01:30Z",
                "index": "high",
                "actual": null,
                "forecast": 180
            },
            {
                "to": "2026-06-01T02:30Z",
                "from": "2026-06-01T02:00Z",
                "index": "high",
                "actual
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/generation` — Current generation mix

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/generation"
```

**Response:**
```json
{
    "data": {
        "to": "2026-06-01T00:00Z",
        "from": "2026-05-31T23:30Z",
        "generation_mix": [
            {
                "fuel": "biomass",
                "percent": 11.2
            },
            {
                "fuel": "coal",
                "percent": 0
            },
            {
                "fuel": "imports",
                "percent": 16.2
            },
            {
                "fuel": "gas",
                "percent": 40.5
            },
            {
                "fuel": "nuclear",
                "percent": 10.2
            },
            {
                "fuel": "other",
                "percent": 0
            },
            {
                "fuel": "hydro",
                "percent": 0
            },
            {
                "fuel": "solar",
                "percent": 0
            },
            {
                "fuel": "wind",
                "percent": 22
            }
        ],
        "renewable_percent": 33.2,
        "zero_carbon_percent": 43.4
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:37.368Z",
        "request_id": "c0463af2-8885-4bcd-8e5c-bd2ec99e9560"
    },
    "status": "ok",
    "message": "Generation retrieved",
    "success": true
}
```

#### `GET /v1/intensity` — National carbon intensity now

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/intensity"
```

**Response:**
```json
{
    "data": {
        "to": "2026-06-01T00:00Z",
        "from": "2026-05-31T23:30Z",
        "unit": "gCO2/kWh",
        "index": "high",
        "actual": null,
        "forecast": 183
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:37.638Z",
        "request_id": "19ffffca-12b1-437b-9dca-84e74c0473a3"
    },
    "status": "ok",
    "message": "Intensity retrieved",
    "success": true
}
```

### Regional

#### `GET /v1/postcode` — Intensity by UK postcode

**Parameters:**
- `postcode` (query, required, string) — UK outward code Example: `RG10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/postcode?postcode=RG10"
```

**Response:**
```json
{
    "data": {
        "to": "2026-06-01T00:00Z",
        "dno": "SSE South",
        "from": "2026-05-31T23:30Z",
        "name": "South England",
        "region": {
            "dno": "SSE South",
            "name": "South England",
            "index": "very high",
            "forecast": 249,
            "region_id": 12,
            "generation_mix": [
                {
                    "fuel": "biomass",
                    "percent": 5.1
                },
                {
                    "fuel": "coal",
                    "percent": 0
                },
                {
                    "fuel": "imports",
                    "percent": 29.8
                },
                {
                    "fuel": "gas",
                    "percent": 57.8
                },
                {
                    "fuel": "nuclear",
                    "percent": 1.3
                },
                {
                    "fuel": "other",
                    "percent": 0
                },
                {
                    "fuel": "hydro",
                    "percent": 0
                },
                {
                    "fuel": "solar",
                    "percent": 0
                },
                {
                    "fuel": "wind",
                    "percent": 6
                }
            ]
        },
        "postcode": "RG10",
        "region_id": 12
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:37.947Z",
        "request_
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/regional` — All 18 GB regions

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/regional"
```

**Response:**
```json
{
    "data": {
        "to": "2026-06-01T00:00Z",
        "from": "2026-05-31T23:30Z",
        "count": 18,
        "regions": [
            {
                "dno": "Scottish Hydro Electric Power Distribution",
                "name": "North Scotland",
                "index": "very low",
                "forecast": 0,
                "region_id": 1,
                "generation_mix": [
                    {
                        "fuel": "biomass",
                        "percent": 0
                    },
                    {
                        "fuel": "coal",
                        "percent": 0
                    },
                    {
                        "fuel": "imports",
                        "percent": 0
                    },
                    {
                        "fuel": "gas",
                        "percent": 0
                    },
                    {
                        "fuel": "nuclear",
                        "percent": 0
                    },
                    {
                        "fuel": "other",
                        "percent": 0
                    },
                    {
                        "fuel": "hydro",
                        "percent": 0
                    },
                    {
                        "fuel": "solar",
                        "percent": 0
                    },
                    {
                        "fuel": "wind",
                        "percent": 100
                    }
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/factors` — Per-fuel emission factors

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/factors"
```

**Response:**
```json
{
    "data": {
        "unit": "gCO2/kWh",
        "factors": {
            "Oil": 935,
            "Coal": 937,
            "Wind": 0,
            "Hydro": 0,
            "Other": 300,
            "Solar": 0,
            "Biomass": 120,
            "Nuclear": 0,
            "Dutch Imports": 474,
            "Irish Imports": 458,
            "French Imports": 53,
            "Pumped Storage": 0,
            "Gas (Open Cycle)": 651,
            "Gas (Combined Cycle)": 394
        }
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:40.214Z",
        "request_id": "83f03b83-3180-4884-94a9-d4f58481b6fa"
    },
    "status": "ok",
    "message": "Factors retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/carbonintensity-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Great Britain electricity grid carbon intensity. /v1/intensity = the current national carbon intensity in gCO2/kWh (actual, forecast & index very low→very high); /v1/generation = the live generation mix by fuel (gas, wind, solar, nuclear, biomass, imports…) with renewable & zero-carbon percentages; /v1/forecast = today's half-hourly intensity timeline; /v1/regional = the 18 GB regions' intensity & mix; /v1/postcode?postcode=RG10 = intensity & mix for a UK postcode (outward code); /v1/factors = the gCO2/kWh emission factor of each fuel type. Covers Great Britain. Ideal for timing EV charging and appliances to the greenest hours.",
        "source": "National Grid ESO Carbon Intensity API (carbonintensity.org.uk)",
        "endpoints": [
            "/v1/intensity",
            "/v1/generation",
            "/v1/forecast",
            "/v1/regional",
            "/v1/postcode",
            "/v1/factors",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:03:40.269Z",
        "request_id": "ce3f965a-f9b1-4d10-89b1-13fb1cc25194"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/carbonintensity-api
OpenAPI spec: https://www.oanor.com/api/carbonintensity-api/openapi.json