API Documentation

Introduction

Welcome to the Electricity Map 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.

Geolocation

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

use the zoneKey parameter - see /v3/zones to get a list of zone keys available
use coordinates with lon and lat 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

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

You must replace myapitoken with your personal API key.

Don't have an API key? Contact us.

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.

["*"] means that all routes on a zone is accessible.

HTTP Request

GET https://api.electricitymap.org/v3/zones

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

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)

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": "DK-DK2",
  "datetime": "2018-11-26T18:02:13.918Z",
  "powerProductionBreakdown": {
    "biomass": 666,
    "coal": 260,
    "gas": 213,
    "geothermal": 0,
    "hydro": 0,
    "nuclear": 0,
    "oil": 24,
    "solar": 0,
    "unknown": 0,
    "wind": 176
  },
  "powerProductionTotal": 1339,
  "powerConsumptionBreakdown": {
    "battery discharge": null,
    "biomass": 744,
    "coal": 377,
    "gas": 330,
    "geothermal": 0,
    "hydro": 268,
    "hydro discharge": 0,
    "nuclear": 179,
    "oil": 27,
    "solar": 0,
    "unknown": 48,
    "wind": 270
  },
  "powerConsumptionTotal": 2244,
  "powerImportBreakdown": {
    "DE": 0,
    "DK-DK1": 495,
    "SE": 445
  },
  "powerImportTotal": 940,
  "powerExportBreakdown": {
    "DE": 35,
    "DK-DK1": 0,
    "SE": 0
  },
  "powerExportTotal": 35,
  "fossilFreePercentage": 65,
  "renewablePercentage": 57,
  "updatedAt": "2018-11-26T18:02:14.873Z"
}

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)

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"
    },
    ...{
      "carbonIntensity": 338,
      "datetime": "2021-08-19T12:00:00.000Z",
      "updatedAt": "2021-08-19T12:39:55.666Z",
      "createdAt": "2021-08-16T12:39:45.450Z"
    }
  ]
}

This endpoint retrieves the last 24h 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)

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
        },
        ...
    ]
}

This endpoint retrieves the last 24h 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-consumption-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)

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": 314,
  "datetime": "2019-05-21T00:00:00.000Z",
  "updatedAt": "2020-10-11T21:55:55.874Z",
  "createdAt": "2019-05-24T17:33:01.027Z"
}

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

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:

{
  "data": [
    {
      "zone": "DE",
      "carbonIntensity": 329,
      "datetime": "2019-05-21T21:00:00.000Z",
      "updatedAt": "2021-03-08T02:38:16.558Z",
      "createdAt": "2019-05-24T17:33:01.027Z"
    },
    {
      "zone": "DE",
      "carbonIntensity": 308,
      "datetime": "2019-05-21T22:00:00.000Z",
      "updatedAt": "2021-03-07T20:25:18.757Z",
      "createdAt": "2019-05-24T17:33:01.027Z"
    },
    {
      "zone": "DE",
      "carbonIntensity": 296,
      "datetime": "2019-05-21T23:00:00.000Z",
      "updatedAt": "2020-10-12T09:45:47.928Z",
      "createdAt": "2019-05-24T17:33:01.027Z"
    }
  ]
}

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)

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": "2020-01-06T19:53:21.745Z",
  "createdAt": "2020-01-04T08:34:35.420Z",
  "powerConsumptionBreakdown": {
    "nuclear": 66,
    "geothermal": 0,
    "biomass": 189,
    "coal": 192,
    "wind": 1624,
    "solar": 0,
    "hydro": 13,
    "gas": 65,
    "oil": 8,
    "unknown": 4,
    "hydro discharge": 0,
    "battery discharge": null
  },
  "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": 1080.0100000000011,
    "NL": 0,
    "SE": 0,
    "DK-DK2": 0,
    "NO-NO2": 0
  },
  "powerExportBreakdown": {
    "DE": 0,
    "NL": 699.8700000000001,
    "SE": 46,
    "DK-DK2": 589.9600000000006,
    "NO-NO2": 1387
  },
  "fossilFreePercentage": 87,
  "renewablePercentage": 84,
  "powerConsumptionTotal": 2163,
  "powerProductionTotal": 3806,
  "powerImportTotal": 1080,
  "powerExportTotal": 2723
}

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

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:

