Allow developers to access real-time grid intensity data through Electricity Maps

[fershad]

Currently, there is historical yearly average and marginal grid intensity data available in CO2.js. We would like to take this a step further by giving developers a way to use CO2.js to access real-time grid intensity data from Electricity Maps and CO2signal.

This would be done by effectively providing a wrapper function that calls the Electricity Maps or CO2signal API to fetch data. Developers would need to have their own API token for the service they wish to use.

Docs for both APIs can be found at the links below:

• https://docs.co2signal.com/#introduction
• https://static.electricitymaps.com/api/docs/index.html#introduction

[mrchrisadams]

Electricity Maps isn't the only provider of information like this, but they do seem to offer the broadest global coverage.

I found out recently that in Germany, one of the major grid operators is exposing realtime information over an API too, without charging.

You can see the map version below: https://co2map.the-nest.io

And the API docs are here: https://portal.traxes.io/co2intensity-dev/documentation/co2itensity

[fershad]

Add CO2 Signal API to CO2.js

[fershad]

Add Electricity Maps API to CO2.js

[mrchrisadams]

There is now an API for Germany (or at least the northern part of Germany covered by the 50hz grid)

https://eco2grid.50hertz.com/calculation

API details below:

https://api-portal.eco2grid.com/

[fershad]

Thinking through how an API for this might look.

Scope

Limiting the scope to just working with the ElectricityMaps API free tier. The paid tier generates unique base URLs for each subscriber, which would make implementation a bit more complicated. Possibly something for a later release.

Spec

We currently allow for the Sustainable Web Design model to be passed an object with adjusted values for grid intensity and other variables. This is done through the perVisitTrace and perByteTrace functions.

const bytesSent = 1000 * 1000 * 1000; // 1GB expressed in bytes
const greenHost = false; // Is the data transferred from a green host?
const options = {
  dataReloadRatio: 0.6,
  firstVisitPercentage: 0.9,
  returnVisitPercentage: 0.1,
  gridIntensity: {
    device: 565.629,
    dataCenter: { country: "TWN" },
    networks: 442,
  },
};

estimatedCO2 = co2Emission.perVisitTrace(bytesSent, greenHost, options);

For grid intensity, the user has the option to adjust grid intensity for the device, network, or data center segments. This can be done by either:

• Passing in a number representing the grid intensity in grams CO2e per kilowatt-hour.
• Passing in an object { country: <ISO Alpha 3 Country Code> }

To extend this to use the /carbon-intensity/latest endpoint from Electricity Maps, we could have the user pass in a different object with the following information:

{
    provider: "Electricity Maps", // required
    apiKey: "<YOUR_API_KEY_HERE>", // required
    zone: "<ISO Alpha 2 Country Code>"  // required
}

The zone should correspond to the Zones available in the Electricity Maps API for the tier provided. E.g. For the free tier, Zones are listed at: https://api-access.electricitymaps.com/free-tier/zones

With this, the example above would look like:

const bytesSent = 1000 * 1000 * 1000; // 1GB expressed in bytes
const greenHost = false; // Is the data transferred from a green host?
const options = {
  dataReloadRatio: 0.6,
  firstVisitPercentage: 0.9,
  returnVisitPercentage: 0.1,
  gridIntensity: {
    device: 565.629,
    dataCenter: {
        provider: "Electricity Maps",
        apiKey: "thisisafakeapikey",
        zone: "TW"
    },
    networks: 442,
  },
};

estimatedCO2 = co2Emission.perVisitTrace(bytesSent, greenHost, options);

With this, we can then make then make a fetch request to the https://api-access.electricitymaps.com/free-tier/carbon-intensity/latest endpoint to fetch the latest grid intensity for Taiwan & use that in the SWD calculations.

Consideration

• When used client-side (in the browser), the API key will be exposed in the request. We should be sure to document this & advise that this functionality is only used server-side.
• If the API request fails, what should be the fallback value?
  • Global average grid intensity is the safest bet.
  • Do we introduce ISO Alpha 2 country codes into the average grid intensity data we have? There's complexity around this fallback, as some Electricity Maps zones map to regions within a country. We'd need a way to reliably get the country code from the Electricity Maps zone name, which isn't trivial.
• How reusable is this approach for other models we might introduce later? It feels pretty robust, but is there anything that might have been missed?

[fershad]

After chatting with @rossf7 about this, based on his experience with thegreenwebfoundation/grid-intensity-go I'd like to make this a more modular approach.

This would separate the code logic for using an external data source from the CO2 calculation. In this way, we would also make it easier for folks to contribute other data sources (like the Germany one @mrchrisadams linked to above).

In this way developers can also use CO2.js as a means of connecting with an external data source, even if they don't want to use that data for a carbon calculations.

To make this possible, we'd have to create a new Class, which we can then expose to users. This can then be imported into a project.

[fershad]

Being worked on in https://github.com/thegreenwebfoundation/co2.js/tree/add-external-data-sources

Should have a PR ready for review in the next couple of days.