API Documentation
Introduction
Welcome to the Electricity Maps API! You can use our API to get access to information about
- where the electricity in a specific area comes from
- how much carbon was emitted to produce it
Furthermore, you can use this API to get historical data, live data and forecasts.
Personal and commercial use
For personal use, the following endpoints are freely available with a token obtained on api-portal.electricitymaps.com:
/v3/carbon-intensity/latest
/v3/carbon-intensity/history
/v3/power-breakdown/latest
/v3/power-breakdown/history
Note: history
endpoints only cover recent history (last 24 hours), while the commercial /past
endpoint goes many years back.
For commercial use, the endpoints available depends on your contract. You can get a 1 month free trial for all endpoints (except /past
) on api-portal.electricitymaps.com or contact us to discuss how we can help you.
Geolocation
Getting data for a specific area can be done in multiple ways:
- use the
zone
parameter - see /v3/zones to get a list of zone keys available - use coordinates with
lon
andlat
parameters
⚠️ 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 the shouldUseFallbackCallerLookup
query parameter to false
.
Estimations
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
.
Emission factors
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.
Resolution
All endpoints return data with a resolution of 1 hour.
Authentication
To authorize, use this code:
# 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: myapitoken'
Make sure to replace
myapitoken
with your API key.
The API key should be included as a header in all requests:
auth-token: myapitoken
Don't have an API key? Check our available plans.
Routes
Zones
Used without an auth-token
curl 'https://api.electricitymap.org/v3/zones'
Above commands returns a json object containing all zones:
{
"AD": {
"zoneName": "Andorra"
},
"AE": {
"zoneName": "United Arab Emirates"
},
...
"US-CAR-DUK": {
"countryName": "United States of America",
"zoneName": "Duke Energy Carolinas"
}
}
Used with an auth-token:
curl 'https://api.electricitymap.org/v3/zones' \
-H 'auth-token: myapitoken'
Above command returns a json object containing the zones and routes accessible with the token:
{
"PL": {
"zoneName": "Poland",
"access": ["*"]
},
"PT": {
"zoneName": "Portugal",
"access": [
"carbon-intensity/latest",
"carbon-intensity/history",
"carbon-intensity/past",
"power-breakdown/latest",
"power-breakdown/past"
"/updated-since"
]
}
}
This endpoint returns all zones available if no auth-token is provided.
If an auth-token is provided, it returns a list of zones and routes available with this token.
HTTP Request
GET https://api.electricitymap.org/v3/zones
Health
Can be used without an auth-token
curl 'https://api.electricitymap.org/health'
The above command returns the status of the API:
{
"monitors": {
"state": "ok"
},
"status": "ok"
}
This endpoint can be used to automatically verify that the Electricity Maps API is up.
HTTP Request
GET https://api.electricitymap.org/health
Live carbon intensity
curl 'https://api.electricitymap.org/v3/carbon-intensity/latest?zone=DE' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh:
{
"zone": "DE",
"carbonIntensity": 302,
"datetime": "2018-04-25T18:07:00.350Z",
"updatedAt": "2018-04-25T18:07:01.000Z",
"emissionFactorType": "lifecycle",
"isEstimated": true,
"estimationMethod": "TIME_SLICER_AVERAGE"
}
This endpoint retrieves the last known carbon intensity (in gCO2eq/kWh) of electricity consumed in an area. It can either be queried by zone identifier or by geolocation.
HTTP Request
GET https://api.electricitymap.org/v3/carbon-intensity/latest
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
emissionFactorType | (optional) type of emission factors used for computing the carbon intensity |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Live power breakdown
curl 'https://api.electricitymap.org/v3/power-breakdown/latest?lat=48.8566&lon=2.3522' \
-H 'auth-token: myapitoken'
The above command returns JSON with units in % and MW:
{
"zone": "FR",
"datetime": "2022-04-20T09:00:00.000Z",
"updatedAt": "2022-04-20T06:40:32.246Z",
"createdAt": "2022-04-14T17:30:23.620Z",
"powerConsumptionBreakdown": {
"nuclear": 31479,
"geothermal": 0,
"biomass": 753,
"coal": 227,
"wind": 8122,
"solar": 4481,
"hydro": 7106,
"gas": 6146,
"oil": 341,
"unknown": 2,
"hydro discharge": 1013,
"battery discharge": 0
},
"powerProductionBreakdown": {
"nuclear": 31438,
"geothermal": null,
"biomass": 740,
"coal": 219,
"wind": 8034,
"solar": 4456,
"hydro": 7099,
"gas": 6057,
"oil": 341,
"unknown": null,
"hydro discharge": 1012,
"battery discharge": null
},
"powerImportBreakdown": {
"GB": 548
},
"powerExportBreakdown": {
"GB": 0
},
"fossilFreePercentage": 89,
"renewablePercentage": 36,
"powerConsumptionTotal": 59670,
"powerProductionTotal": 59396,
"powerImportTotal": 548,
"powerExportTotal": 0,
"isEstimated": true,
"estimationMethod": "TIME_SLICER_AVERAGE"
}
This endpoint retrieves the last known data about the origin of electricity in an area.
- "powerProduction" (in MW) represents the electricity produced in the zone, broken down by production type
- "powerConsumption" (in MW) represents the electricity consumed in the zone, after taking into account imports and exports, and broken down by production type.
- "powerExport" and "Power import" (in MW) represent the physical electricity flows at the zone border
- "renewablePercentage" and "fossilFreePercentage" refers to the % of the power consumption breakdown coming from renewables or fossil-free power plants (renewables and nuclear) It can either be queried by zone identifier or by geolocation.
HTTP Request
GET https://api.electricitymap.org/v3/power-breakdown/latest
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Recent carbon intensity history
curl 'https://api.electricitymap.org/v3/carbon-intensity/history?zone=DE' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh:
{
"zone": "DE",
"history": [
{
"carbonIntensity": 413,
"datetime": "2021-08-18T13:00:00.000Z",
"updatedAt": "2021-08-19T08:40:20.886Z",
"createdAt": "2021-08-15T13:40:15.544Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
},
...{
"carbonIntensity": 338,
"datetime": "2021-08-19T12:00:00.000Z",
"updatedAt": "2021-08-19T12:39:55.666Z",
"createdAt": "2021-08-16T12:39:45.450Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
}
]
}
This endpoint retrieves the last 24 hours of carbon intensity (in gCO2eq/kWh) of an area. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes.
HTTP Request
GET https://api.electricitymap.org/v3/carbon-intensity/history
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
emissionFactorType | (optional) type of emission factors used for computing the carbon intensity |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Recent power breakdown history
curl 'https://api.electricitymap.org/v3/power-breakdown/history?lat=55.588189&lon=9.16826' \
-H 'auth-token: myapitoken'
The above command returns JSON with units in % and MW:
{
"zone": "DK-DK1",
"history": [
{
"datetime": "2018-04-24T19:00:00.000Z",
"fossilFreePercentage": 75,
"powerConsumptionBreakdown": {
"biomass": 81,
"coal": 395,
"gas": 213,
"geothermal": 0,
"hydro": 521,
"hydro discharge": 0,
"battery discharge": null,
"nuclear": 0,
"oil": 9,
"solar": 2,
"unknown": 10,
"wind": 1288
},
"powerConsumptionTotal": 2519,
"powerImportBreakdown": {
"DE": 0,
"DK-DK1": 495,
"SE": 445
},
"powerImportTotal": 940,
"powerExportBreakdown": {
"DE": 35,
"DK-DK1": 0,
"SE": 0
},
"powerExportTotal": 35,
"powerProductionBreakdown": {
"battery discharge": null,
"biomass": 666,
"coal": 260,
"gas": 213,
"geothermal": 0,
"hydro": 0,
"hydro discharge": null,
"nuclear": 0,
"oil": 24,
"solar": 0,
"unknown": 0,
"wind": 176
},
"powerProductionTotal": 1339,
"renewablePercentage": 75,
"isEstimated": false,
"estimationMethod": null
},
...
]
}
This endpoint retrieves the last 24 hours of power consumption and production breakdown of an area, which represents the physical origin of electricity broken down by production type. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes.
HTTP Request
GET https://api.electricitymap.org/v3/power-breakdown/history
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Past carbon intensity history
curl 'https://api.electricitymap.org/v3/carbon-intensity/past?zone=DE&datetime=2019-05-21T00:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh:
{
"zone": "DE",
"carbonIntensity": 322,
"datetime": "2019-05-21T00:00:00.000Z",
"updatedAt": "2022-04-07T15:32:21.002Z",
"createdAt": "2022-02-08T06:20:31.772Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
}
This endpoint retrieves a past carbon intensity (in gCO2eq/kWh) of an area. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes.
HTTP Request
GET https://api.electricitymap.org/v3/carbon-intensity/past
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
datetime | datetime in ISO format |
emissionFactorType | (optional) type of emission factors used for computing the carbon intensity |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Past carbon intensity history (range)
curl 'https://api.electricitymap.org/v3/carbon-intensity/past-range?zone=DE&start=2019-05-21T21:00:00Z&end=2019-05-22T00:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh for the specified timeframe:
{
"zone": "DE",
"data": [
{
"zone": "DE",
"carbonIntensity": 339,
"datetime": "2019-05-21T21:00:00.000Z",
"updatedAt": "2022-04-07T15:32:36.348Z",
"createdAt": "2022-02-08T06:20:31.772Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
},
{
"zone": "DE",
"carbonIntensity": 317,
"datetime": "2019-05-21T22:00:00.000Z",
"updatedAt": "2022-04-07T15:32:36.348Z",
"createdAt": "2022-02-08T06:17:02.676Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
},
{
"zone": "DE",
"carbonIntensity": 305,
"datetime": "2019-05-21T23:00:00.000Z",
"updatedAt": "2022-04-07T15:32:36.348Z",
"createdAt": "2022-02-08T06:17:21.012Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
}
]
}
This endpoint retrieves a past carbon intensity (in gCO2eq/kWh) of an area within a given date range. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes. The time range is limited to 10 days.
HTTP Request
GET https://api.electricitymap.org/v3/carbon-intensity/past-range
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
start | datetime in ISO format |
end | datetime in ISO format (excluded) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Past power breakdown history
curl 'https://api.electricitymap.org/v3/power-breakdown/past?zone=DK-DK1&datetime=2020-01-04T00:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns a JSON with the power breakdown for the specified datetime:
{
"zone": "DK-DK1",
"datetime": "2020-01-04T00:00:00.000Z",
"updatedAt": "2022-04-07T09:35:03.914Z",
"createdAt": "2022-02-04T15:49:58.284Z",
"powerConsumptionBreakdown": {
"nuclear": 65,
"geothermal": 0,
"biomass": 188,
"coal": 195,
"wind": 1642,
"solar": 0,
"hydro": 13,
"gas": 72,
"oil": 8,
"unknown": 5,
"hydro discharge": 0,
"battery discharge": 0
},
"powerProductionBreakdown": {
"nuclear": null,
"geothermal": null,
"biomass": 319,
"coal": 287,
"wind": 3088,
"solar": 0,
"hydro": 2,
"gas": 97,
"oil": 10,
"unknown": 3,
"hydro discharge": null,
"battery discharge": null
},
"powerImportBreakdown": {
"DE": 1070,
"NL": 0,
"SE": 0,
"DK-DK2": 0,
"NO-NO2": 0
},
"powerExportBreakdown": {
"DE": 0,
"NL": 700,
"SE": 12,
"DK-DK2": 589,
"NO-NO2": 1387
},
"fossilFreePercentage": 87,
"renewablePercentage": 84,
"powerConsumptionTotal": 2188,
"powerProductionTotal": 3806,
"powerImportTotal": 1070,
"powerExportTotal": 2687,
"isEstimated": false,
"estimationMethod": null
}
This endpoint retrieves a past power breakdown of an area. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes.
HTTP Request
GET https://api.electricitymap.org/v3/power-breakdown/past
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
datetime | datetime in ISO format |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Past power breakdown history (range)
curl 'https://api.electricitymap.org/v3/power-breakdown/past-range?zone=DK-DK1&start=2020-01-04T00:00:00Z&end=2020-01-04T01:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns a JSON with the power breakdown for the specified timeframe:
{
"zone": "DE",
"data": [
{
"zone": "DK-DK1",
"datetime": "2020-01-04T00:00:00.000Z",
"updatedAt": "2022-04-07T09:35:03.914Z",
"createdAt": "2022-02-04T15:49:58.284Z",
"powerConsumptionBreakdown": {
"nuclear": 65,
"geothermal": 0,
"biomass": 188,
"coal": 195,
"wind": 1642,
"solar": 0,
"hydro": 13,
"gas": 72,
"oil": 8,
"unknown": 5,
"hydro discharge": 0,
"battery discharge": 0
},
"powerProductionBreakdown": {
"nuclear": null,
"geothermal": null,
"biomass": 319,
"coal": 287,
"wind": 3088,
"solar": 0,
"hydro": 2,
"gas": 97,
"oil": 10,
"unknown": 3,
"hydro discharge": null,
"battery discharge": null
},
"powerImportBreakdown": {
"DE": 1070,
"NL": 0,
"SE": 0,
"DK-DK2": 0,
"NO-NO2": 0
},
"powerExportBreakdown": {
"DE": 0,
"NL": 700,
"SE": 12,
"DK-DK2": 589,
"NO-NO2": 1387
},
"fossilFreePercentage": 87,
"renewablePercentage": 84,
"powerConsumptionTotal": 2188,
"powerProductionTotal": 3806,
"powerImportTotal": 1070,
"powerExportTotal": 2687,
"isEstimated": false,
"estimationMethod": null
}
]
}
This endpoint retrieves a past power breakdown of an area within a given date range. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes. The time range is limited to 10 days.
HTTP Request
GET https://api.electricitymap.org/v3/power-breakdown/past-range
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
start | datetime in ISO format |
end | datetime in ISO format (excluded) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Forecasted carbon intensity
curl 'https://api.electricitymap.org/v3/carbon-intensity/forecast?zone=DK-DK2&horizonHours=24' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh:
{
"zone": "DK-DK2",
"forecast": [
{
"carbonIntensity": 326,
"datetime": "2018-11-26T17:00:00.000Z"
},
{
"carbonIntensity": 297,
"datetime": "2018-11-26T18:00:00.000Z"
},
...{
"carbonIntensity": 194,
"datetime": "2018-11-28T17:00:00.000Z"
}
],
"updatedAt": "2018-11-26T17:25:24.685Z"
}
This endpoint retrieves the forecasted carbon intensity (in gCO2eq/kWh) of an area. It can either be queried by zone identifier or by geolocation.
By default, this endpoint returns 24 hours of forecasts. The forecasts span from horizon 0, which is the start of the current hour, to horizon 23. Ex: if the date and time is currently 2024-03-02 13:12:39 GMT, then the forecasts will cover the range from 2024-03-02 13:00:00 GMT to 2024-03-03 12:00:00 GMT.
You can supply an optional horizonHours
query parameter to receive forecasts for a different time horizon. If you specify 24
for the horizonHours
parameter, you will receive 24 hours of forecasts. For now, it can only accept a value of 24
hours. This will get updated in the future as we support longer horizons.
HTTP Request
GET https://api.electricitymap.org/v3/carbon-intensity/forecast
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
Forecasted power breakdown
curl 'https://api.electricitymap.org/v3/power-breakdown/forecast?zone=DE' \
-H 'auth-token: myapitoken'
The above command returns JSON with units in % and MW:
{
"zone": "DE",
"data": [
{
"zone": "DE",
"datetime": "2022-06-01T13:00:00.000Z",
"updatedAt": null,
"createdAt": null,
"powerConsumptionBreakdown": {
"nuclear": 3624,
"geothermal": 18,
"biomass": 4734,
"coal": 16987,
"wind": 7724,
"solar": 24355,
"hydro": 2884,
"gas": 6832,
"oil": 12,
"unknown": 344,
"hydro discharge": 104,
"battery discharge": 0
},
"powerProductionBreakdown": {
"nuclear": 3624,
"geothermal": 20,
"biomass": 5151,
"coal": 18753,
"wind": 8001,
"solar": 27053,
"hydro": 1879,
"gas": 7376,
"oil": 8,
"unknown": 346,
"hydro discharge": -2466,
"battery discharge": null
},
"powerImportBreakdown": {},
"powerExportBreakdown": {},
"fossilFreePercentage": 64,
"renewablePercentage": 59,
"powerConsumptionTotal": 67618,
"powerProductionTotal": 72211,
"powerImportTotal": null,
"powerExportTotal": null,
"isEstimated": null,
"estimationMethod": null
},
...{
"zone": "DE",
"datetime": "2022-06-01T19:00:00.000Z",
"updatedAt": null,
"createdAt": null,
"powerConsumptionBreakdown": {
"nuclear": 3624,
"geothermal": 18,
"biomass": 4734,
"coal": 16987,
"wind": 7724,
"solar": 24355,
"hydro": 2884,
"gas": 6832,
"oil": 12,
"unknown": 344,
"hydro discharge": 104,
"battery discharge": 0
},
"powerProductionBreakdown": {
"nuclear": 3624,
"geothermal": 20,
"biomass": 5151,
"coal": 18753,
"wind": 8001,
"solar": 27053,
"hydro": 1879,
"gas": 7376,
"oil": 8,
"unknown": 346,
"hydro discharge": -2466,
"battery discharge": null
},
"powerImportBreakdown": {},
"powerExportBreakdown": {},
"fossilFreePercentage": 64,
"renewablePercentage": 59,
"powerConsumptionTotal": 67618,
"powerProductionTotal": 72211,
"powerImportTotal": null,
"powerExportTotal": null,
"isEstimated": null,
"estimationMethod": null
}
]
}
This endpoint retrieves the most recent forecasted data about the origin of electricity in an area.
- "powerProduction" (in MW) represents the electricity produced in the zone, broken down by production type
- "powerConsumption" (in MW) represents the electricity consumed in the zone, after taking into account imports and exports, and broken down by production type.
- "powerExport" and "Power import" (in MW) represent the physical electricity flows at the zone border
- "renewablePercentage" and "fossilFreePercentage" refers to the % of the power consumption breakdown coming from renewables or fossil-free power plants (renewables and nuclear) It can either be queried by zone identifier or by geolocation.
Note that for some zones, only the power production, or power consumption breakdown is available. Forecasts of imports and exports are unavailable at the moment.
By default, this endpoint returns 24 hours of forecasts. The forecasts span from horizon 0, which is the start of the current hour, to horizon 23. Ex: if the date and time is currently 2024-03-02 13:12:39 GMT, then the forecasts will cover the range from 2024-03-02 13:00:00 GMT to 2024-03-03 12:00:00 GMT.
You can supply an optional horizonHours
query parameter to receive forecasts for a different time horizon. If you specify 24
for the horizonHours
parameter, you will receive 24 hours of forecasts. For now, it can only accept a value of 24
hours. This will get updated in the future as we support longer horizons.
HTTP Request
GET https://api.electricitymap.org/v3/power-breakdown/forecast
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
Forecasted power production breakdown
curl 'https://api.electricitymap.org/power-production-breakdown/forecast?zone=DE' \
-H 'auth-token: myapitoken'
The above command returns JSON with units in MW:
{
"zone": "DE",
"forecast": [
{
"powerProductionBreakdown": {
"nuclear": 4392,
"biomass": 5178,
"coal": 25078,
"wind": 7706,
"solar": 28604,
"hydro": 1659,
"gas": 9602,
"oil": 65,
"unknown": 0
},
"datetime": "2022-06-01T13:00:00.000Z",
"powerProductionTotal": 82284
},
...{
"powerProductionBreakdown": {
"nuclear": 4386,
"biomass": 5196,
"coal": 25566,
"wind": 7818,
"solar": 23762,
"hydro": 1711,
"gas": 10312,
"oil": 67,
"unknown": 0
},
"datetime": "2022-06-01T14:00:00.000Z",
"powerProductionTotal": 78818
}
],
"updatedAt": "2022-06-01T12:55:37.578Z"
}
This endpoint retrieves the forecasted power production breakdown of an area by production type. It can either be queried by zone identifier or by geolocation.
By default, this endpoint returns 24 hours of forecasts. The forecasts span from horizon 0, which is the start of the current hour, to horizon 23. Ex: if the date and time is currently 2024-03-02 13:12:39 GMT, then the forecasts will cover the range from 2024-03-02 13:00:00 GMT to 2024-03-03 12:00:00 GMT.
You can supply an optional horizonHours
query parameter to receive forecasts for a different time horizon. If you specify 24
for the horizonHours
parameter, you will receive 24 hours of forecasts. For now, it can only accept a value of 24
hours. This will get updated in the future as we support longer horizons.
HTTP Request
GET https://api.electricitymap.org/v3/power-production-breakdown/forecast
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
Forecasted power consumption breakdown
curl 'https://api.electricitymap.org/v3/power-consumption-breakdown/forecast?lat=59.072820&lon=17.026826&horizonHours=24' \
-H 'auth-token: myapitoken'
The above command returns JSON with units in MW:
{
"zone": "DK-DK2",
"forecast": [
{
"powerConsumptionBreakdown": {
"biomass": 483,
"coal": 475,
"gas": 338,
"hydro": 632,
"nuclear": 383,
"solar": 4,
"wind": 188,
"unknown": 69
},
"datetime": "2018-11-26T17:00:00.000Z",
"powerConsumptionTotal": 2572
},
{
"powerConsumptionBreakdown": {
"biomass": 459,
"coal": 441,
"gas": 308,
"hydro": 639,
"nuclear": 382,
"solar": 0,
"wind": 167,
"unknown": 68
},
"datetime": "2018-11-26T18:00:00.000Z",
"powerConsumptionTotal": 2464
},
...{
"powerConsumptionBreakdown": {
"biomass": 158,
"coal": 652,
"gas": 385,
"hydro": 326,
"nuclear": 169,
"solar": 44,
"wind": 210,
"unknown": 36
},
"datetime": "2018-11-27T17:00:00.000Z",
"powerConsumptionTotal": 1980
}
],
"updatedAt": "2018-11-26T17:26:57.091Z"
}
This endpoint retrieves the forecasted power consumption breakdown of an area, which represents the physical origin of electricity broken down by production type. It can either be queried by zone identifier or by geolocation.
By default, this endpoint returns 24 hours of forecasts. The forecasts span from horizon 0, which is the start of the current hour, to horizon 23. Ex: if the date and time is currently 2024-03-02 13:12:39 GMT, then the forecasts will cover the range from 2024-03-02 13:00:00 GMT to 2024-03-03 12:00:00 GMT.
You can supply an optional horizonHours
query parameter to receive forecasts for a different time horizon. If you specify 24
for the horizonHours
parameter, you will receive 24 hours of forecasts. For now, it can only accept a value of 24
hours. This will get updated in the future as we support longer horizons.
HTTP Request
GET https://api.electricitymap.org/v3/power-consumption-breakdown/forecast
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
Past marginal carbon intensity history
curl 'https://api.electricitymap.org/v3/marginal-carbon-intensity/past?zone=GB&datetime=2023-01-04T00:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns the following JSON with units in gCO2eq/kWh:
{
"zone": "GB",
"carbonIntensity": 359,
"datetime": "2023-01-04T00:00:00.000Z",
"updatedAt": "2023-10-01T18:30:28.708Z",
"createdAt": "2023-07-06T12:57:18.612Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
}
This endpoint retrieves a past marginal carbon intensity (in gCO2eq/kWh) of an area. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes. The delay with the latest available data is between 1 and 2 months.
HTTP Request
GET https://api.electricitymap.org/v3/marginal-carbon-intensity/past
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
datetime | datetime in ISO format |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Past marginal carbon intensity history (range)
curl 'https://api.electricitymap.org/v3/marginal-carbon-intensity/past-range?zone=GB&start=2023-01-04T01:00:00Z&end=2023-01-04T04:00:00Z' \
-H 'auth-token: myapitoken'
The above command returns a JSON with units in gCO2eq/kWh for the specified timeframe:
{
"zone": "GB",
"data": [
{
"zone": "GB",
"carbonIntensity": 362,
"datetime": "2023-01-04T01:00:00.000Z",
"updatedAt": "2023-10-01T18:30:28.708",
"createdAt": "2023-07-06T12:57:18.612Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
},
{
"zone": "GB",
"carbonIntensity": 369,
"datetime": "2023-01-04T02:00:00.000Z",
"updatedAt": "2023-10-01T18:30:28.708",
"createdAt": "2023-07-06T12:57:18.612Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
},
{
"zone": "GB",
"carbonIntensity": 368,
"datetime": "2023-01-04T03:00:00.000Z",
"updatedAt": "2023-10-01T18:30:28.708",
"createdAt": "2023-07-06T12:57:18.612Z",
"emissionFactorType": "lifecycle",
"isEstimated": false,
"estimationMethod": null
}
]
}
This endpoint retrieves a past marginal carbon intensity (in gCO2eq/kWh) of an area within a given date range. It can either be queried by zone identifier or by geolocation. The resolution is 60 minutes. The time range is limited to 10 days. The delay with the latest available data is between 1 and 2 months.
HTTP Request
GET https://api.electricitymap.org/v3/marginal-carbon-intensity/past-range
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
start | datetime in ISO format |
end | datetime in ISO format (excluded) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |
Updated Since
curl 'https://api.electricitymap.org/v3/updated-since?zone=DK-DK1&since=2020-02-06T00:00:00Z&start=2020-02-05T00:00:00Z&end=2020-02-07T00:00:00Z&limit=100&threshold=P1D' \
-H 'auth-token: myapitoken'
The above command returns timestamps of updates that have been made to a specific zone since a specified date.
{
"zone": "DK-DK1",
"updates": [
{
"updated_at": "2020-02-07T11:54:55.581Z",
"datetime": "2020-02-05T00:00:00.000Z"
},
{
"updated_at": "2020-02-07T11:54:55.581Z",
"datetime": "2020-02-05T23:00:00.000Z"
}
...
{
"updated_at": "2020-02-07T11:54:55.581Z",
"datetime": "2020-02-05T00:00:00.000Z"
}
],
"threshold": "P1D",
"limit": 100,
"limitReached": false
}
This endpoint returns a list of timestamps where data has been updated since a specified date for a specified zone. The 'start' and 'end' parameters can be used to specify a limited timeframe in which to search. Furthermore, the 'threshold' parameter can be used to filter the timestamps to only include entries with a difference between 'datetime' and 'updated_at' higher than the threshold. It can either be queried by zone identifier or by geolocation.
Access to this endpoint is only authorized if the token has access to one or more 'past' endpoints.
HTTP Request
GET https://api.electricitymap.org/v3/updated-since
Query Parameters
Parameter | Description |
---|---|
zone | A string representing the zone identifier |
lon | Longitude (if querying with a geolocation) |
lat | Latitude (if querying with a geolocation) |
since | datetime in ISO format |
start (optional) | datetime in ISO format |
end (optional) | datetime in ISO format |
limit (optional) | number, limit of the number of entries to output (max 1000) (default 100) |
threshold (optional) | duration in ISO 8601 format, filter for entries to include those only where the difference between datetime and updated_at is higher than the threshold. (default PT0H0M0S) |
disableEstimations | (optional) boolean (if estimated data should be disabled) |