API Reference

• GET

  /v3/carbon-intensity/past

  Past Carbon Intensity

  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 temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • datetimedatetime (ISO)

    Date in ISO format

  • emissionFactorTypestringoptional

    Select the emission-factor-type - can be "lifecycle" (LCA) or "direct" (operational)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity/past"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/carbon-intensity/past-range

  Past Range Carbon Intensity

  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 default temporal granularity is 1 hour.

  The time range is limited to 10 days (240 hours) for an hourly granularity, and to 100 days for a daily granularity.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • startdatetime (ISO)

    Start date in ISO

  • enddatetime (ISO)

    End date in ISO (excluded)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • emissionFactorTypestringoptional

    Select the emission-factor-type - can be "lifecycle" (LCA) or "direct" (operational)

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity/past-range"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/carbon-intensity/history

  Recent Carbon Intensity (last 24 hours)

  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 temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  • emissionFactorTypestringoptional

    Select the emission-factor-type - can be "lifecycle" (LCA) or "direct" (operational)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity/history"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/carbon-intensity/latest

  Latest Carbon Intensity

  This endpoint retrieves the last known carbon intensity (in gCO2eq/kWh) of electricity consumed in an area. Read more details about how we calculate this number on the Methodology page.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • emissionFactorTypestringoptional

    Select the emission-factor-type - can be "lifecycle" (LCA) or "direct" (operational)

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity/latest"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "carbonIntensity": 302,
    "datetime": "2018-04-25T18:07:00.350Z",
    "updatedAt": "2018-04-25T18:07:01.000Z",
    "emissionFactorType": "lifecycle",
    "isEstimated": false,
    "estimationMethod": null
  }

• GET

  /v3/carbon-intensity/forecast

  Forecasted Carbon Intensity

  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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity/forecast"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/renewable-energy/past-range

  Past Range Renewable Energy Percentage

  This endpoint retrieves a past renewable energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The default temporal granularity is 1 hour.

  The time range is limited to 10 days (240 hours) for an hourly granularity, and to 100 days for a daily granularity.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • startdatetime (ISO)

    Start date in ISO

  • enddatetime (ISO)

    End date in ISO (excluded)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-energy/past-range"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "data": [
      {
        "zone": "DE",
        "datetime": "2019-05-21T21:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:20:31.772Z",
        "unit": "%",
        "value": "86",
        "isEstimated": false,
        "estimationMethod": null
      },
      {
        "zone": "DE",
        "datetime": "2019-05-21T22:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:17:02.676Z",
        "unit": "%",
        "value": "84",
        "isEstimated": false,
        "estimationMethod": null
      },
      {
        "zone": "DE",
        "datetime": "2019-05-21T23:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:17:21.012Z",
        "unit": "%",
        "value": "83",
        "isEstimated": false,
        "estimationMethod": null
      }
    ]
  }

• GET

  /v3/renewable-energy/past

  Past Renewable Energy Percentage

  This endpoint retrieves a past renewable energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • datetimedatetime (ISO)

    Date in ISO format

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-energy/past"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "datetime": "2019-05-21T00:00:00.000Z",
    "updatedAt": "2022-04-07T15:32:21.002Z",
    "createdAt": "2022-02-08T06:20:31.772Z",
    "unit": "%",
    "value": "84",
    "isEstimated": false,
    "estimationMethod": null
  }

• GET

  /v3/renewable-energy/history

  Recent Renewable Energy Percentage (last 24 hours)

  This endpoint retrieves the last 24 hours of renewable energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-energy/history"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "history": [
      {
        "zone": "DE",
        "datetime": "2021-08-18T13:00:00.000Z",
        "updatedAt": "2021-08-19T08:40:20.886Z",
        "createdAt": "2021-08-15T13:40:15.544Z",
        "unit": "%",
        "value": 89,
        "isEstimated": false,
        "estimationMethod": None
      },
      // ...
      {
        "zone": "DE",
        "datetime": "2021-08-19T12:00:00.000Z",
        "updatedAt": "2021-08-19T12:39:55.666Z",
        "createdAt": "2021-08-16T12:39:45.450Z",
        "unit": "%",
        "value": 86,
        "isEstimated": true,
        "estimationMethod": "FORECASTS_HIERARCHY"
      }
    ]
  }

