Quick start
Concepts and parameters
API Reference
Guides and resources

Quick start

Introduction

The Electricity Maps API is your gateway to real-time, historical and forecasted electricity data worldwide.

  • The Quick start section presents the necessary elements to make your first request.
  • The Concepts and parameters section defines the parameters used in the API endpoints as well as key concepts about Electricity Maps data to keep in mind when ingesting data.
  • The API Reference section lists the documentation for all endpoints.
  • The Guides and resources section lists additional resources such as links to Electricity Maps methodology webpage and whitepapers.

Keep reading to dig deeper on how to use our API and talk with Sales when you're ready to take it further.

Authorization

All requests to the API (except for /zones) must be authorized.

The API key should be included as a header on the request: auth-token: my-api-token.

Example with cURL:

It is also possible to use Basic Auth if preferred:

You can find your API key on the API access page when signed in. Sign up to get started.

Geolocation

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

  1. Use the zone parameter
Find the zone-key by calling /v4/zones with your auth-token as header and you can see details about the zones you have access to.
  1. Use coordinates with lon and lat parameters
In cases where it's undesirable to send latitude and longitude with each request, it's possible to use the /v4/zone endpoint to locate the zone that corresponds with a set of coordinates ahead of time. If it is not possible to send coordinates to Electricity Maps' servers (e.g. for privacy reasons), we have built a script that can map coordinates to zones fully offline: https://github.com/electricitymaps/zone-finder.
  1. Use a look-up by data center, with the dataCenterProvider and dataCenterRegion parameters
Find available data centers by calling /v4/data-centers.
Auto fallback: If no zone is detected (or we don't have data for that area), the API will attempt to use your current location based on IP of the caller. This can be actively disabled by setting the disableCallerLookup query parameter to true.