From 8544e6f51306865c116805813a03272aa466503c Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:14:08 +0800 Subject: [PATCH 01/13] nav design tweak --- src/_includes/layouts/default.njk | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/_includes/layouts/default.njk b/src/_includes/layouts/default.njk index 5e7627a..1398e2a 100644 --- a/src/_includes/layouts/default.njk +++ b/src/_includes/layouts/default.njk @@ -107,7 +107,7 @@ {%- for entry in navPages %} {% if sectionTitle != entry.sectionTitle %} {% set sectionTitle = entry.sectionTitle %} -
  • +

  • {{ sectionTitle }}

    • {% endif %} @@ -175,4 +175,4 @@ {% analytics %} - \ No newline at end of file + From 328bb28238338855410c7052a96b90749273462c Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:14:31 +0800 Subject: [PATCH 02/13] reorder roadmap nav order --- src/docs/co2js/roadmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/co2js/roadmap.md b/src/docs/co2js/roadmap.md index 031445e..5026c34 100644 --- a/src/docs/co2js/roadmap.md +++ b/src/docs/co2js/roadmap.md @@ -4,7 +4,7 @@ description: This page contains links to different Github issues that track the eleventyNavigation: key: roadmap title: Roadmap - order: 6 + order: 3 --- # CO2.js - Roadmap From 2fe4f4487469ddf9c211c37dc2b8595b2493aea9 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:14:40 +0800 Subject: [PATCH 03/13] add electricity maps license --- src/docs/co2js/overview.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/docs/co2js/overview.md b/src/docs/co2js/overview.md index cb09364..0db77de 100644 --- a/src/docs/co2js/overview.md +++ b/src/docs/co2js/overview.md @@ -83,3 +83,14 @@ The code for CO2.js is licensed [Apache 2.0](https://github.com/thegreenwebfound The carbon intensity data from Ember is published under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa)) The marginal intensity data is published by the Green Web Foundation, under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa)) + +Electricity Maps Grid Intensity Data - The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must: + +- Attribute: Credit Electricity Maps as the source +- Share-Alike: Keep derivative works under the same license +- Keep open: Provide unrestricted versions if using DRM + +For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology +For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/ + +Data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) are available through Electricity Maps as a paid service. Users requiring this data should visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). From 8d4de3a9995909cef534f9786fd05c72024cb111 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:16:46 +0800 Subject: [PATCH 04/13] create functions section --- src/docs/co2js/functions/overview.md | 18 +++ src/docs/co2js/functions/perbyte-trace.md | 61 +++++++ src/docs/co2js/functions/perbyte.md | 37 +++++ src/docs/co2js/functions/pervisit-trace.md | 71 ++++++++ src/docs/co2js/functions/pervisit.md | 37 +++++ src/docs/co2js/methods.md | 180 --------------------- 6 files changed, 224 insertions(+), 180 deletions(-) create mode 100644 src/docs/co2js/functions/overview.md create mode 100644 src/docs/co2js/functions/perbyte-trace.md create mode 100644 src/docs/co2js/functions/perbyte.md create mode 100644 src/docs/co2js/functions/pervisit-trace.md create mode 100644 src/docs/co2js/functions/pervisit.md delete mode 100644 src/docs/co2js/methods.md diff --git a/src/docs/co2js/functions/overview.md b/src/docs/co2js/functions/overview.md new file mode 100644 index 0000000..ed69e12 --- /dev/null +++ b/src/docs/co2js/functions/overview.md @@ -0,0 +1,18 @@ +--- +title: Functions +description: This guide will show you how to use the different functions to calculate carbon emissions that are available in CO2.js. +eleventyNavigation: + key: functions-overview + title: Overview + sectionTitle: Functions + order: 5 +--- + +# Functions + +CO2.js exposes four functions that developers can use to return CO2 estimates. This guide will show you how to use the different methods to calculate carbon emissions, and give a brief explanation for each. + +- [`perByte`](/co2js/functions/perbyte/) +- [`perVisit`](/co2js/functions/pervisit/) +- [`perByteTrace`](/co2js/functions/perbyte-trace/) +- [`perVisitTrace`](/co2js/functions/pervisit-trace/) diff --git a/src/docs/co2js/functions/perbyte-trace.md b/src/docs/co2js/functions/perbyte-trace.md new file mode 100644 index 0000000..d5100f5 --- /dev/null +++ b/src/docs/co2js/functions/perbyte-trace.md @@ -0,0 +1,61 @@ +--- +title: Functions - perByteTrace +description: This guide will show you how to use the perByteTrace function to calculate carbon emissions that are available in CO2.js. +eleventyNavigation: + key: functions-perbyte-trace + title: perByteTrace + sectionTitle: Functions + order: 5.2 +--- + +# Functions - perByteTrace
    Sustainable Web Design Model only
    + +The `perByteTrace()` function is an extension of `perByte()` which allows for certain inputs to be adjusted. This allows for more accurate, scenario specific estimates to be produced using the Sustainable Web Design Model. + + + +## Accepted parameters + +The `perByteTrace()` function accepts the following parameters: + +- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. +- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. +- **options**: `object` Optional - A JavaScript object containing any Sustainable Web Design specific variables to be change. + +### The `options` parameter + +The `options` parameter can contain any of the following keys. These can be used to adjust the values used by the Sustainable Web Design Model's calculation. + +- `greenHostingFactor`
    Sustainable Web Design Model v4 only
    - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy, between 0 and 1. If the `green hosting` boolean above is set to `true` then the `greenHostingFactor` will always be `1`. +- `gridIntensity` Optional – an `object` that can contain the following keys: + - `device` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + - `dataCenter` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + - `networks` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + +Below is an example which shows both kinds of accepted inputs in use. + +```js +const options = { + gridIntensity: { + device: 565.629, // Here we have set the grid intensity at the device location using a number. + dataCenter: { country: "TWN" }, // Here we have set the data center grid intensity using a country code. + networks: 442, + }, +}; +``` + +## Result + +The `perByteTrace()` function returns an object with the following keys: + +- `co2` - A `number` representing the carbon emissions calculated in grams +- `green` - A `boolean` indicating whether the calculation was based on data being hosted in a green data center +- `variables` - An `object`` that details all the other variables used in the calculation. This object will include: + - `description` - A static `string` explaining what is being shown. + - `bytes` - A `number` showing the bytes that were passed into the function. + - `greenHostingFactor` Sustainable Web Design Model v4 only - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy. + - `gridIntensity` – an `object` that can contain the following keys: + - `device` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. + - `dataCenter` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. + - `networks` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. diff --git a/src/docs/co2js/functions/perbyte.md b/src/docs/co2js/functions/perbyte.md new file mode 100644 index 0000000..012ea1b --- /dev/null +++ b/src/docs/co2js/functions/perbyte.md @@ -0,0 +1,37 @@ +--- +title: Functions - perByte +description: This guide will show you how to use the perByte function to calculate carbon emissions that are available in CO2.js. +eleventyNavigation: + key: functions-perbyte + title: perByte + sectionTitle: Functions + order: 5.1 +--- + +# Functions - perByte() + +The `perByte()` function can be used with both the [OneByte and Sustainable Web Design Models](/co2js/models/). We recommend using this function, as it will return a CO2 value (in grams) for raw data transfer using a given model. It can be used for calculating emissions from websites, file uploads, streaming etc. + + + +```js +import { co2 } from "@tgwf/co2"; + +const oneByte = new co2({ model: "1byte" }); + +const emissions = oneByte.perByte(1000000); +``` + +Here we are using the OneByte model, and using the `perByte()` function to check the carbon emissions for transferring 1 million bytes. + +## Accepted parameters + +The `perByte()` function accepts the following parameters: + +- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. +- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. + +## Result + +The `perByte()` function returns a floating point decimal value which is the amount of CO2e (in grams) calculated using the function. diff --git a/src/docs/co2js/functions/pervisit-trace.md b/src/docs/co2js/functions/pervisit-trace.md new file mode 100644 index 0000000..ebd7554 --- /dev/null +++ b/src/docs/co2js/functions/pervisit-trace.md @@ -0,0 +1,71 @@ +--- +title: Functions - perVisitTrace +description: This guide will show you how to use the perVisitTrace function to calculate carbon emissions that are available in CO2.js. +eleventyNavigation: + key: functions-pervisit-trace + title: perVisitTrace + sectionTitle: Functions + order: 5.4 +--- + +# Functions - perVisitTrace
    Sustainable Web Design only
    + +The `perVisitTrace()` function is an extension of `perVisit()` which allows for certain inputs to be adjusted. This allows for more accurate, scenario specific estimates to be produced using the Sustainable Web Design Model. + + + +## Accepted parameters + +The `perVisitTrace()` function accepts the following parameters: + +- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. +- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. +- **options**: `object` Optional - A JavaScript object containing any Sustainable Web Design specific variables to be change. + +### The `options` parameter + +The `options` parameter can contain any of the following keys. These can be used to adjust the values used by the Sustainable Web Design Model's calculation. + +- `dataReloadRatio` Optional – a `number` between 0 and 1 representing the percentage of data that is downloaded by return visitors. This is the complement of the data cache ratio from the Sustainable Web Design model, i.e. dataReloadRatio = 1 - dataCacheRatio. +- `firstVisitPercentage` Optional – a `number` between 0 and 1 representing the percentage of new visitors. +- `returnVisitPercentage` Optional – a `number` between 0 and 1 representing the percentage of returning visitors. +- `greenHostingFactor`
    Sustainable Web Design Model v4 only
    - The portion of hosting services powered by renewable or zero-carbon energy, between 0 and 1. If the `green hosting` boolean above is set to `true` then the `greenHostingFactor` will always be `1`. +- `gridIntensity` Optional – an `object` that can contain the following keys: + - `device` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + - `dataCenter` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + - `networks` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. + +Below is an example which shows both kinds of accepted inputs in use. + +```js +const options = { + dataReloadRatio: 0.6, + firstVisitPercentage: 0.9, + returnVisitPercentage: 0.1, + gridIntensity: { + device: 565.629, // Here we have set the grid intensity at the device location using a number. + dataCenter: { country: "TWN" }, // Here we have set the data center grid intensity using a country code. + networks: 442, + }, +}; +``` + +## Result + +The `perVisitTrace()` function returns an object with the following keys: + +- `co2` - A `number` representing the carbon emissions calculated in grams +- `green` - A `boolean` indicating whether the calculation was based on data being hosted in a green data center +- `variables` - An `object`` that details all the other variables used in the calculation. This object will include: + - `description` - A static `string` explaining what is being shown. + - `bytes` - A `number` showing the bytes that were passed into the function. + - `greenHostingFactor` Sustainable Web Design Model v4 only - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy. + - `gridIntensity` – an `object` that can contain the following keys: + - `device` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. + - `dataCenter` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. + - `networks` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. + - `production` - A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. + - `dataReloadRatio` – a `number` between 0 and 1 representing the percentage of data that is downloaded by return visitors. This is the complement of the data cache ratio from the Sustainable Web Design model, i.e. dataReloadRatio = 1 - dataCacheRatio. + - `firstVisitPercentage` – a `number` between 0 and 1 representing the percentage of new visitors. + - `returnVisitPercentage` – a `number` between 0 and 1 representing the percentage of returning visitors. diff --git a/src/docs/co2js/functions/pervisit.md b/src/docs/co2js/functions/pervisit.md new file mode 100644 index 0000000..b38230b --- /dev/null +++ b/src/docs/co2js/functions/pervisit.md @@ -0,0 +1,37 @@ +--- +title: Functions - perVisit +description: This guide will show you how to use the perVisit function to calculate carbon emissions that are available in CO2.js. +eleventyNavigation: + key: functions-pervisit + title: perVisit + sectionTitle: Functions + order: 5.3 +--- + +# Functions - perVisit
    Sustainable Web Design Model only
    + +The `perVisit()` function can only be used with the Sustainable Web Design Models. This function includes assumptions the model authors have made [about website visitors and caching](https://sustainablewebdesign.org/calculating-digital-emissions/#:~:text=Returning%20visitors%20are%20assumed%20to%20be%2025%25%2C%20loading%202%25%20of%20data.) as part its calculation. For that reason, we recommend only using it if you are comfortable with those assumptions. The `perVisit()` function is best used for calculating website carbon emissions. + + + +```js +import { co2 } from "@tgwf/co2"; + +const swd = new co2({ model: "swd" }); + +const emissions = swd.perVisit(1000000); +``` + +Here we are using the Sustainable Web Design Model, and using the `perVisit()` function to check the carbon emissions for transferring 1 million bytes. + +### Accepted parameters + +The `perVisit()` function accepts the following parameters: + +- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. +- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. + +## Result + +The `perVisit()` function returns a floating point decimal value which is the amount of CO2e (in grams) calculated using the function. diff --git a/src/docs/co2js/methods.md b/src/docs/co2js/methods.md deleted file mode 100644 index 34e734d..0000000 --- a/src/docs/co2js/methods.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Methods -description: This guide will show you how to use the different methods to calculate carbon emissions that are available in CO2.js. -eleventyNavigation: - key: methods - title: Methods - order: 4 ---- - -# Methods - -CO2.js exposes two functions that developers can use to return CO2 estimates. This guide will show you how to use the different methods to calculate carbon emissions, and give a brief explanation for each. - -{% include 'partials/swdmv4-update.njk' %} - -## perByte() - -The `perByte()` function can be used with both the [OneByte and Sustainable Web Design Models](/co2js/models/). We recommend using this function, as it will return a CO2 value (in grams) for raw data transfer using a given model. It can be used for calculating emissions from websites, file uploads, streaming etc. - - - -```js -import { co2 } from "@tgwf/co2"; - -const oneByte = new co2({ model: "1byte" }); - -const emissions = oneByte.perByte(1000000); -``` - -Here we are using the OneByte model, and using the `perByte()` function to check the carbon emissions for transferring 1 million bytes. - -### Accepted parameters - -The `perByte()` function accepts the following parameters: - -- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. -- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. - -### Result - -The `perByte()` function returns a floating point decimal value which is the amount of CO2e (in grams) calculated using the function. - -## perByteTrace
    Sustainable Web Design Model only
    - -The `perByteTrace()` function is an extension of `perByte()` which allows for certain inputs to be adjusted. This allows for more accurate, scenario specific estimates to be produced using the Sustainable Web Design Model. - - - -### Accepted parameters - -The `perByteTrace()` function accepts the following parameters: - -- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. -- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. -- **options**: `object` Optional - A JavaScript object containing any Sustainable Web Design specific variables to be change. - -#### The `options` parameter - -The `options` parameter can contain any of the following keys. These can be used to adjust the values used by the Sustainable Web Design Model's calculation. - -- `greenHostingFactor`
    Sustainable Web Design Model v4 only
    - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy, between 0 and 1. If the `green hosting` boolean above is set to `true` then the `greenHostingFactor` will always be `1`. -- `gridIntensity` Optional – an `object` that can contain the following keys: - - `device` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - - `dataCenter` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - - `networks` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - -Below is an example which shows both kinds of accepted inputs in use. - -```js -const options = { - gridIntensity: { - device: 565.629, // Here we have set the grid intensity at the device location using a number. - dataCenter: { country: "TWN" }, // Here we have set the data center grid intensity using a country code. - networks: 442, - }, -}; -``` - -### Result - -The `perByteTrace()` function returns an object with the following keys: - -- `co2` - A `number` representing the carbon emissions calculated in grams -- `green` - A `boolean` indicating whether the calculation was based on data being hosted in a green data center -- `variables` - An `object`` that details all the other variables used in the calculation. This object will include: - - `description` - A static `string` explaining what is being shown. - - `bytes` - A `number` showing the bytes that were passed into the function. - - `greenHostingFactor` Sustainable Web Design Model v4 only - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy. - - `gridIntensity` – an `object` that can contain the following keys: - - `device` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. - - `dataCenter` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. - - `networks` – A `number` representing the carbon intensity (in grams per kilowatt-hour) used in the calculation. - -## perVisit
    Sustainable Web Design Model only
    - -The `perVisit()` function can only be used with the Sustainable Web Design Models. This function includes assumptions the model authors have made [about website visitors and caching](https://sustainablewebdesign.org/calculating-digital-emissions/#:~:text=Returning%20visitors%20are%20assumed%20to%20be%2025%25%2C%20loading%202%25%20of%20data.) as part its calculation. For that reason, we recommend only using it if you are comfortable with those assumptions. The `perVisit()` function is best used for calculating website carbon emissions. - - - -```js -import { co2 } from "@tgwf/co2"; - -const swd = new co2({ model: "swd" }); - -const emissions = swd.perVisit(1000000); -``` - -Here we are using the Sustainable Web Design Model, and using the `perVisit()` function to check the carbon emissions for transferring 1 million bytes. - -### Accepted parameters - -The `perVisit()` function accepts the following parameters: - -- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. -- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. - -## perVisitTrace
    Sustainable Web Design only
    - -The `perVisitTrace()` function is an extension of `perVisit()` which allows for certain inputs to be adjusted. This allows for more accurate, scenario specific estimates to be produced using the Sustainable Web Design Model. - - - -### Accepted parameters - -The `perVisitTrace()` function accepts the following parameters: - -- **bytes** `number`
    Required
    : The value of bytes to estimate emissions for. -- **green hosting** `boolean` Optional: if the data being measured is served from a green web host. -- **options**: `object` Optional - A JavaScript object containing any Sustainable Web Design specific variables to be change. - -#### The `options` parameter - -The `options` parameter can contain any of the following keys. These can be used to adjust the values used by the Sustainable Web Design Model's calculation. - -- `dataReloadRatio` Optional – a `number` between 0 and 1 representing the percentage of data that is downloaded by return visitors. This is the complement of the data cache ratio from the Sustainable Web Design model, i.e. dataReloadRatio = 1 - dataCacheRatio. -- `firstVisitPercentage` Optional – a `number` between 0 and 1 representing the percentage of new visitors. -- `returnVisitPercentage` Optional – a `number` between 0 and 1 representing the percentage of returning visitors. -- `greenHostingFactor`
    Sustainable Web Design Model v4 only
    - The portion of hosting services powered by renewable or zero-carbon energy, between 0 and 1. If the `green hosting` boolean above is set to `true` then the `greenHostingFactor` will always be `1`. -- `gridIntensity` Optional – an `object` that can contain the following keys: - - `device` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - - `dataCenter` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - - `networks` Optional – A `number` representing the carbon intensity for the given segment (in grams per kilowatt-hour). Or, an `object`, which contains a key of country and a value that is an Alpha-3 ISO country code. - -Below is an example which shows both kinds of accepted inputs in use. - -```js -const options = { - dataReloadRatio: 0.6, - firstVisitPercentage: 0.9, - returnVisitPercentage: 0.1, - gridIntensity: { - device: 565.629, // Here we have set the grid intensity at the device location using a number. - dataCenter: { country: "TWN" }, // Here we have set the data center grid intensity using a country code. - networks: 442, - }, -}; -``` - -### Result - -The `perVisitTrace()` function returns an object with the following keys: - -- `co2` - A `number` representing the carbon emissions calculated in grams -- `green` - A `boolean` indicating whether the calculation was based on data being hosted in a green data center -- `variables` - An `object`` that details all the other variables used in the calculation. This object will include: - - `description` - A static `string` explaining what is being shown. - - `bytes` - A `number` showing the bytes that were passed into the function. - - `greenHostingFactor` Sustainable Web Design Model v4 only - A `number` representing the portion of hosting services powered by renewable or zero-carbon energy. - - `gridIntensity` – an `object` that can contain the following keys: - - `device` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. - - `dataCenter` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. - - `networks` – A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. - - `production` - A `number` representing the carbon intensity for this segment (in grams per kilowatt-hour) used in the calculation. - - `dataReloadRatio` – a `number` between 0 and 1 representing the percentage of data that is downloaded by return visitors. This is the complement of the data cache ratio from the Sustainable Web Design model, i.e. dataReloadRatio = 1 - dataCacheRatio. - - `firstVisitPercentage` – a `number` between 0 and 1 representing the percentage of new visitors. - - `returnVisitPercentage` – a `number` between 0 and 1 representing the percentage of returning visitors. From 1e7c54acc6ef332c0251d65961def7b758924799 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:17:14 +0800 Subject: [PATCH 05/13] create models section --- src/docs/co2js/models.md | 70 -------------------- src/docs/co2js/models/overview.md | 104 ++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 70 deletions(-) delete mode 100644 src/docs/co2js/models.md create mode 100644 src/docs/co2js/models/overview.md diff --git a/src/docs/co2js/models.md b/src/docs/co2js/models.md deleted file mode 100644 index b0a081c..0000000 --- a/src/docs/co2js/models.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Models -description: This guide will show you how use the different carbon estimation models available in CO2.js. -eleventyNavigation: - key: models - title: Models - order: 3 ---- - -# Models - -There are a few different models that can be used to measure digital carbon emissions. CO2.js includes two of these - the [OneByte][soberDigital] model, and the [Sustainable Web Design Model][swd]. This guide will show you how use the different carbon estimation models available in CO2.js. - -This guide will not go into the details of each model. If you'd like to learn more about the OneByte or Sustainable Web Design Models then take a look at [Methodologies for calculating website carbon](/co2js/explainer/methodologies-for-calculating-website-carbon/). - -## Using the Sustainable Web Design Model Default - v0.11.0 - -Since v0.11.0, CO2.js uses the Sustainable Web Design Model by default. After importing CO2.js into your project, you can start using this model right away by initiating a `co2()` object. Alternately, you can pass in the `model: "swd"` option. This will use [version 3 of the Sustainable Web Design Model](https://sustainablewebdesign.org/estimating-digital-emissions-version-3) by default. - -```js -import { co2 } from "@tgwf/co2"; - -const swd = new co2(); -// You can also explicitly declare the model -const declaredSwd = new co2({ model: "swd" }); -``` - -{% include 'partials/swdmv4-update.njk' %} - -### Using Sustainable Web Design Model version 3 - -You can explicitly set the Sustainable Web Design Model version 3 when initiating the a new instance of the `co2()` object. - -```js -import { co2 } from "@tgwf/co2"; - -const swdmV3 = new co2({ model: "swd", version: 3 }); -``` - -### Using Sustainable Web Design Model version 4 Since v0.16.0 - -In May 2024, version 4 of the Sustainable Web Design Model was published for initial community feedback. The update includes a change to the estimation formula, introduces separation between operational and embodied emissions, and updates the underlying data that forms the foundation of the model. We have covered the changes made in [this helpful blog post](https://www.thegreenwebfoundation.org/news/understanding-the-latest-sustainable-web-design-model-update/). - -CO2.js v0.16 sees the inclusion of Sustainable Web Design Model version 4 as one of the models that can be used in CO2.js. Developers will be required to explicitly opt-in to using Sustainable Web Design Model version 4, but will have access to all the same functions that can be accessed in version 3. Switching to version 4 should create minimal disruption for most developers, with only the returned values when using `perByteTrace` and `perVisitTrace` functions changing. - -The code sample below shows how to use SWDM version 4 in CO2.js to estimate 1000 bytes using the `perByte` function. Note that the version number has been explicitly declared (`version: 4`) when initiating a new `co2()` instance. - -```js -import { co2 } from "@tgwf/co2"; - -const swdmV4 = new co2({ model: "swd", version: 4 }); -const bytes = 1000; - -const estimate = version4.perByte(1000); -``` - -Learn more about the [different methods available when using the Sustainable Web Design Model](/co2js/methods/), including how to adjust variables used within the model. - -## Using the OneByte model - -If you want to use the OneByte model, then you'll need to let CO2.js know. This can be done by passing in a `model` parameter with a value of `"1byte"` when you initiate a new `co2()` object. - -```js -import { co2 } from "@tgwf/co2"; - -const oneByte = new co2({ model: "1byte" }); -``` - -[soberDigital]: https://theshiftproject.org/en/lean-ict-2/ -[swd]: https://sustainablewebdesign.org/estimating-digital-emissions diff --git a/src/docs/co2js/models/overview.md b/src/docs/co2js/models/overview.md new file mode 100644 index 0000000..303f2f3 --- /dev/null +++ b/src/docs/co2js/models/overview.md @@ -0,0 +1,104 @@ +--- +title: Models +description: This guide will show you how use the different carbon estimation models available in CO2.js. +eleventyNavigation: + key: models-overview + title: Overview + # parent: overview + sectionTitle: Estimation Models + order: 4 +--- + +# Models + +There are a few different models that can be used to measure digital carbon emissions. CO2.js includes two of these - the [OneByte][soberDigital] model, and the [Sustainable Web Design Model][swd]. This guide will show you how use the different carbon estimation models available in CO2.js. + +## Default estimation model + +CO2.js uses the **Sustainable Web Design (SWDM) Model version 4** as the default when calculating carbon emissions. + +## Carbon estimation models + +### The Sustainable Web Design Model + +After importing CO2.js into your project, you can start using this model right away by initiating a `co2()` object. Alternately, you can pass in the `model: "swd"` option. This will use [version 4 of the Sustainable Web Design Model](https://sustainablewebdesign.org/estimating-digital-emissions) by default. + +```js +import { co2 } from "@tgwf/co2"; + +const swd = new co2(); +// You can also explicitly declare the model +const declaredSwd = new co2({ model: "swd" }); +``` + +#### Using Sustainable Web Design Model version 3 + +By default, CO2.js will use the Sustainable Web Design Model version 4 calculations. To use Sustainable Web Design Model version 3, you can explicitly set it as the model version when initiating the a new instance of the `co2()` object. + +```js +import { co2 } from "@tgwf/co2"; + +const swdmV3 = new co2({ model: "swd", version: 3 }); +``` + +#### Explainer: How the SWDM works + +This model uses data transfer as an proxy indicator for total resource usage, and uses this number to extrapolate energy usage numbers for your application as a fraction of the energy used by the total system comprised of: + +1. the use-phase energy of datacentres serving content +2. the use-phase energy network transfering the data +3. the use-phase energy of user device an user is accessing content on +4. the total embodied energy used to create all of the above + +swd model + +It then converts these energy figures to carbon emissions, based on the carbon intensity of electricity from the [Ember annual global electricity review][Ember-annual-global-electricity-review]. + +The carbon intensity of electricity figures for the swd model include the the full lifecycle emissions including upstream methane, supply-chain and manufacturing emissions, and include all gases, converted into CO2 equivalent over a 100 year timescale. + +This follows the approach used by the IPCC 5th Assessment Report Annex 3 (2014), for the carbon intensity of electricity. + +[Ember's methodology notes][ember-methodology] detail where the rest of this data comes from in more detail, as well as any further assumptions made. + +### The OneByte model + + +Additionally, CO2.js also allows developers to use the OneByte model as introduced by The Shift Project in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital].If you want to use the OneByte model, then you'll need to let CO2.js know. This can be done by passing in a `model` parameter with a value of `"1byte"` when you initiate a new `co2()` object. + +```js +import { co2 } from "@tgwf/co2"; + +const oneByte = new co2({ model: "1byte" }); +``` + +This returns a number for the estimated CO2 emissions for the corresponding number of bytes sent over the wire, and has been used for video streaming, file downloads and websites. + +## How the models differ + +These models return slightly different results, since they apply different system boundaries as part of their calculations. Tom Greenwood has written [a terrific blog post](https://www.wholegraindigital.com/blog/website-energy-consumption/) explaining system boundaries and how they impact carbon estimates. + +The OneByte model, as it has been implemented in CO2.js, applies narrow system boundaries - datacenter and network only. It takes a top down approach to calculations, returning a single carbon emissions result based on a given input. It should be noted that the original model used in the Lean ICT report did have broader systems boundaries. However, when the model was included in CO2.js a judgement call was made to reduce its scope. You can read more about why in [this GitHub issue](https://github.com/thegreenwebfoundation/co2.js/issues/68). + +On the other hand, the Sustainable Web Design Model has a broader system boundary (explained above). It takes a more complex, but detailed, bottom up approach. By using a wider system boundary, the Sustainable Web Design Model provides a more comprehensive carbon estimate. This also means that segmented estimates can be produced for each part of the system, allowing for greater granularity and flexibility. + +## Switching between models + +To use the Sustainable Web Design Model in CO2.js, pass in the `{ model: 'swd' }` or `{ model: '1byte' }` parameter when initiating a new CO2.js object. + +```js +import { co2 } from "@tgwf/co2"; + +// Use the default Sustainable Web Design Model v4 +const swd = new co2(); + +// Use the OneByte model +const oneByte = new co2({ model: "1byte" }); + +// Use the Sustainable Web Design Model v3 +const swdmV3 = new co2({ model: "swd", version: 3 }); +``` + +[ember-methodology]: https://ember-climate.org/app/uploads/2022/03/GER22-Methodology.pdf +[Ember-annual-global-electricity-review]: https://ember-climate.org/insights/research/european-electricity-review-2022/ +[soberDigital]: https://theshiftproject.org/en/lean-ict-2/ +[swd]: https://sustainablewebdesign.org/calculating-digital-emissions From 14e671599f43dcd3891c56699e80302b813fa6da Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:17:29 +0800 Subject: [PATCH 06/13] create data section --- src/docs/co2js/data/average-intensity.md | 36 +++++++++ src/docs/co2js/data/electricity-maps.md | 25 ++++++ src/docs/co2js/data/marginal-intensity.md | 36 +++++++++ src/docs/co2js/{data.md => data/overview.md} | 51 ++++-------- ...dologies-for-calculating-website-carbon.md | 78 ------------------- 5 files changed, 110 insertions(+), 116 deletions(-) create mode 100644 src/docs/co2js/data/average-intensity.md create mode 100644 src/docs/co2js/data/electricity-maps.md create mode 100644 src/docs/co2js/data/marginal-intensity.md rename src/docs/co2js/{data.md => data/overview.md} (60%) delete mode 100644 src/docs/co2js/explainer/methodologies-for-calculating-website-carbon.md diff --git a/src/docs/co2js/data/average-intensity.md b/src/docs/co2js/data/average-intensity.md new file mode 100644 index 0000000..55cc942 --- /dev/null +++ b/src/docs/co2js/data/average-intensity.md @@ -0,0 +1,36 @@ +--- +title: Data - Average intensity +description: This guide will show you how find and use country-level grid intensity data available in CO2.js. +eleventyNavigation: + key: data-average-intensity + title: Average intensity + sectionTitle: Data + order: 6.2 +--- + +# Data - Average intensity + +You can import annual, country-level average grid intensity data from [Ember Climate](https://ember-climate.org/data/data-explorer/) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia in a project, then you can do so by using the code below: + +```js +import { averageIntensity } from '@tgwf/co2/data'; +const { data, type, year } = averageIntensity; + +const { AUS } = data; +console.log({ AUS }) +``` + +All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search). + +### Using CO2.js v0.16 and older + +If you are using CO2.js v0.16 or older in your code, then you should import data using the code sample below: + +```js +// Import data from CO2.js +import { marginalIntensity } from "@tgwf/co2" +``` + +## Licenses + +The carbon intensity data from Ember is published under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa)) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md new file mode 100644 index 0000000..1d8b111 --- /dev/null +++ b/src/docs/co2js/data/electricity-maps.md @@ -0,0 +1,25 @@ +--- +title: Data - Electricity Maps +description: This guide will show you how find and use country-level grid intensity data available in CO2.js. +eleventyNavigation: + key: data-electricity-maps + title: Electricity Maps + sectionTitle: Data + order: 6.1 +--- + +# Data - Electricity Maps + + +## Licenses + +Electricity Maps Grid Intensity Data - The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must: + +- Attribute: Credit Electricity Maps as the source +- Share-Alike: Keep derivative works under the same license +- Keep open: Provide unrestricted versions if using DRM + +For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology +For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/ + +Data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) are available through Electricity Maps as a paid service. Users requiring this data should visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). diff --git a/src/docs/co2js/data/marginal-intensity.md b/src/docs/co2js/data/marginal-intensity.md new file mode 100644 index 0000000..3c5391a --- /dev/null +++ b/src/docs/co2js/data/marginal-intensity.md @@ -0,0 +1,36 @@ +--- +title: Data - Marginal intensity +description: This guide will show you how find and use country-level grid intensity data available in CO2.js. +eleventyNavigation: + key: data-marginal-intensity + title: Marginal intensity + sectionTitle: Data + order: 6.3 +--- + +# Data - Marginal intensity + +You can import annual, country-level marginal grid intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change) into your projects directly from CO2.js. For example, if you wanted to use the marginal grid intensity for Australia in a project, then you can do so by using the code below: + +```js +import { marginalIntensity } from '@tgwf/co2/data'; +const { data, type, year } = marginalIntensity; + +const { AUS } = data; +console.log({ AUS }) +``` + +All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search). + +### Using CO2.js v0.16 and older + +If you are using CO2.js v0.16 or older in your code, then you should import data using the code sample below: + +```js +// Import data from CO2.js +import { marginalIntensity } from "@tgwf/co2" +``` + +## Licenses + +The marginal intensity data is published by the Green Web Foundation, under the Creative Commons ShareAlike Attribution Licence ([CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). ([What does this mean?](https://www.tldrlegal.com/license/creative-commons-attribution-share-alike-cc-sa)) diff --git a/src/docs/co2js/data.md b/src/docs/co2js/data/overview.md similarity index 60% rename from src/docs/co2js/data.md rename to src/docs/co2js/data/overview.md index 5d0ed57..18dbd97 100644 --- a/src/docs/co2js/data.md +++ b/src/docs/co2js/data/overview.md @@ -1,15 +1,16 @@ --- -title: Data +title: Data - Overview description: This guide will show you how find and use country-level grid intensity data available in CO2.js. eleventyNavigation: - key: data - title: Data - order: 5 + key: data-overview + title: Overview + sectionTitle: Data + order: 6 --- # Data -Sourcing carbon intensity data shouldn’t be the remit of developers. For that reason, CO2.js now includes yearly average grid intensity data from [Ember](https://ember-climate.org/data/data-explorer/), as well as marginal intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change). +Sourcing carbon intensity data shouldn’t be the remit of developers. For that reason, CO2.js now includes yearly average grid intensity data from [Electricity Maps](electricitymaps.com), [Ember](https://ember-climate.org/data/data-explorer/), as well as marginal intensity data from the [UNFCCC](https://unfccc.int/) (United Nations Framework Convention on Climate Change). ## Average and marginal intensity explained @@ -19,40 +20,14 @@ Marginal intensity, on the other hand, looks at where the additional electricity If you want to learn more about the differences between average or marginal grid intensity data, the team over at Electricity Maps have two great blog posts [explaining both concepts](https://electricitymaps.com/blog/marginal-emissions-what-they-are-and-when-to-use-them/) and why you [might use one over the other](https://electricitymaps.com/blog/marginal-vs-average-real-time-decision-making/). -## Where to find the data +## Using the data to your projects -The raw data files (in CSV) format, can be found in the `data` folder in the [CO2.js repository](https://github.com/thegreenwebfoundation/co2.js/tree/main/data). We have written a generation script that parses the raw data files, and outputs grid intensity data in unminified JSON and CommonJS formats. The generated output can be found in the `data/output` folder of the CO2.js repository. - -## Using emissions intensity data - -You can also import annual, country-level marginal or average grid intensity data into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia in a project, then you can do so by using the code below: - -```js -import { averageIntensity } from '@tgwf/co2/data'; -const { data, type, year } = averageIntensity; - -const { AUS } = data; -console.log({ AUS }) -``` +You can also import annual, country-level marginal or average grid intensity data into your projects directly from CO2.js. For code examples, see the specific pages for the data source you are using: -Likewise, if you want to use annual marginal intensity for Australia: +- [Electricity Maps](/co2js/data/electricity-maps/) +- [Ember (average intensity)](/co2js/data/average-intensity/) +- [UNFCC (marginal intensity)](/co2js/data/marginal-intensity/) -```js -import { marginalIntensity } from '@tgwf/co2/data'; -const { data, type, year } = marginalIntensity; +## Where to find the raw data -const { AUS } = data; -console.log({ AUS }) -``` - -All countries are represented by their respective [Alpha-3 ISO country code](https://www.iso.org/obp/ui/#search). - -### Using CO2.js v0.16 and older - -If you are using CO2.js v0.16 or older in your code, then you can import data using the code sample below: - -```js -// Import data from CO2.js -import { averageIntensity } from "@tgwf/co2" -import { marginalIntensity } from "@tgwf/co2" -``` +The raw data files (in CSV) format, can be found in the `data` folder in the [CO2.js repository](https://github.com/thegreenwebfoundation/co2.js/tree/main/data). We have written a generation script that parses the raw data files, and outputs grid intensity data in unminified JSON and CommonJS formats. The generated output can be found in the `data/output` folder of the CO2.js repository. diff --git a/src/docs/co2js/explainer/methodologies-for-calculating-website-carbon.md b/src/docs/co2js/explainer/methodologies-for-calculating-website-carbon.md deleted file mode 100644 index c4cf3ab..0000000 --- a/src/docs/co2js/explainer/methodologies-for-calculating-website-carbon.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Methodologies for calculating website carbon -description: CO2.js offers two models for understanding the environmental impact of compute - the OneByte model, and the Sustainable Web Design Model. -eleventyNavigation: - key: website-carbon-methodologies - # parent: overview - title: Methodologies for calculating website carbon - sectionTitle: Explanations - order: 30 ---- - -# {{ title }} - -CO2.js offers two models for understanding the environmental impact of compute - the OneByte model (`1byte.js`), and the Sustainable Web Design Model (`swd.js`). - -## Default - -Since v0.11.0, CO2.js uses the Sustainable Web Design (SWDM) model as the default when calculating carbon emissions. - -## Carbon estimation models - -### The Sustainable Web Design Model - -By default, CO2.js uses the [Sustainable Web Design Model][swd] for calculating emissions from digital services. As the name suggests, this has been designed for helping understand the environmental impact of websites. Further details are available on the [Sustainable Web Design website explaining the model](https://sustainablewebdesign.org/calculating-digital-emissions/), but for convenience, a short summary is below. - -#### How the SWDM works - -This model uses data transfer as an proxy indicator for total resource usage, and uses this number to extrapolate energy usage numbers for your application as a fraction of the energy used by the total system comprised of: - -1. the use-phase energy of datacentres serving content -2. the use-phase energy network transfering the data -3. the use-phase energy of user device an user is accessing content on -4. the total embodied energy used to create all of the above - -swd model - -It then converts these energy figures to carbon emissions, based on the carbon intensity of electricity from the [Ember annual global electricity review][Ember-annual-global-electricity-review]. - -The carbon intensity of electricity figures for the swd model include the the full lifecycle emissions including upstream methane, supply-chain and manufacturing emissions, and include all gases, converted into CO2 equivalent over a 100 year timescale. - -This follows the approach used by the IPCC 5th Assessment Report Annex 3 (2014), for the carbon intensity of electricity. - -[Ember's methodology notes][ember-methodology] detail where the rest of this data comes from in more detail, as well as any further assumptions made. - -### The OneByte model - -Additionally, CO2.js also allows developers to use the OneByte model as introduced by The Shift Project in their report on CO2 emissions from digital infrastructure, [Lean ICT: for a sober digital][soberDigital]. - -This returns a number for the estimated CO2 emissions for the corresponding number of bytes sent over the wire, and has been used for video streaming, file downloads and websites. - -### How the models differ - -These models return slightly different results, since they apply different system boundaries as part of their calculations. Tom Greenwood has written [a terrific blog post](https://www.wholegraindigital.com/blog/website-energy-consumption/) explaining system boundaries and how they impact carbon estimates. - -The OneByte model, as it has been implemented in CO2.js, applies narrow system boundaries - datacenter and network only. It takes a top down approach to calculations, returning a single carbon emissions result based on a given input. It should be noted that the original model used in the Lean ICT report did have broader systems boundaries. However, when the model was included in CO2.js a judgement call was made to reduce its scope. You can read more about why in [this GitHub issue](https://github.com/thegreenwebfoundation/co2.js/issues/68). - -On the other hand, the Sustainable Web Design Model has a broader system boundary (explained above). It takes a more complex, but detailed, bottom up approach. By using a wider system boundary, the Sustainable Web Design Model provides a more comprehensive carbon estimate. This also means that segmented estimates can be produced for each part of the system, allowing for greater granularity and flexibility. - -As a result, the `perByte` carbon estimates returned when using the OneByte model will be lower than those from Sustainable Web Design for the same amount of data transfer. - -## Switching between models - -To use the Sustainable Web Design Model in CO2.js, pass in the `{ model: 'swd' }` parameter when initiating a new CO2.js object. - -```js -import { co2 } from "@tgwf/co2"; - -// Use the default Sustainable Web Design Model -const swd = new co2(); - -// Use the OneByte model -const oneByte = new co2({ model: "1byte" }); -``` - -[ember-methodology]: https://ember-climate.org/app/uploads/2022/03/GER22-Methodology.pdf -[Ember-annual-global-electricity-review]: https://ember-climate.org/insights/research/european-electricity-review-2022/ -[soberDigital]: https://theshiftproject.org/en/lean-ict-2/ -[swd]: https://sustainablewebdesign.org/calculating-digital-emissions From da516c58fa53fde2fa5c3a2178c026472c9af949 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 14:17:35 +0800 Subject: [PATCH 07/13] add redirects --- public/_redirects | 3 +++ 1 file changed, 3 insertions(+) diff --git a/public/_redirects b/public/_redirects index 718072d..86379f4 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1,2 +1,5 @@ /carbon.txt / 404 /.well-known/carbon.txt / 404 +/co2js/explainer/methodologies-for-calculating-website-carbon/ /co2js/models/overview/ 301 +/co2js/methods/ /co2js/functions/overview/ 301 +/co2js/data/ /co2js/data/overview/ 301 From 306ea14b8807f9d5dcf1cd7ace21ae3dce190e66 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:11:31 +0800 Subject: [PATCH 08/13] update electricity maps docs --- src/docs/co2js/data/electricity-maps.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md index 1d8b111..e4da33f 100644 --- a/src/docs/co2js/data/electricity-maps.md +++ b/src/docs/co2js/data/electricity-maps.md @@ -10,10 +10,25 @@ eleventyNavigation: # Data - Electricity Maps +You can import annual, country-level average grid intensity data from [Electricity Maps](https://www.electricitymaps.com) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia for the year 2025 in a project, then you can do so by using the code below: + +```js +import { yearly2025 } from '@tgwf/co2/data/electricity-maps'; +const { data, methodology } = averageIntensity; + +const { AU } = data; +console.log({ AU }) +``` + +Data is available for: + +- All Electricity Maps zones (see the [full list of available zones](https://github.com/thegreenwebfoundation/co2.js/blob/main/data/fixtures/electricity-maps-zones.js)) +- The calendar years 2021, 2022, 2023, 2024, and 2025 + ## Licenses -Electricity Maps Grid Intensity Data - The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must: +The annual grid intensity data is republished from Electricity Maps under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/summary/). Users of this data through CO2.js must: - Attribute: Credit Electricity Maps as the source - Share-Alike: Keep derivative works under the same license From 04e2349448c9084c3ca0718cee90b614ef390a98 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:22:20 +0800 Subject: [PATCH 09/13] update electricity maps docs --- src/docs/co2js/data/electricity-maps.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md index e4da33f..c5af8c0 100644 --- a/src/docs/co2js/data/electricity-maps.md +++ b/src/docs/co2js/data/electricity-maps.md @@ -20,11 +20,17 @@ const { AU } = data; console.log({ AU }) ``` +Electricity Maps also provides information for some grid regions (for example CAISO in the United States, or Northern India). To access these regions, developers should use the appropriate zone ID for the region they wish to access. + Data is available for: - All Electricity Maps zones (see the [full list of available zones](https://github.com/thegreenwebfoundation/co2.js/blob/main/data/fixtures/electricity-maps-zones.js)) - The calendar years 2021, 2022, 2023, 2024, and 2025 +### Accessing other Electricity Maps data + +While we are able to provide annual grid data from Electricity Maps in CO2.js, users wishing to utilise data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) should contact Electricity Maps to access this data via their paid API. To do so, visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). + ## Licenses @@ -36,5 +42,3 @@ The annual grid intensity data is republished from Electricity Maps under the [O For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/ - -Data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) are available through Electricity Maps as a paid service. Users requiring this data should visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). From 3497c2c3dada4ccc0a695a31c817d975ea9aa447 Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:22:20 +0800 Subject: [PATCH 10/13] Update _redirects --- public/_redirects | 2 -- 1 file changed, 2 deletions(-) diff --git a/public/_redirects b/public/_redirects index 86379f4..a7035b4 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1,5 +1,3 @@ -/carbon.txt / 404 -/.well-known/carbon.txt / 404 /co2js/explainer/methodologies-for-calculating-website-carbon/ /co2js/models/overview/ 301 /co2js/methods/ /co2js/functions/overview/ 301 /co2js/data/ /co2js/data/overview/ 301 From bd6e03c2b159b795273564aa990165bee1206dca Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:46:16 +0800 Subject: [PATCH 11/13] fix hyperlinks --- src/docs/co2js/data/electricity-maps.md | 4 ++-- src/docs/co2js/overview.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md index c5af8c0..afac009 100644 --- a/src/docs/co2js/data/electricity-maps.md +++ b/src/docs/co2js/data/electricity-maps.md @@ -40,5 +40,5 @@ The annual grid intensity data is republished from Electricity Maps under the [O - Share-Alike: Keep derivative works under the same license - Keep open: Provide unrestricted versions if using DRM -For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology -For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/ +For full details on Electricity Maps methodology see: [https://www.electricitymaps.com/data/methodology](https://www.electricitymaps.com/data/methodology) +For full detail on the ODbL see: [https://opendatacommons.org/licenses/odbl/summary/](https://opendatacommons.org/licenses/odbl/summary/) diff --git a/src/docs/co2js/overview.md b/src/docs/co2js/overview.md index 0db77de..ef325c8 100644 --- a/src/docs/co2js/overview.md +++ b/src/docs/co2js/overview.md @@ -90,7 +90,7 @@ Electricity Maps Grid Intensity Data - The annual grid intensity data is republi - Share-Alike: Keep derivative works under the same license - Keep open: Provide unrestricted versions if using DRM -For full details on Electricity Maps methodology see: https://www.electricitymaps.com/data/methodology -For full detail on the ODbL see: https://opendatacommons.org/licenses/odbl/summary/ +For full details on Electricity Maps methodology see: [https://www.electricitymaps.com/data/methodology](https://www.electricitymaps.com/data/methodology) +For full detail on the ODbL see: [https://opendatacommons.org/licenses/odbl/summary/](https://opendatacommons.org/licenses/odbl/summary/) Data at higher-than-yearly resolution (e.g monthly, hourly etc.), or [other historical and forecasted datapoints](https://www.electricitymaps.com/data) are available through Electricity Maps as a paid service. Users requiring this data should visit the Electricity Maps website for [pricing and details](https://www.electricitymaps.com/pricing). From 294c2ef5f5164cd1c25536d9fe82e29a6d3cf09e Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:46:21 +0800 Subject: [PATCH 12/13] update demo --- src/docs/co2js/data/electricity-maps.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md index afac009..04d4321 100644 --- a/src/docs/co2js/data/electricity-maps.md +++ b/src/docs/co2js/data/electricity-maps.md @@ -10,14 +10,18 @@ eleventyNavigation: # Data - Electricity Maps -You can import annual, country-level average grid intensity data from [Electricity Maps](https://www.electricitymaps.com) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for Australia for the year 2025 in a project, then you can do so by using the code below: +You can import annual, country-level average grid intensity data from [Electricity Maps](https://www.electricitymaps.com) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for **Australia for all available years** in a project, then you can do so by using the code below: ```js -import { yearly2025 } from '@tgwf/co2/data/electricity-maps'; -const { data, methodology } = averageIntensity; +import { yearly2025, yearly2024, yearl2023, yearly2022, yearly2021 } from '@tgwf/co2/data/electricity-maps'; -const { AU } = data; -console.log({ AU }) +const data2025 = yearly2025.data["AU"] +const data2024 = yearly2024.data["AU"] +const data2023 = yearly2023.data["AU"] +const data2022 = yearly2022.data["AU"] +const data2021 = yearly2021.data["AU"] + +console.log({ data2025, data2024, data2023, data2022, data2021 }) ``` Electricity Maps also provides information for some grid regions (for example CAISO in the United States, or Northern India). To access these regions, developers should use the appropriate zone ID for the region they wish to access. From 310fe3ed03ebaf60410f85b97af95eaa7da850df Mon Sep 17 00:00:00 2001 From: fershad <27988517+fershad@users.noreply.github.com> Date: Fri, 6 Feb 2026 18:05:19 +0800 Subject: [PATCH 13/13] very tiny typo --- src/docs/co2js/data/electricity-maps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/co2js/data/electricity-maps.md b/src/docs/co2js/data/electricity-maps.md index 04d4321..9aca13e 100644 --- a/src/docs/co2js/data/electricity-maps.md +++ b/src/docs/co2js/data/electricity-maps.md @@ -13,7 +13,7 @@ eleventyNavigation: You can import annual, country-level average grid intensity data from [Electricity Maps](https://www.electricitymaps.com) into your projects directly from CO2.js. For example, if you wanted to use the average grid intensity for **Australia for all available years** in a project, then you can do so by using the code below: ```js -import { yearly2025, yearly2024, yearl2023, yearly2022, yearly2021 } from '@tgwf/co2/data/electricity-maps'; +import { yearly2025, yearly2024, yearly2023, yearly2022, yearly2021 } from '@tgwf/co2/data/electricity-maps'; const data2025 = yearly2025.data["AU"] const data2024 = yearly2024.data["AU"]