Grid-aware Websites

[!CAUTION] > This repository is currently under active development. It is not advised that this code be used in any critical production systems.

Installing this library

You can install this library using NPM.

npm install @greenweb/grid-aware-websites

You can now import this library into a JavaScript project like this:

import { gridAwarePower } from "@greenweb/grid-aware-websites";

Working with this library

This library currently uses the Electricity Maps API to fetch current grid data for regions around the World.

We hope to add other data sources at a later time.

You will need to have an Electricity Maps API key in order to use this library. You will probably want to set this as a private environment variable in your project. You can obtain an API key here: https://api-portal.electricitymaps.com/

Using grid power breakdown

Alternately, you may choose to use the current power consumption breakdown of a regional grid to determine if grid-aware changes should be applied. With this approach, developers can specify if they wish to use data for all low-carbon energy (renewables + nuclear), or only renewable energy. The default mode is using only renewable energy.

A minimum threshold can also be specified. This is the minimum percentage of renewable/low-carbon energy being used by the grid. By default this value is set to 50 percent - meaning that at least 50% of the energy on the grid must come from renewables/low-carbon sources otherwise the gridAware: true flag will be returned.

import { gridAwarePower } from "@greenweb/grid-aware-websites";

const zone = "DE"; // The zone ID string or lat-lon object of the region you'd like to get grid intensity data for
const apiKey = "you_api_key";

const options = {
  mode: "renewables", // The energy data we want to use - either renewables or low-carbon. Default: renewables
  minimumPercentage: 95, // The minimum percentage of the choosen energy type before grid-awareness should be triggered. Default: 50
};

const gridData = await gridAwarePower(zone, apiKey, options);

The gridAwarePower() function will return either:

Success

{
    "status": "success",
    "gridAware": boolean, // A flag indicating if grid aware changes should be applied
    "region": "DE" // The country code of the region you'd like to get grid intensity data for
    "data": {
          "mode": "renewables", // The energy source being used
          "minimumPercentage": 95, // The minimum percentage for that energy source before grid-awareness is set to true,
          "renewablePercentage": number, // Only returned when mode === "renewables". Data from Electricity Maps for the current renewables percentage
        //   "lowCarbonPercentage": number, // Only returned when mode === "low-carbon". Data from Electricity Maps for the current low-carbon (renewables + nuclear) percentage,
        },
}

Error

{
    "status": "error",
    "message": "some error message",
    "details": {
        // ... an object with additional information about the error, if available.
    }
}

Using grid intensity data

You can choose to use grid intensity data to determine if grid-aware changes should be made. In this approach, the current grid intensity (fetched from Electricity Maps) is compared with the annual average grid intensity data (available in CO2.js). If the grid intensity is higher than the annual average, gridAware: true will be returned indicating that grid-aware changes should be applied. Otherwise gridAware: false will be returned.

import { gridAwareCO2e } from "grid-aware-websites";

const zone = "DE"; // The zone ID string or lat-lon object you'd like to get grid intensity data for
const apiKey = "your_api_key";

const options = {
  mode: "average", // The type of comparison used to determine grid-awareness - either average or limit. Default: average
  minimumIntensity: 400, // The minimum grid intensity value (grams CO2e/kWh) before grid-awareness is triggered. Default: 400
};

const gridData = await gridAwareCO2e(zone, apiKey, options);

The gridAwareCO2e() function will return either:

Success

{
    "status": "success",
    "gridAware": boolean, // A flag indicating if grid aware changes should be applied
    "region": "DE" // The country code of the region you'd like to get grid intensity data for
    "data" {
        "mode": "average", // The comparison method being used
        "carbonIntensity": number, // The current grid intensity fetched from Electricity Maps
        "averageIntensity": number // Only returned when mode === "average". The annual average grid intensity for the zone being checked taken from CO2.js
        // "minimumIntensity": 400 // Returned only when mode === "limit".
    }
}

Error

{
    "status": "error",
    "message": "some error message",
    "details": {
        // ... an object with additional information about the error, if available.
    }
}

Plugins

Plugins for Grid-aware Websites (gaw) provide platform/framework specific functionality that can aid developers in deploying and using this library.

This library can be used anywhere that runs server-side JavaScript and can make outbound fetch requests. Currently, we have limited documentation on how to use this project with:

Edge Functions

• Cloudflare Workers
• Netlify Edge Functions
• ... more to come

To do:

• Add some text explaining the project (or linking to an explainer).