Calculate Electricity Emissions

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

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

Request

Required Parameters

Parameter	Type	Description
`kwh`	number	Electricity consumed (in units specified by `unit`)

Location Parameters

Provide one of the following to specify the grid. If none is provided, defaults to GB.

Parameter	Type	Description
`unit`	string	Input unit: `kwh`, `mwh`, `wh`
`country`	string	Country code (ISO 3166-1 alpha-2, e.g., `DE`, `FR`, `US`)
`state`	string	US state code (e.g., `CA`, `TX`). Requires `country=US`
`cloud_provider`	string	Cloud provider: `aws`, `gcp`, `azure`
`cloud_region`	string	Cloud region identifier (e.g., `eu-west-1`, `us-east-1`)

Methodology Parameters

Parameter	Type	Default	Description
`include_wtt`	boolean	`true`	Include Well-to-Tank upstream emissions (Scope 3 Category 3)
`include_td_losses`	boolean	`false`	Include transmission & distribution losses (+8%)

Output Parameters

Parameter	Type	Default	Description
`equivalents`	boolean	`false`	Include real-world equivalents

Location Resolution

The API uses the most specific grid intensity available, in priority order:

Priority	Parameters	Source	Example
1	`cloud_provider` + `cloud_region`	Electricity Maps	`aws` + `eu-west-1` → Ireland grid
2	`country=US` + `state`	EPA eGRID 2023	`US` + `CA` → 179 gCO₂e/kWh
3	`country`	Ember / DEFRA	`DE` → 332 gCO₂e/kWh

Cloud Provider Regions

When calculating data centre emissions, pass the cloud provider and region:

curl "https://api.emissions.dev/v1/electricity/emissions?\
kwh=50000&\
cloud_provider=aws&\
cloud_region=eu-west-1" \
  -H "Authorization: Bearer em_live_xxxx"

Supported Providers

Provider	Parameter Value	Example Regions
Amazon Web Services	`aws`	`eu-west-1`, `us-east-1`, `ap-southeast-1`
Google Cloud	`gcp`	`europe-west1`, `us-central1`, `asia-east1`
Microsoft Azure	`azure`	`westeurope`, `eastus`, `southeastasia`

Response

Full Response Example

{
  "data": {
    "type": "electricity_emission",
    "id": "b8e2f4a1-3c5d-4e6f-a7b8-9c0d1e2f3a4b",
    "attributes": {
      "emissions": {
        "co2e": 1280.3,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ipcc_ar6_gwp100",
        "co2e_grams": 1280300,
        "breakdown": {
          "scope_2_location_based": 1085.0,
          "scope_3_wtt": 195.3,
          "unit": "kg"
        },
        "ghg_protocol_scopes": {
          "scope_2": {
            "location_based": 1085.0,
            "market_based": null,
            "method_note": "Market-based requires supplier-specific emission factors or residual mix data. Pass market_based_factor for Scope 2 market-based reporting."
          },
          "scope_3_category_3": 195.3
        },
        "source_trail": [
          {
            "data_category": "grid_intensity",
            "name": "United Kingdom — 217 gCO₂e/kWh",
            "source": "Ember",
            "source_dataset": "Global Electricity Review 2025",
            "year": "2025",
            "region": "GB",
            "region_name": "United Kingdom"
          }
        ]
      },
      "electricity": {
        "kwh": 5000,
        "effective_kwh": 5000,
        "grid_intensity": 217,
        "grid_intensity_unit": "gCO2e/kWh",
        "country_code": "GB",
        "state_code": null,
        "resolved_location": "GB",
        "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"
  }
}

Response Fields

emissions

Field	Type	Description
`co2e`	number	Total CO₂e in kg (Scope 2 + WTT if included)
`co2e_unit`	string	Always `kg`
`co2e_grams`	integer	Total CO₂e in grams
`breakdown.scope_2_location_based`	number	Location-based Scope 2 emissions (kg)
`breakdown.scope_3_wtt`	number	Well-to-Tank upstream emissions (kg)

ghg_protocol_scopes

Field	Type	Description
`scope_2.location_based`	number	Location-based Scope 2 (kg)
`scope_2.market_based`	number\|null	Market-based Scope 2 — `null` unless supplier factor provided
`scope_3_category_3`	number	WTT upstream fuel emissions (kg)

electricity

Field	Type	Description
`kwh`	number	Input consumption
`effective_kwh`	number	Adjusted for T&D losses if enabled
`grid_intensity`	number	Carbon intensity used (gCO₂e/kWh)
`country_code`	string	Country used
`state_code`	string\|null	US state used
`source`	string	`country`, `us_state`, or `cloud_region`
`is_clean_grid`	boolean	Grid intensity < 100 gCO₂e/kWh

notices

Contextual notices are returned based on the calculation:

Code	Severity	When
`clean_grid`	info	Grid intensity < 100 gCO₂e/kWh
`dirty_grid`	warning	Grid intensity > 500 gCO₂e/kWh
`wtt_excluded`	info	WTT was disabled
`td_losses_included`	info	T&D losses were enabled
`location_based_method`	info	Always — reminds about market-based option
`cloud_region_estimate`	info	Cloud provider region was used

Transmission & Distribution Losses

Enable T&D losses to account for energy lost between generation and consumption:

curl "https://api.emissions.dev/v1/electricity/emissions?\
kwh=10000&\
country=GB&\
include_td_losses=true" \
  -H "Authorization: Bearer em_live_xxxx"

This adds 8% (IEA global average) to the effective kWh before calculating emissions. The response includes td_losses_kwh and effective_kwh in the breakdown.

Well-to-Tank (WTT)

WTT emissions represent the upstream fuel extraction, processing, and transport needed to generate the electricity. These are classified as Scope 3 Category 3 under the GHG Protocol.

WTT is included by default (18% overhead). Disable with include_wtt=false if you only need Scope 2.

Examples

UK office electricity

curl "https://api.emissions.dev/v1/electricity/emissions?kwh=5000&country=GB"

→ 1,280.3 kg CO₂e (1,085.0 Scope 2 + 195.3 WTT)

US state-level precision

curl "https://api.emissions.dev/v1/electricity/emissions?kwh=10000&country=US&state=CA"

→ 2,112.2 kg CO₂e (California grid: 179 gCO₂e/kWh)

AWS data centre

curl "https://api.emissions.dev/v1/electricity/emissions?kwh=50000&cloud_provider=aws&cloud_region=eu-west-1"

→ Calculated using Ireland's grid intensity.

Clean grid (France)

curl "https://api.emissions.dev/v1/electricity/emissions?kwh=5000&country=FR"

→ 247.8 kg CO₂e + clean_grid notice (42 gCO₂e/kWh)

Error Responses

Missing kWh

{
  "error": {
    "code": "validation_error",
    "message": "The kwh field is required.",
    "status": 422
  }
}

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
  }
}