Getting started

The Electricity Maps API is your gateway to real-time, historical and forecasted electricity data worldwide.

• The Getting started section presents the different terms, parameters, and attributes of the API.
• The Signals section defines all electricity signals that can be accessed.
• The API Reference section lists the documentation for all endpoints.

Keep reading to dig deeper on how to use our API and talk with Sales when you're ready to take it further.

The following sections describe the information you need to make your first authenticated request.

All requests to the API (except for /zones) must be authorized.

The API key should be included as a header on the request: auth-token: my-api-token.

Example with cURL:

It is also possible to use Basic Auth if preferred:

Getting data for a specific area can be done in multiple ways:

1. Use the zone parameter

2. Use coordinates with lon and lat parameters

3. Use a look-up by data center, with the dataCenterProvider and dataCenterRegion parameters

The following sections describe key parameters you can use to control core characteristics of the data returned by the API.

Electricity Maps develops estimation models that provide estimated data when measured data is not available (delayed or missing).

The isEstimated flag in the returned JSON indicates whether the result is estimated or not, and the estimationMethod field indicates what model was used to generate that estimate.

By default, all endpoints return estimated data for timestamps when measured data is not available. To disable estimations in the returned JSON, the disableEstimations parameter can be set to true.

All Electricity Maps data can be delivered with various temporal granularities.

By default, all endpoints return data with a temporal granularity of 1 hour. The temporalGranularity query parameter controls the temporal granularity of data returned. Possible values are:

• 5_minutes
• 15_minutes
• hourly (default)
• daily (only for past data)
• monthly (only for past data)
• quarterly (only for past data)
• yearly (only for past data)

Each entry represents data for the following time period from the timestamp. For example, hourly data timestamped at 10:00 AM covers the period from 10:00 AM to 11:00 AM.

To calculate the carbon intensity, the flow-traced electricity mix is matched with technology-specific emission factors. We offer two primary types:

• Direct Emission Factors (Operational): These only count the emissions released directly from the operation of the power plant (like burning fuel).
• Life-Cycle Emission Factors: These provide a thorough "cradle-to-grave" accounting. They include emissions from building the power plant, operating it, extracting fuel, and disposal at the end of its life.

The emissionFactorType query parameter controls this.

Possible values are:

• lifecycle
• direct

By default, all carbon intensity endpoints return data computed using life-cycle emission factors.

Electricity Maps uses the flow-tracing methodology to compute the electricity mix and derived signals (renewable energy percentage, carbon intensity, ...) that accurately represent the electricity available on a grid accounting for domestic generation and electricity flows with neighboring grids.

For all signals computed based on the electricity mix, a parameter (that can be called flowtraced or breakdownType depending on the endpoint) can be used to receive data computed on either the domestic generation mix or the calculated flow-traced mix.

Example: If the carbon intensity is computed using the production mix, it represents the amount of emissions for each unit of electricity produced. It does not represent the carbon intensity of electricity available to consumers on the grid. If the carbon intensity is computed using the flow-traced electricity mix, it represents the amount of emissions for each unit of electricity consumed, taking into account all electricity flows across interconnected grids. Sometimes, a significant share of grid emissions come from imported electricity.

The following sections describe key concepts of Electricity Maps data.

Generally, all signals provided by Electricity Maps are available globally across the following date ranges:

• Historically, since 2017
• Real-time
• Forecasted, for the next 72 hours

Exceptions exist such as day-ahead electricity prices that are only available in Europe, and a few other zones worldwide. The coverage page groups all information relative to data availability.

Electricity Maps offers access to global data.

All zones (except aggregated zones) are assigned a tier, based on the data sources available.

• Tier A zones have measured hourly data available from the original data source for the full electricity mix. Any potential gaps are filled using Time Slicer Average (TSA).
• Tier B zones have partial measured hourly data available from the original data source. Missing information, such as the production mode breakdown, are estimated using zone-specific estimation models.
• Tier C zones do not have measured hourly source data available, but monthly or yearly totals. Hourly values are modelled with the General Purpose Zone Development model using a combination of live weather data and historical production data.

Our coverage explorer exposes the most up to date information about signal availability, per geography.

Different system operators might have different definitions for what they report as the total load. Some include losses, and discard storage, others don't.