• GET

  /v3/renewable-energy/latest

  Latest Renewable Energy Percentage

  This endpoint retrieves the last known renewable energy percentage (in %) of electricity consumed in an area. Read more details about how we calculate this number on the Methodology page.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-energy/latest"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "datetime": "2018-04-25T18:07:00.350Z",
    "updatedAt": "2018-04-25T18:07:01.000Z",
    "createdAt": "2018-04-22T18:07:01.000Z",
    "unit": "%",
    "value": "89",  
    "isEstimated": true,
    "estimationMethod": "FORECASTS_HIERARCHY"
  }

• GET

  /v3/renewable-energy/forecast

  Forecasted Renewable Energy Percentage

  This endpoint retrieves the forecasted renewable energy percentage (in %) 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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-energy/forecast"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DK-DK2",
    "data": [
      {
        "zone": "DK-DK2",
        "datetime": "2024-08-09T12:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "86",
        "isEstimated": null,
        "estimationMethod": null
      },
      {
        "zone": "DK-DK2",
        "datetime": "2024-08-09T13:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "86",
        "isEstimated": null,
        "estimationMethod": null
      },
      ...{
        "zone": "DK-DK2",
        "datetime": "2024-08-12T12:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "86",
        "isEstimated": null,
        "estimationMethod": null
      }
    ],
  }

• GET

  /v3/carbon-free-energy/past-range

  Past Range Carbon-Free Energy Percentage

  This endpoint retrieves a past carbon-free energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The default temporal granularity is 1 hour.

  The time range is limited to 10 days (240 hours) for an hourly granularity, and to 100 days for a daily granularity.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • startdatetime (ISO)

    Start date in ISO

  • enddatetime (ISO)

    End date in ISO (excluded)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-energy/past-range"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "data": [
      {
        "zone": "DE",
        "datetime": "2019-05-21T21:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:20:31.772Z",
        "unit": "%",
        "value": "88",
        "isEstimated": false,
        "estimationMethod": null
      },
      {
        "zone": "DE",
        "datetime": "2019-05-21T22:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:17:02.676Z",
        "unit": "%",
        "value": "84",
        "isEstimated": false,
        "estimationMethod": null
      },
      {
        "zone": "DE",
        "datetime": "2019-05-21T23:00:00.000Z",
        "updatedAt": "2022-04-07T15:32:36.348Z",
        "createdAt": "2022-02-08T06:17:21.012Z",
        "unit": "%",
        "value": "83",
        "isEstimated": false,
        "estimationMethod": null
      }
    ]
  }

• GET

  /v3/carbon-free-energy/past

  Past Carbon-Free Energy Percentage

  This endpoint retrieves a past carbon-free energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • datetimedatetime (ISO)

    Date in ISO format

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-energy/past"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "datetime": "2019-05-21T00:00:00.000Z",
    "updatedAt": "2022-04-07T15:32:21.002Z",
    "createdAt": "2022-02-08T06:20:31.772Z",
    "unit": "%",
    "value": "86",
    "isEstimated": false,
    "estimationMethod": null
  }

• GET

  /v3/carbon-free-energy/history

  Recent Carbon-Free Energy Percentage (last 24 hours)

  This endpoint retrieves the last 24 hours of carbon-free energy percentage (in %) of an area.

  It can either be queried by zone identifier or by geolocation.

  The temporal granularity is 1 hour.

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-energy/history"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "history": [
      {
        "zone": "DE",
        "datetime": "2021-08-18T13:00:00.000Z",
        "updatedAt": "2021-08-19T08:40:20.886Z",
        "createdAt": "2021-08-15T13:40:15.544Z",
        "unit": "%",
        "value": 91,
        "isEstimated": false,
        "estimationMethod": None
      },
      // ...
      {
        "zone": "DE",
        "datetime": "2021-08-19T12:00:00.000Z",
        "updatedAt": "2021-08-19T12:39:55.666Z",
        "createdAt": "2021-08-16T12:39:45.450Z",
        "unit": "%",
        "value": 88,
        "isEstimated": true,
        "estimationMethod": "FORECASTS_HIERARCHY"
      }
    ]
  }

