Getting grid intensity for a location

Overview

Knowing the grid intensity for the locations in which your code runs allows you to make better informed decisions about where and/or when to run it.

In this tutorial, you will use the Grid Intensity CLI to:

1. Get historical intensity data for a location.
2. Change data providers, and
3. Get near real-time grid intensity data for a location.

Before starting

Ensure that you have the Grid Intensity CLI installed locally.

Learning goals

• How to use the Grid Intensity CLI to get historical and near real-time data.
• How to change providers using the CLI.
• How to set a location using the CLI.

In this tutorial we will be using the Ember and WattTime provider integrations. We will use the Grid Intensity CLI to get data for the country of Portugal.

Get grid intensity for the last calendar year

To being with, let's get grid intensity data for the last calendar year. By doing this, we can get a snapshot of a country's carbon intensity profile.

Once you have installed the Grid Intensity CLI, run the following command in your terminal.

grid-intensity --location PT

The command above uses the Ember dataset - the default integration for the Grid Intensity CLI. We have used the --location flag to request data for Portugal (PT).

Running the command above will return data that looks similar to the snippet below.

[
        {
                "emissions_type": "average",
                "metric_type": "absolute",
                "provider": "Ember",
                "location": "PT",
                "units": "gCO2e per kWh",
                "valid_from": "2021-01-01T00:00:00Z",
                "valid_to": "2021-12-31T23:59:00Z",
                "value": 222.632
        }
]

Here, we are interested in the value of the emissions_intensity_gco2_per_kwh field. This shows us how many grams of CO2 were emitted per kilowatt-hour of electricity generated in Portugal during 2021. The closer this number is to zero, the cleaner a country's grid is.

Get near real-time grid intensity data

Having historical data for a location is a great first step. But, if we want our code to be carbon aware then we'll need to get more up-to-date information.

To do this, we will use the WattTime API integration.

Registration

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

Using WattTime with the Grid Intensity CLI

Once you have setup your WattTime account, you can run the command below in your terminal.

grid-intensity --provider WattTime --location PT

Here, we use the --provider flag to let the CLI know to fetch data from the WattTime API. As before, we have set the --location flag to return data for Portugal (PT).

Running the command above will return data that looks similar to the snippet below.

[
        {
                "emissions_type": "marginal",
                "metric_type": "relative",
                "provider": "WattTime",
                "location": "PT",
                "units": "percent",
                "valid_from": "2022-08-19T05:00:00Z",
                "valid_to": "2022-08-19T05:05:00Z",
                "value": 71
        }
]

Here, we are interested in the value of the percent field. This value represents the relative real-time marginal emissions intensity for the past month. A lower value here represents a cleaner electricity grid.

Wrapping up

Now you know how to use different providers to fetch country-level grid intensity data. From here you can:

• Try some of the other provider integrations.
• Export grid intensity information to be used by other tools.