To simultaneously guarantee a unique definition, global coverage, and provide access to system operators data, Electricity Maps provides access to different load signals:

• Total reported load represents the load data, as reported by system operators across the world.
• Total load represents the load data, as calculated by Electricity Maps. It is calculated as follows: Total load = Net generation - Exports + Imports - Charge + Discharge.
• Net load represents the load, as calculated by Electricity Maps, from which is deducted the variable renewable electricity (solar and wind).

The fossil-only carbon intensity represents the amount of greenhouse gas emitted (gCO₂eq) per unit of electricity (kWh) generated from sources that consume fossil fuels. It can be calculated for each time interval, for each geographical entity, by combining the fossil-only electricity mix data with technology-specific emission factors.

The carbon intensity computed from fossil sources only can be used as a proxy for the carbon intensity of the residual mix.

Electricity Maps provides full transparency on its data sources and methodology used to provide all signals.

A detailed methodology page with FAQs is available on the website.

Two whitepapers are also available on our website:

• Methodology for the electricity mix and derived signals
• Electricity Maps emission factors methodology

GHG Protocol Scope 2 and 3 compliance

Electricity Maps direct emission factors correspond to GHG Protocol Scope 2 reporting. As necessary, reporting entities using Electricity Maps data for carbon accounting can isolate the exact delta between the life cycle and direct values to populate Scope 3 Category 3 (Fuel- and Energy-Related Activities) inventories natively, without introducing interpretive ambiguity or risking double-counting under Scope 2 boundaries.

ISO-14064 compliance

To ensure compliance with ISO 14064-1:2018 requirements, reporting entities can properly map Electricity Maps carbon intensity to their corresponding indirect greenhouse gas emission categories:

• Category 2: Indirect greenhouse gas emissions from imported energy: Organizations reporting grid electricity under Category 2 should utilize Electricity Maps Direct Carbon Intensity. This accounts solely for physical emissions occurring at the generation stack during power production, fully satisfying the location-based direct energy imports criteria.
• Category 4: Indirect greenhouse gas emissions from products used by an organization: Upstream emissions associated with fuel extraction, refining, transport, and power generation infrastructure fall under Category 4 (specifically upstream energy-related activities). Reporting entities can natively quantify these emissions by calculating the delta between the Electricity Maps Life Cycle Carbon Intensity and Direct Carbon Intensity. Alternatively, if an organization chooses to report its total energy-related footprint comprehensively within Category 4 under a complete life-cycle boundary, the full Life Cycle Carbon Intensity metric may be applied directly.

By applying this structured allocation, organizations maintain clear reporting boundaries, prevent the double-counting of operational versus upstream supply-chain emissions, and preserve full traceability during third-party ISO 14064-3 verification.

Summary

Electricity Maps carbon intensity to use per Carbon Accounting Standard

• GHG Protocol Scope 2: Direct Carbon Intensity
• GHG Protocol Scope 3: Delta between Life Cycle and Direct Carbon Intensity
• ISO 14064-1:2018 Category 2: Direct Carbon Intensity
• ISO 14064-1:2018 Category 4: Delta between Life Cycle and Direct Carbon Intensity

Electricity Maps has worked with marginal emissions for close to a decade, when it decided to discontinue the marginal data offering in 2025 due to concerns about the veracity and verifiability of such signals. You'll find below a list of resources written on the topic, alongside with a list of caveats to consider before using marginal signals.

What marginal emissions are

Marginal emissions are the emissions of the power plant that would ramp up in reaction to an increase in electricity demand (read more in our blog post here). While marginal carbon intensity can be a useful framework for reasoning about what would happen based on a change in behavior, there are some important limitations to keep in mind:

Compatibility with regulation

Marginal emissions are incompatible with most of the reporting guidances, as well as all other major regulation. Recent legislations from the US government and the European Commission prohibit their use. Most importantly, marginal emissions are unsuitable for Scope 2 Accounting (read more here).

Greenhouse Gas Protocol The Scope 2 Guidance writes that “Companies shall not use marginal emission factors [...] for a location-based scope 2 calculation” and that "this guidance does not support an 'avoided emissions' approach for scope 2 accounting"

SBTi The Corporate near-term criteria stipulates that “avoided emissions fall under a separate accounting system from corporate inventories and do not count toward near-term science-based emission reduction targets.”