• GET

  /v3/carbon-free-energy/latest

  Latest Carbon-Free Energy Percentage

  This endpoint retrieves the last known carbon-free energy percentage (in %) of electricity consumed in an area. Read more details about how we calculate this number on the Methodology page.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-energy/latest"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "datetime": "2018-04-25T18:07:00.350Z",
    "updatedAt": "2018-04-25T18:07:01.000Z",
    "createdAt": "2018-04-22T18:07:01.000Z",
    "unit": "%",
    "value": "91",  
    "isEstimated": true,
    "estimationMethod": "FORECASTS_HIERARCHY"
  }

• GET

  /v3/carbon-free-energy/forecast

  Forecasted Carbon-Free Energy Percentage

  This endpoint retrieves the forecasted carbon-free energy percentage (in %) 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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-energy/forecast"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DK-DK2",
    "data": [
      {
        "zone": "DK-DK2",
        "datetime": "2024-08-09T12:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "84",
        "isEstimated": null,
        "estimationMethod": null
      },
      {
        "zone": "DK-DK2",
        "datetime": "2024-08-09T13:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "88",
        "isEstimated": null,
        "estimationMethod": null
      },
      ...{
        "zone": "DK-DK2",
        "datetime": "2024-08-12T12:00:00.000Z"
        "updatedAt": "2024-08-09T11:36:17.870Z"
        "createdAt": "2024-08-09T11:36:17.870Z"
        "unit": "%",
        "value": "88",
        "isEstimated": null,
        "estimationMethod": null
      }
    ],
  }

• GET

  /v3/power-breakdown/past-range

  Past Range Power Breakdown

  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 default temporal granularity is 1 hour. When the aggregationPeriod parameter is used, data is returned in MWh.

  The time range is limited to 10 days (240 hours) for an hourly granularity, and to 100 days for a daily granularity.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • startdatetime (ISO)

    Start date in ISO

  • enddatetime (ISO)

    End date in ISO (excluded)

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-breakdown/past-range"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/power-breakdown/past

  Past Power Breakdown

  This endpoint retrieves a past power breakdown of an area.

  It can either be queried by zone identifier or by geolocation.

  The default temporal granularity is 1 hour. When the aggregationPeriod parameter is used, data is returned in MWh.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • datetimedatetime (ISO)

    Date in ISO format

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-breakdown/past"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/power-breakdown/history

  Recent Power Breakdown (last 24 hours)

  This endpoint retrieves the last 24 hours of data detailed information 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.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-breakdown/history"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/power-breakdown/latest

  Latest Power Breakdown

  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.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  • temporalGranularitystringoptional

    A string indicating the temporal granularity of data to be returned. Default value is 'hourly' and supported values are '5_minutes', '15_minutes', 'hourly'. For past and past-range endpoints 'daily', 'weekly', 'monthly', 'quarterly', and 'yearly' are also supported.

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-breakdown/latest"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/power-breakdown/forecast

  Forecasted Power Breakdown

  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.

  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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-breakdown/forecast"
  -H "auth-token: my-api-token"

  Response

  {
    "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-01T14: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
      },
      // ...
    ]
  }

• GET

  /v3/power-consumption-breakdown/forecast

  Forecasted Power Consumption Breakdown

  This endpoint is being deprecated as we transition to an improved forecasting system. Please use /v3/power-breakdown/forecast instead for higher quality data and continuous support.

  This endpoint retrieves the forecasted power consumption breakdown of an area, which represents the physical origin of electricity 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.

  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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-consumption-breakdown/forecast"
  -H "auth-token: my-api-token"

  Response

  {
    "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
      }
      // ...    
    ],
    "updatedAt": "2018-11-26T17:26:57.091Z"
  }

