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

🙋

503 errors on the site endpoint

Due to the current method of testing pages to get the data transfer used as part of calculating emissions, the API is experiencing daily and lengthly downtime for calls to the site endpoint.

We're working on an alternative testing method, but there is no date for this being rolled out.

In the meantime, please use the data endpoint. You will need to get the number of bytes transferred for a page load yourself, but this provides an almost-instant response when passed the number of bytes transferred as part of a page load and the green hosting status of the site.

🙋

While we make this API available to use to increase awareness and understanding of sustainability on the web, we aren't currently able to guarantee support beyond this page, and these endpoints and the structure of the responses can change without notice.

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 the How does it work? part of our Website Carbon Calculator site.

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/.