European Commission On the production of renewable liquid and gaseous transport fuels, it is stated that “the emission intensity of electricity shall be determined following the approach for calculating the average carbon intensity of grid electricity.”

US Department of Energy - Clean Hydrogen "45v" Tax Credit The guidance stipulates that “the level of the credit is based on the lifecycle greenhouse gas ("GHG") emissions that result from the process of producing clean hydrogen.”

Marginal signals oversimplify reality

On the surface, marginal emissions are the emissions caused by the power plant ramping up (or down) in response to a change in consumption. In reality, the electricity grid is a vast and complex interconnected system, having many interdependent components that all affect each other.

Grid operators acknowledge the marginal concept is an oversimplification of the reality they operate in. They state that the accuracy of these signals can't be assessed and verified in practice and therefore caution against their use.

Scientific experts warn about flaws of marginal emissions that prevent them from accurately estimating the impact of load shifting.

The Grid Operator 50 Hertz states that “Determining the correct [marginal] power plant is extremely complex or even impossible. [...] Furthermore, it is never possible to find out retrospectively whether the signal is correct”.

The Grid Operator PJM states that "Because of the various constraints and complexities involved, PJM cannot and does not make any guarantees as to the accuracy of the information nor that it is fit for any purpose."

The Princeton University & NREL state that “Short-run marginal emission factors neglect impactful phenomena and are unsuitable for assessing the power sector emissions impacts of hydrogen electrolysis”.

Public relations risks

At a time when sustainability claims come under heavy scrutiny, verifiability and auditability are key. Auditing a product feature based on marginal emissions is very difficult.

Financial Times Big Tech’s bid to rewrite the rules on net zero: [...] will allow companies to report emissions numbers that bear little relation to their real-world pollution.”

National Resources Defense Council The once in a generation chance to fix corporate emissions reporting: "Some of those global corporate giants are proposing an emissions offsetting approach that will weaken climate targets and open loopholes that allow them to claim success without delivering more ambitious – yet still attainable – climate outcomes."

Action Speaks Louder Hidden Power, Broken Rules: How companies are gaming emissions reporting rules and undermining global climate targets: “[...] pushing for new accounting rules that would allow companies to underreport their emissions by up to 90%.”

Challenging user experience

Marginal emissions can't be used to calculate end-users' footprint as presented in a historical usage dashboard. Recommendations based on marginal emissions factors may worsen the user’s historical footprint (calculated with hourly flow-traced emissions factors).

Users receive multiple other sources of information in their lives such as alerts from their electricity provider, or records of renewable generation in the news. These often contradict the recommendations formulated based on a marginal signal. Marginal emissions factors are commonly perceived as unintuitive and confusing for users, hindering trust and reducing engagement.

Further reading

We've written extensively about marginal emissions in our blog post series:

• Marginal emissions — what they are, and when to use them
• Estimating the marginal carbon intensity of electricity with machine learning
• Our latest research on Marginal emission factors
• Why marginal emission factors are unsuitable for scope 2 accounting
• Marginal vs average: which one to use for real-time decisions?
• Optimizing electricity consumption with a marginal signal may not reduce its carbon footprint
• The challenges of validating marginal signals
• From power markets to reality: Does the marginal power plant really exist?

Selected scientific articles:

P. Gagnon et al., Short-run marginal emission rates omit important impacts of electric-sector interventions

Q. Xu et al., System-level impacts of voluntary carbon-free electricity procurement strategies

R. Bhandarkar et al., Estimating the marginal emissions impact of electric vehicle adoption in the WECC region in 2030

I. Riepin et al., Spatio-temporal load shifting for truly clean computing

P. Gagnon et al., Planning for the evolution of the electric grid with a long-run marginal emission rate

W. Ricks et al., Minimizing emissions from grid-based hydrogen production in the United States

T. Sukprasert et al., On the implications of choosing average versus marginal carbon intensity signals on carbon-aware optimizations

P. Grunewald et al., Taking the long view on short-run marginal emissions: how much carbon does flexibility and energy storage save?

Guides & blogs:

CEBI, Guide to sourcing marginal emissions factor data

G. Miller, Thoughts on REsurety's Locational Marginal Emissions white paper, and the need for open and transparent avoided carbon data

WattCarbon, What about "Marginal Emissions"?