• GET

  /v3/power-production-breakdown/forecast

  Forecasted Power Production Breakdown

  This endpoint is being deprecated as we transition to an improved forecasting system. Please use /v3/power-breakdown/forecast instead for higher quality data and continuous support.

  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.

  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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/power-production-breakdown/forecast"
  -H "auth-token: my-api-token"

  Response

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

• GET

  /v3/price-day-ahead/forecast

  Forecasted Day-Ahead Price

  This endpoint retrieves the forecasted market day-ahead prices (in EUR/MWh) of an area.

  When day-ahead market prices are published for the horizon requested, published prices are returned by the endpoint. When prices are not yet published, prices forecasted by Electricity Maps are returned. The source is indicated for every datapoint in the response field 'source'.

  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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 6, 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/price-day-ahead/forecast"
  -H "auth-token: my-api-token"

  Response

  {
    "zone": "DE",
    "data": [
      {
        "datetime": "2025-02-26T10:00:00.000Z",
        "createdAt": "2025-02-25T11:55:42.644Z",
        "updatedAt": "2025-02-25T11:55:42.644Z",
        "value": 78.34,
        "unit": "EUR/MWh",
        "source": "nordpool.com",
      },
      ...
      {
        "datetime": "2025-02-27T10:00:00.000Z",
        "createdAt": "2025-02-25T11:55:42.644Z",
        "updatedAt": "2025-02-26T11:55:42.644Z",
        "value": 125.76,
        "unit": "EUR/MWh",
        "source": "Electricity Maps Forecast",
      },
    ]
  }

• GET

  /v3/updated-since

  Updated Since

  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.

  Attributes

  • zonestring

    A string representing the zone identifier

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • sincedatetime (ISO)optional

    Datetime in ISO format

  • startdatetime (ISO)

    Start date in ISO

  • enddatetime (ISO)

    End date in ISO (excluded)

  • limitnumberoptional

    limit of the number of entries to output (max 1000)

  • thresholdstringoptional

    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.

  • disableEstimationsbooleanoptional

    A boolean indicating if estimated data should be disabled

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/updated-since"
  -H "auth-token: my-api-token"

  Response

  {
    "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"
      }
    ],
    "threshold": "P1D",
    "limit": 100,
    "limitReached": false
  }

• GET

  /v3/zones

  Zones

  This endpoint returns all zones available if no auth-token is provided. Note that this list currently includes zones with no data available, which will be changed in a future API version.

  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 are accessible.

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/zones"
  -H "auth-token: my-api-token"

  Response

  {
    "DE": {
      "zoneName": "Germany",
      "access": [
        "carbon-intensity/latest",
        "carbon-intensity/history",
        "power-breakdown/latest",
        "power-breakdown/history",
      ]
    },
    "PL": {
      "zoneName": "Poland",
      "access": ["*"]
    },
  }

• GET

  /v3/data-centers

  Data centers

  This endpoint returns all information about data centers Electricity Maps and its contributors have mapped.

  Query parameters can be used to filter out data centers geographically.

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  • dataCenterProviderstring

    Provider name for the data center, always lower case, ex: gcp, if querying for a data center

  • pagenumber

    Page for pagination

  • limitnumber

    Limit for pagination (number of returned elements in the result)

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/data-centers"
  -H "auth-token: my-api-token"

  Response

  [
      {
          "provider": "aws",
          "lonlat": [
              18.4231,
              -33.9221
          ],
          "displayName": "Cape Town (af-south-1)",
          "region": "af-south-1",
          "zoneKey": "ZA",
          "status": "operational",
          "source": "https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html",
          "operationalSince": null
      },
      {
          "provider": "aws",
          "lonlat": [
              114.1694,
              22.3193
          ],
          "displayName": "Hong Kong (ap-east-1)",
          "region": "ap-east-1",
          "zoneKey": "HK",
          "status": "operational",
          "source": "https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html",
          "operationalSince": null
      },
  ]

