The Grid Intensity CLI allows data to be sourced from several providers. Currently the following integrations are available:
If you would like us to integrate more providers please open an issue.
When running the Grid Intensity CLI, you can change providers by passing the --provider
flag, along with the name of the provider you want to use. Alternately, you can set GRID_INTENSITY_PROVIDER
as an environment variable.
When no provider is set, the CLI will use Ember as the default.
Ember is an energy think tank that uses data-driven insights to shift the world from coal to clean electricity.
--provider=ember-climate.org
Ember is the default provider for the Grid Intensity CLI. The Ember integration returns regional data by country, for the last calendar year.
When using Ember, you will need to pass either an Alpha-2 or Alpha-3 ISO country code. You can do this using the --region
flag.
For example, the code below returns data for Taiwan.
grid-intensity --provider=ember-climate.org --region=TW
# Returns
{
"country_code_iso_2": "TW",
"country_code_iso_3": "TWN",
"country_or_region": "Taiwan (Province of China)",
"year": 2021,
"latest_year": 2021,
"emissions_intensity_gco2_per_kwh": 565.629
}
WattTime is a nonprofit that offers technology solutions that make it easy for anyone to achieve emissions reductions without compromising cost, comfort, and function.
--provider=watttime.org
Before using the WattTime integration, you must first create a user account. This will allow you to access and use their API. Details on registering an account are available on the WattTime website.
Once you have created a WattTime account, you must set the WATT_TIME_USER
and WATT_TIME_PASSWORD
environment variables. This allows the Grid Intensity CLI to access the WattTime API.
export WATT_TIME_USER=your-username
export WATT_TIME_PASSWORD=your-password
When using WattTime, you will need to pass a region that is supported by the WattTime API. WattTime's API documentation details how you can get a list of regions, or use latitude & longitude to find a specific region.
For example, running the command below returns data for California Independent System Operator (North).
grid-intensity --provider=watttime.org --region=CAISO_NORTH
# Returns
{
"ba": "CAISO_NORTH",
"freq": "300",
"moer": "887",
"percent": "38",
"point_time": "2022-07-28T01:40:00Z"
}
Each region will return a percent
field. This value represents the relative real-time marginal emissions intensity for the past month.
If you require Marginal Operating Emissions Rate (MOER) data, this is available for free when querying the CAISO_NORTH
region but will require a WattTime Pro subscription for other regions.
The Electricity Map API provides worldwide access to 24/7 grid carbon intensity historically, in real time, and as a forecast for the next 24 hours.
--provider=electricitymap.org
Before using the Electricity Maps integration, you must first obtain an API key. This will allow you to access and use their API.
Once you have an Electricity Map API key, you must set the ELECTRICITY_MAP_API_TOKEN
environment variable. This allows the Grid Intensity CLI to access the Electricity Map API.
export ELECTRICITY_MAP_API_TOKEN=your-token
When using Electricity Maps, you will need to pass a supported region. You can get a list of all supported regions using the Electricity Map API.
For example, running the command below will return data for Portugal.
grid-intensity --provider=electricitymap.org --region=PT
National Grid ESO have developed a Regional Carbon Intensity forecast for the Great Britain electricity grid.
--provider=carbonintensity.org.uk
The UK Carbon Intensity API integration supports only one region, --region=UK
. This can be passed to the CLI as an optional parameter.
For example, the code below returns data for the UK.
grid-intensity --provider=carbonintensity.org.uk
# Returns
{
"from": "2022-07-28T02:00Z",
"to": "2022-07-28T02:30Z",
"intensity": {
"forecast": 272,
"actual": 0,
"index": "high"
}
}