Electricity API

Calculate CO2e emissions from electricity consumption based on grid carbon intensity.

Endpoints

Calculate Emissions

<span class="api-method api-method-get">GET</span> /v1/electricity/emissions

Parameters

Example Request

curl "https://api.emissions.dev/v1/electricity/emissions?\
kwh=5000&\
country=DE" \
  -H "Authorization: Bearer em_live_xxxxxxxxxxxx"

Example Response

{
  "data": {
    "type": "electricity_emission",
    "id": "b8e2f4a1-3c5d-4e6f-a7b8-9c0d1e2f3a4b",
    "attributes": {
      "emissions": {
        "co2e": 1958.8,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ipcc_ar6_gwp100",
        "co2e_grams": 1958800,
        "breakdown": {
          "scope_2_location_based": 1660.0,
          "scope_3_wtt": 298.8,
          "unit": "kg"
        },
        "ghg_protocol_scopes": {
          "scope_2": {
            "location_based": 1660.0,
            "market_based": null,
            "method_note": "Market-based requires supplier-specific emission factors or residual mix data."
          },
          "scope_3_category_3": 298.8
        },
        "source_trail": [
          {
            "data_category": "grid_intensity",
            "name": "Germany — 332 gCO₂e/kWh",
            "source": "Ember",
            "source_dataset": "Global Electricity Review 2025",
            "year": "2025",
            "region": "DE",
            "region_name": "Germany"
          }
        ]
      },
      "electricity": {
        "kwh": 5000,
        "effective_kwh": 5000,
        "grid_intensity": 332,
        "grid_intensity_unit": "gCO2e/kWh",
        "country_code": "DE",
        "resolved_location": "DE",
        "source": "country",
        "include_wtt": true,
        "include_td_losses": false,
        "is_clean_grid": false
      },
      "notices": [
        {
          "message": "This is a location-based Scope 2 calculation. For market-based reporting, use your energy supplier's specific emission factor.",
          "code": "location_based_method",
          "severity": "info"
        }
      ]
    }
  },
  "meta": {
    "methodology": "GHG Protocol Scope 2 Guidance",
    "emission_factors_year": 2025,
    "calculated_at": "2026-02-08T12:00:00Z"
  }
}

Grid Intensity Lookup

<span class="api-method api-method-get">GET</span> /v1/electricity/grid

Get all available grid carbon intensity factors, ranked by carbon intensity.

Example Response

{
  "data": [
    {
      "country_code": "IS",
      "country_name": "Iceland",
      "grid_intensity": 10,
      "unit": "gCO2e/kWh",
      "is_clean_grid": true
    },
    {
      "country_code": "FR",
      "country_name": "France",
      "grid_intensity": 42,
      "unit": "gCO2e/kWh",
      "is_clean_grid": true
    },
    {
      "country_code": "GB",
      "country_name": "United Kingdom",
      "grid_intensity": 217,
      "unit": "gCO2e/kWh",
      "is_clean_grid": false
    }
  ],
  "meta": {
    "total_countries": 100,
    "source": "Ember Global Electricity Review 2025 / EPA eGRID 2023"
  }
}

Location Resolution Hierarchy

The API resolves grid intensity using the most specific data available:

Grid Intensity Ranges

Clean Grids (<100 gCO₂e/kWh)

Dirty Grids (>500 gCO₂e/kWh)

GHG Protocol Scope 2 Reporting

The GHG Protocol requires dual Scope 2 reporting:

The ghg_protocol_scopes object separates Scope 2 (location-based) from Scope 3 Category 3 (WTT upstream emissions).

Data Sources

Error Responses

Invalid Country

{
  "error": {
    "code": "invalid_country",
    "message": "Country code 'XX' not recognised.",
    "status": 422
  }
}

Invalid State

{
  "error": {
    "code": "invalid_state",
    "message": "State code 'ZZ' not recognised for US.",
    "status": 422
  }
}