• GET

  /v3/carbon-intensity-level/latest

  Latest Carbon Intensity Level

  This endpoint returns a high, moderate, or low signal for the most recent hour that indicates how the current carbon intensity for a given zone compares to a rolling average of the previous 10 days.

  The thresholds for high, moderate, and low are as follows:

  • Low: 15% below average (ratio < 0.85)
  • Moderate: between 15% below and 15% above average (0.85 ≤ ratio ≤ 1.15)
  • High: 15% above average (ratio > 1.15)

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-intensity-level/latest"
  -H "auth-token: my-api-token"

  Response

  {
      "zone": "DK-DK2",
      "data": [
          {
              "level": "high",
              "datetime": "2025-06-12T17:00:00.000Z"
          }
      ]
  }

• POST

  /beta/carbon-aware-scheduler

  Carbon aware scheduler

  This endpoint facilitates the implementation of carbon or grid awareness. For any flexible processing or compute job, whether in time and/or location, the scheduler will determine the optimal execution time and location.

  Information about the job need to be provided in the request body. It should contain:

  • duration: Expected duration of the job, using the ISO8601 standard.
  • startWindow: Start of the optimization window, earliest timestamp at which the job can be scheduled.
  • endWindow: End of the optimization window, latest time at which the job can end.
  • locations: list of location parameters. Can be a list of Electricity Maps zones, a list of data centers (see v3/data-centers), or a list of (latitude, longitude) coordinates.
  • optimizationMetric: The scheduler can use the flow-traced carbon intensity, (flow-traced_carbon_intensity), net load (net_load) or flow-traced renewable share (flow-traced_renewable_share) to determine the optimal execution time and location.

  Request Body

  {
      "duration": "PT3H",
      "startWindow": "2025-06-16T15:00:00+00:00",
      "endWindow": "2025-06-22T01:00:00+00:00",
      "locations": [
          {"dataCenterProvider": "gcp", "dataCenterRegion": "europe-west1"},
          {"dataCenterProvider": "gcp", "dataCenterRegion": "europe-north1"}
      ],
      "optimizationMetric": "flow-traced_carbon_intensity",
  }

  Request

  Copy

  curl -X POST "https://api.electricitymaps.com/beta/carbon-aware-scheduler"
  -H "auth-token: my-api-token"

  Response

  {
      "optimalStartTime": "2025-06-17T15:00:00.000Z",
      "optimalLocation": {
          "dataCenterProvider": "gcp",
          "dataCenterRegion": "europe-north1"
      },
      "optimizationOutput": {
          "metricValueImmediateExecution": 55.45,
          "metricValueOptimalExecution": 51.79,
          "metricValueStartWindowExecution": 55.37,
          "metricUnit": "gCO2/kWh",
          "optimizationMetric": "flow-traced_carbon_intensity",
          "zoneKey": "FI"
      }
  }

• GET

  /v3/total-load/forecast

  Total Load Forecast

  The total load is the total electricity made available on the grid at a given point in time. This concept may also be referred to as demand or total consumption. It is measured in megawatts (MW).

  This endpoint retrieves the most recent forecasted data about the total load in 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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • lonstring

    Longitude, if querying with a geolocation

  • latstring

    Latitude, if querying with a geolocation

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/total-load/forecast"
  -H "auth-token: my-api-token"

  Response

  {                                                                                                                                                                                                
    "zone": "DE",                                                                                                                                                                                  
    "data": [                                                                                                                                                                                      
      {                                                                                                                                                                                            
        "zone": "DE",                                                                                                                                                                              
        "datetime": "2025-06-17T07:00:00.000Z",                                                                                                                                                    
        "createdAt": "2025-06-17T06:55:15.908Z",                                                  
        "updatedAt": "2025-06-17T06:55:15.908Z",                                                                                                                                                   
        "value": 58937.43,                                                                                                                                                                         
        "unit": "MW",                                                                                                                                                                              
        "source": "PREDICTED",                                                                                                                                                                     
        "isEstimated": false,                                                                                                                                                                      
        "estimationMethod": null                                                                                                                                                                  
      },               
      // ...
    ]
  }

