IP to CO2 Intensity API

The IP to CO2 Intensity API allows you to query an IP address, and return the average annual grid intensity based on its real-world location.

Request method

Use the GET method for this request.

Endpoint

The request should be sent to https://api.thegreenwebfoundation.org/api/v3/ip-to-co2intensity/{ip_address}.

The {ip_address} parameter should be replaced with the IP address you want to query for.

Parameters

{ip_address}

A public IPv4 or IPv6 address should be passed to the endpoint. IP ranges are not accepted by this endpoint.

• 35.187.144.0 Accepted IPv4 address
• 2600:1900:4050:: Accepted IPv6 address
• 35.187.144.0/20 Incorrect
• 2600:1900:4050::/44 Incorrect

Sample request

fetch("https://api.thegreenwebfoundation.org/api/v3/ip-to-co2intensity/35.187.144.0", {
  method: "GET",
}).then((response) => response.json());

curl -X 'GET' \
 'https://api.thegreenwebfoundation.org/api/v3/ip-to-co2intensity/35.187.144.0' \
 -H 'accept: application/json'

{
  "country_name": "Taiwan (Province of China)",
  "country_code_iso_2": "TW",
  "country_code_iso_3": "TWN",
  "carbon_intensity_type": "avg",
  "carbon_intensity": 565.629,
  "generation_from_fossil": 82.84,
  "year": 2021,
  "checked_ip": "35.187.144.0"
}

Response object

The response is returned as a JSON object. When the IP being queried cannot be found, the World average intensity data is returned.

{
    "country_name": string,
    "country_code_iso_2": string - ISO 3166 Alpha-2 country code,
    "country_code_iso_3": string - ISO 3166 Alpha-3 country code,
    "carbon_intensity_type": string,
    "carbon_intensity": number,
    "generation_from_fossil": number,
    "year": number,
    "checked_ip": string
}

About the response data

Carbon Intensity

The carbon_intensity data returned by the endpoint is provided by Ember. The figures returned are annual, average amounts presenting the grams per kilowatt-hour (g/kWh).

What is average intensity?

Average emissions intensity uses the fuel mix of the entire electricity grid and can be used to derive estimates for the carbon footprint of a digital product or service. You’ll see average intensity used in the majority of carbon reporting standards and tooling. This makes it useful if you were to use CO2.js to feed in data to other carbon reporting tools.

How is it different from marginal intensity?

Marginal intensity, on the other hand, looks at where the additional electricity to power a device, product or service would come from. In almost all cases it would be from a fossil-fuel power source, and so marginal intensity figures tend to be higher than average intensity figures. The Green Software Foundation is one group that uses marginal intensity as part of its specification.

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 and why you might use one over the other.

Generation from Fossil

The generation_from_fossil figure represents the fraction of total annual electricity that was generated by fossil fuel sources. This data is also provided by Ember. Their methodologies for calculating generation and aggregates can be found on their website.

Year

The year returned represents the calendar year the data refers to. Since the dataset is updated yearly, in most cases this will show the previous calendar year.