{
  "data": [
    {
      "zone": "DK-DK1",
      "datetime": "2020-01-04T00:00:00.000Z",
      "updatedAt": "2020-01-06T19:53:21.745Z",
      "createdAt": "2020-01-04T08:34:35.420Z",
      "powerConsumptionBreakdown": {
        "nuclear": 66,
        "geothermal": 0,
        "biomass": 189,
        "coal": 192,
        "wind": 1624,
        "solar": 0,
        "hydro": 13,
        "gas": 65,
        "oil": 8,
        "unknown": 4,
        "hydro discharge": 0,
        "battery discharge": null
      },
      "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": 1080.0100000000011,
        "NL": 0,
        "SE": 0,
        "DK-DK2": 0,
        "NO-NO2": 0
      },
      "powerExportBreakdown": {
        "DE": 0,
        "NL": 699.8700000000001,
        "SE": 46,
        "DK-DK2": 589.9600000000006,
        "NO-NO2": 1387
      },
      "fossilFreePercentage": 87,
      "renewablePercentage": 84,
      "powerConsumptionTotal": 2163,
      "powerProductionTotal": 3806,
      "powerImportTotal": 1080,
      "powerExportTotal": 2723
    }
  ]
}

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)

Forecasted carbon intensity

curl 'https://api.electricitymap.org/v3/carbon-intensity/forecast?zone=DK-DK2' \
  -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.

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 consumption breakdown

curl 'https://api.electricitymap.org/v3/power-consumption-breakdown/forecast?lat=59.072820&lon=17.026826' \
  -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.

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)

Forecasted marginal carbon intensity

curl 'https://api.electricitymap.org/v3/marginal-carbon-intensity/forecast?zone='GB' \
  -H 'auth-token: myapitoken'

The above command returns the following JSON with units in gCO2eq/kWh:

{
  "zone": "GB",
  "forecast": [
    {
      "marginalCarbonIntensity": 532,
      "datetime": "2018-11-26T17:00:00.000Z"
    },
    {
      "marginalCarbonIntensity": 492,
      "datetime": "2018-11-26T18:00:00.000Z"
    },
    ...{
      "marginalCarbonIntensity": 544,
      "datetime": "2018-11-27T17:00:00.000Z"
    }
  ],
  "updatedAt": "2018-11-26T17:13:49.747Z"
}

Forecasted marginal power consumption breakdown

curl 'https://api.electricitymap.org/v3/marginal-power-consumption-breakdown/forecast?lat=59.600379&lon=15.671817' \
  -H 'auth-token: myapitoken'

The above command returns a JSON with unit-less data:

{
  "zone": "SE",
  "forecast": [
    {
      "marginalPowerConsumptionBreakdown": {
        "biomass": 0.010644844545310124,
        "coal": 0.055238780793742955,
        "gas": 0.04408115817237451,
        "hydro": 0.8662160577968173,
        "nuclear": -1.3808108049580578e-6,
        "oil": 0.003017717342664587,
        "solar": 0,
        "wind": 0,
        "geothermal": 0,
        "unknown": 0.011761929291773677,
        "hydro-discharge": 0.00986604892807125,
        "hydro-charge": -0.0008251560599492709
      },
      "datetime": "2018-11-26T17:00:00.000Z"
    },
    {
      "marginalPowerConsumptionBreakdown": {
        "biomass": 0.012539835053845445,
        "coal": 0.06356673565278453,
        "gas": 0.05055281292106399,
        "hydro": 0.8496355715412874,
        "nuclear": -6.849087448338248e-6,
        "oil": 0.0033468893746003378,
        "solar": 0,
        "wind": 0,
        "geothermal": 0,
        "unknown": 0.011378577320012732,
        "hydro-discharge": 0.009207022400598933,
        "hydro-charge": -0.0002205951767450215
      },
      "datetime": "2018-11-26T18:00:00.000Z"
    },
    ...{
      "marginalPowerConsumptionBreakdown": {
        "biomass": 0.015400388034869442,
        "coal": 0.04568070346327031,
        "gas": 0.0329398221162075,
        "hydro": 0.8857615857957369,
        "nuclear": 1.3950880074226387e-5,
        "oil": 0.002056780498685778,
        "solar": 0,
        "wind": 0,
        "geothermal": 0,
        "unknown": 0.011436268311217067,
        "hydro-discharge": 0.00839406953653962,
        "hydro-charge": -0.001683568636600882
      },
      "datetime": "2018-11-27T17:00:00.000Z"
    }
  ],
  "updatedAt": "2018-11-26T17:13:49.343Z"
}

This endpoint retrieves the forecasted marginal power consumption breakdown of an area, which represents the physical marginal origin of electricity broken down by production type. It can either be queried by zone identifier or by geolocation.

HTTP Request

GET https://api.electricitymap.org/v3/marginal-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)

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)