Welcome to the Electricity Maps API! You can use the API to get access to information about:
Furthermore, you can use this API to get historical data, live data and forecasts.
Getting data for a specific area can be done in multiple ways:
zone parameterlon and lat parameters
Find the zone-key by calling /v3/zones with your auth-token as header and you can see details about the zones you have access to
Auto fallback: If no zone is detected (or we don't have data for that area), the API will attempt to use your current location based on IP of the caller. This can be actively disabled by setting theshouldUseFallbackCallerLookup query parameter to false
The API key should be included as a header in all requests: auth-token: my-api-token.
Don't have an API key? Check out our available plans
In a shell, you should pass the correct header with each request:
curl 'https://api.electricitymap.org/v3/carbon-intensity/latest?zone=DE'
-H 'auth-token: my-api-token'For the free plan, the following endpoints are available:
Note: history endpoints only cover recent history (last 24 hours), while the commercial /past endpoint goes many years back.
All endpoints return estimated data by default for timestamps when measured data is not available.
The isEstimated flag in the the returned JSON indicates whether the result is estimated or not, and the estimationMethod field indicates what model was used to generate that estimate. Documentation about estimation models can be found here.
To disable estimations in the returned JSON, the disableEstimations parameter can be set to true.
All endpoints return data with a resolution of 1 hour.
Each entry represents data for the following hour from the timestamp. For example, data timestamped at 10:00 AM covers the period from 10:00 AM to 11:00 AM.
For the carbon-intensity endpoints you can specify the type of emissionFactors to use. To use this, include a emissionFactorType=??? parameter in your request. The supported parameters are direct and lifecycle. The default parameter is lifecycle.
The emission factors used can be viewed here.