Skip to content

providers.md

Latest commit

 

History

History
197 lines (139 loc) · 7.07 KB

providers.md

File metadata and controls

197 lines (139 loc) · 7.07 KB
Raw
title Providers
description The Grid Intensity CLI allows data to be sourced from several providers.
eleventyNavigation
key title sectionTitle order
providers
Providers
Explanations
30

{{ title }}

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.

Listing providers

{% include 'snippets/grid-cli/list-providers.md' %}

Changing providers

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.

Please note that some providers require user account and/or API tokens to be set as well.

Ember Default

Ember is an energy think tank that uses data-driven insights to shift the world from coal to clean electricity.

--provider Ember

Ember is the default provider for the Grid Intensity CLI. The Ember integration returns regional data by country, for the last calendar year.

Required parameters

When using Ember, you will need to pass either an Alpha-2 or Alpha-3 ISO country code. You can do this using the --location flag.

For example, the code below returns data for Taiwan.

grid-intensity --provider Ember --location TW

# Returns

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

WattTime
Registration required

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

{% include 'snippets/grid-cli/watttime-registration.md' %}

Required parameters

When using WattTime, you will need to pass a location that is supported by the WattTime API. WattTime's API documentation details how you can get a list of locations, or use latitude & longitude to find a specific location.

For example, running the command below returns an array data for California Independent System Operator (North).

grid-intensity --provider WattTime --location CAISO_NORTH

# Returns

[
        {
                "emissions_type": "marginal",
                "metric_type": "relative",
                "provider": "WattTime",
                "location": "CAISO_NORTH",
                "units": "percent",
                "valid_from": "2022-08-19T07:40:00Z",
                "valid_to": "2022-08-19T07:45:00Z",
                "value": 32
        },
        {
                "emissions_type": "marginal",
                "metric_type": "absolute",
                "provider": "WattTime",
                "location": "CAISO_NORTH",
                "units": "lbCO2e per MWh",
                "valid_from": "2022-08-19T07:40:00Z",
                "valid_to": "2022-08-19T07:45:00Z",
                "value": 918
        }
]

Limitations

Each location will return a percent field. This value represents the relative real-time marginal emissions intensity for the past month.

If you require absolute Marginal Operating Emissions Rate (MOER) data, this is available for free when querying the CAISO_NORTH location as shown above. However, you will require a WattTime Pro subscription to obtain this data for other locations.

Electricity Maps
API token required

The Electricity Maps API provides worldwide access to 24/7 grid carbon intensity historically, in real time, and as a forecast for the next 24 hours.

--provider ElectricityMaps

Registration

Before using the Electricity Maps integration, you must first obtain an API key. This will allow you to access and use their API. You can use their free tier for non-commercial use. You can also register for a 30 day trial of their paid API which includes their forecast data.

Once you have an Electricity Maps API key, you must set the ELECTRICITY_MAPS_API_TOKEN and ELECTRICITY_MAPS_API_URL environment variables. This allows the Grid Intensity CLI to access the Electricity Maps API.

export ELECTRICITY_MAPS_API_TOKEN=your-token
export ELECTRICITY_MAPS_API_URL=https://api-access.electricitymaps.com/free-tier/

Required parameters

When using Electricity Maps, you will need to pass a supported location. You can get a list of all supported locations using the Electricity Maps API.

For example, running the command below will return data for Portugal.

grid-intensity --provider ElectricityMaps --location PT

# Returns

[
 {
  "emissions_type": "average",
  "metric_type": "absolute",
  "provider": "ElectricityMaps",
  "location": "PT",
  "units": "gCO2e per kWh",
  "valid_from": "2023-07-14T10:00:00Z",
  "valid_to": "2023-07-14T11:00:00Z",
  "value": 155
 }
]

UK Carbon Intensity API

National Grid ESO have developed a Regional Carbon Intensity forecast for the Great Britain electricity grid.

--provider CarbonIntensityOrgUK

Required parameters

The UK Carbon Intensity API integration supports only one area, --location=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 CarbonIntensityOrgUK  --location UK

# Returns

[
        {
                "emissions_type": "average",
                "metric_type": "absolute",
                "provider": "CarbonIntensityOrgUK",
                "location": "UK",
                "units": "gCO2e per kWh",
                "valid_from": "2022-08-19T07:00:00Z",
                "valid_to": "2022-08-19T07:30:00Z",
                "value": 201
        }
]