NAV Navbar
  • Introduction
  • Authentication
  • Routes
  • Introduction

    Welcome to the Electricity Map API! You can use our API to get access to information about

    Furthermore, you can use this API to get historical data, live data and forecasts.

    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

    Routes

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

    Live power production breakdown

    curl 'https://api.electricitymap.org/v3/power-production-breakdown/latest?lat=55.688189&lon=12.526826' \
      -H 'auth-token: myapitoken'
    

    The above command returns JSON with units in % and MW:

    {
      "zone": "DK-DK2",
      "datetime": "2018-11-26T17:36:49.808Z",
      "powerProductionBreakdown": {
        "solar": 0,
        "nuclear": 0,
        "oil": 24,
        "unknown": 0,
        "coal": 274,
        "hydro": 0,
        "wind": 167,
        "biomass": 646,
        "gas": 213,
        "geothermal": 0
      },
      "powerProductionTotal": 1324,
      "fossilFreePercentage": 61,
      "renewablePercentage": 61,
      "updatedAt": "2018-11-26T17:36:50.751Z"
    }
    

    This endpoint retrieves the last known electricity production in the zone, broken down by production type. It can either be queried by zone identifier or by geolocation.

    Live power consumption breakdown

    curl 'https://api.electricitymap.org/v3/power-consumption-breakdown/latest?lat=55.688189&lon=12.526826' \
      -H 'auth-token: myapitoken'
    

    The above command returns JSON with units in % and MW:

    {
      "zone": "DK-DK2",
      "datetime": "2018-11-26T17:36:49.808Z",
      "powerConsumptionBreakdown": {
        "biomass": 705,
        "coal": 359,
        "gas": 301,
        "hydro": 392,
        "hydro discharge": 0,
        "nuclear": 149,
        "oil": 26,
        "solar": 0,
        "wind": 239,
        "geothermal": 0,
        "unknown": 40,
        "battery discharge": null
      },
      "powerConsumptionTotal": 2212,
      "fossilFreePercentage": 67,
      "renewablePercentage": 60,
      "updatedAt": "2018-11-26T17:36:50.751Z"
    }
    

    This endpoint retrieves the last known power consumption breakdown of an area, which represents the physical origin of electricity consumed in the zone, taking into account imports and exports, and 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/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": "2018-04-24T20:00:00.000Z"
            },
            ...
            {
                "carbonIntensity": 338,
                "datetime": "2018-04-25T19:45:00.000Z"
            }
        ]
    }
    

    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 15min.

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

    curl 'https://api.electricitymap.org/v3/power-consumption-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,
                "renewablePercentage": 75
            },
            ...
            {
                "datetime": "2018-04-25T18:45:00.000Z",
                "fossilFreePercentage": 72,
                "powerConsumptionBreakdown": {
                    "biomass": 101,
                    "coal": 494,
                    "gas": 255,
                    "geothermal": 0,
                    "hydro": 212,
                    "hydro discharge": 0,
                    "battery discharge": null,
                    "nuclear": 0,
                    "oil": 11,
                    "solar": 3,
                    "unknown": 4,
                    "wind": 1607
                },
                "powerConsumptionTotal": 2687,
                "renewablePercentage": 72
            }
        ]
    }
    

    This endpoint retrieves the last 24h of 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. The resolution is 15min.

    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:

    {
      "carbonIntensity": 264,
      "datetime": "2019-05-21T00:00:00.000Z",
      "updatedAt": "2019-05-21T18:52:32.780Z",
      "zone": "DE"
    }
    

    This endpoint retrieves a past 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/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

    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-06,
            "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-06,
            "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-05,
            "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)