• GET

  /v3/net-load/forecast

  Net Load Forecast

  The net load is the total electricity made available on the grid at a given point in time, minus solar and wind. Because Electricity Maps applies flowtracing, this calculation takes imports and exports of solar and wind into account. Essentially, it represents the remaining load that must be met by other power sources, primarily fossil fuel plants, to maintain grid stability. This concept may also be referred to as net demand or net consumption. It is measured in megawatts (MW).

  This endpoint retrieves the most recent forecasted data about the net load in 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 24.

  Example: 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 13:00:00 GMT.

  You can supply an optional horizonHours query parameter to receive forecasts for a different time horizon (availability depends on your plan). If you specify 24 for the horizonHours parameter, you will receive 24 hours of forecasts. Accepted values are 24, 48 and 72 hours.

  Attributes

  • zonestring

    A string representing the zone identifier

  • horizonHoursnumberoptional

    A number indicating the horizon of the forecast returned. Accepted values are 6, 24, 48, 72 (availability depends on your plan).

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  • dataCenterRegionstringoptional

    Name of the region of the data center according to the provider, always lower case and dash separated, ex: europe-west1, if querying for a data center

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/net-load/forecast"
  -H "auth-token: my-api-token"

  Response

  {                                             
    "zone": "DE",                               
    "data": [                                   
      {                         
        "zone": "DE",           
        "datetime": "2025-06-17T07:00:00.000Z",
        "createdAt": "2025-06-17T06:55:15.908Z",
        "updatedAt": "2025-06-17T06:55:15.908Z",
        "value": 28345.47,                      
        "unit": "MW",                           
        "source": "PREDICTED",                  
        "isEstimated": false,                   
        "estimationMethod": null                
      },
      // ...
    ]
  }

• GET

  /v3/carbon-free-percentage-level/latest

  Latest Carbon-Free Energy Percentage Level

  This endpoint returns a high, moderate, or low signal for the most recent hour that indicates how the current carbon-free energy percentage for a given zone compares to a rolling average of the previous 10 days.

  The thresholds for high, moderate, and low are as follows:

  • Low: 15% below average (ratio < 0.85)
  • Moderate: between 15% below and 15% above average (0.85 ≤ ratio ≤ 1.15)
  • High: 15% above average (ratio > 1.15)

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/carbon-free-percentage-level/latest"
  -H "auth-token: my-api-token"

  Response

  {
      "zone": "DE",
      "data": [
          {
              "level": "high",
              "datetime": "2025-06-23T11:00:00.000Z"
          }
      ]
  }

• GET

  /v3/renewable-percentage-level/latest

  Latest Renewable Energy Percentage Level

  This endpoint returns a high, moderate, or low signal for the most recent hour that indicates how the current renewable energy percentage for a given zone compares to a rolling average of the previous 10 days.

  The thresholds for high, moderate, and low are as follows:

  • Low: 15% below average (ratio < 0.85)
  • Moderate: between 15% below and 15% above average (0.85 ≤ ratio ≤ 1.15)
  • High: 15% above average (ratio > 1.15)

  Attributes

  • zonestring

    A string representing the zone identifier

  • latstring

    Latitude, if querying with a geolocation

  • lonstring

    Longitude, if querying with a geolocation

  Request

  Copy

  curl -X GET "https://api.electricitymaps.com/v3/renewable-percentage-level/latest"
  -H "auth-token: my-api-token"

  Response

  {
      "zone": "DE",
      "data": [
          {
              "level": "high",
              "datetime": "2025-06-23T11:00:00.000Z"
          }
      ]
  }