Website Carbon API

👷// Documentation in progress|

How is your website impacting the planet?

The internet consumes a lot of electricity. 416.2TWh per year to be precise. To give you some perspective, that’s more than the entire United Kingdom.

From data centres to transmission networks to the devices that we hold in our hands, it is all consuming electricity, and in turn producing carbon emissions.

For more information about how we calculate the carbon emissions take a look at the How does it work? part of our Website Carbon Calculator site.

Public Endpoints

🙋

We're making some changes to the API behind the scenes, so these endpoints and their responses are subject to change.

If you're utilising the API please let us know via websitecarbon@wholegraindigital.com so we can keep you in the loop with any changes that might impact your work.

(We'd also love to hear what you're cooking up with it!)

The Site Endpoint: /site

/site?url={xxx}

This endpoint requires a URL parameter and will run a test in real time to calculate the carbon emissions generated per page view.

This endpoint is cached and will only test the same URL once every 24 hours.

Accepted Parameters

url as a string that is required

The URL of the page you want to test.

The URL should have the protocol included, and be URL encoded.

Successful Response

url as a string

The URL that has been tested.

In some cases this may differ from the URL you've provided, e.g. in the case of a redirect, or if it contains disallowed parameters.

green as a boolen or string "unknown"

Whether or not we could establish hosting of the website as being "green".

We work with The Green Web Foundation to get this information.

If the green hosting status can't be established this will return a string with a value of unknown.

bytes as an integer

The number of bytes transferred during the page load.

cleanerThan as a number

A numeric value between 0 and 1 representing the percentage of tested resources this is cleaner than.

This is based on the CO2 value. See the co2 property of the Statistics object.

statistics as an object

See The Statistics Object.

Example Valid Request

https://api.websitecarbon.com/site?url=https%3A%2F%2Fwww.wholegraindigital.com%2F

Example Successful Response

{
    "url": "https://www.wholegraindigital.com/",
    "green": true,
    "bytes": 443854,
    "cleanerThan": 0.83,
    "statistics": {
        "adjustedBytes": 335109.77,
        "energy": 0.0005633320052642376,
        "co2": {
            "grid": {
                "grams": 0.26758270250051286,
                "litres": 0.14882949913078525
            },
            "renewable": {
                "grams": 0.24250694721722435,
                "litres": 0.13488236404222018
            }
        }
    }
}

The Data Endpoint: /data

/data?bytes={0000000}&green={1/0}

An endpoint to calculate the emissions of a page by manually passing the bytes and whether or not it is powered by green hosting.

Accepted Parameters

bytes as an integer that is required

The number of bytes transferred by the page on load.

green as an integer that is required

Whether the site is using environmentally sustainable hosting.

This should be either 1 (if it is using green hosting) or 0 (if it is not using green hosting).

legacy as an integer

A flag to attempt to use calculations based on an outdated methodology.

Currently the only valid value for this is 2, relating to the methodology and calculations being used up to 19 April 2022.

Details about the current methodology can be found in in the How does it work? part of our Website Carbon Calculator site.

If you'd like more information about the legacy methodologies and our support for them, send us a message to websitecarbon@wholegraindigital.com.

Successful Response

cleanerThan as a number

A numeric value between 0 and 1 representing the percentage of tested resources this is cleaner than.

This is based on the CO2 value. See the co2 property of the Statistics object.

statistics as an object

See The Statistics Object.

Example Valid Request

https://api.websitecarbon.com/data?bytes=1000&green=1

Example Successful Response

{
    "statistics": {
        "adjustedBytes": 755,
        "energy": 0.0000012691831216216086,
        "co2": {
            "grid": {
                "grams": 0.000602861982770264,
                "litres": 0.0003353118348168209
            },
            "renewable": {
                "grams": 0.0005463664791062474,
                "litres": 0.0003038890356788948
            }
        }
    },
    "cleanerThan": 1
}

The Statistics Object

The statistics object returned as part of some responses is a result of the calculations performed by the API.

You can find out more about these calculations in the How does it work? part of our Website Carbon Calculator site.

adjustedBytes as a number

The approximate number of bytes transferred by the page load, adjusted to take first time vs returning visitor percentage into account.

energy as a number

The approximate amount of energy transferred on each page load in KWg.

co2 as an object

An object containing data on the amount of CO2 transferred on each page load.

This is often offered as two separate options, renewable and grid. These relate to whether the energy is renewable or from the national grid respectively; you should use one or the other.

The value of both the renewable and grid options is an object:

grams as a number

The approximate amount of CO2 transferred on each page load in grams

litres as a number

The approximate amount of CO2 transferred on each page load in litres

The Website Carbon Calculator

This API powers https://www.websitecarbon.com/.