Quickstart

This guide will walk you through making your first estimation with the EarthEmission API using a real-life example.

Prerequisites

• Sign up for Earth Emission and have your API key ready.
• Familiarity with curl or other ways of interacting with HTTP APIs.

Introduction to Emission Factors

Earth Emission API estimates how much greenhouse gasses your activities emit using validated conversion factors known as emission factors. An emission factor is a way to convert different human activities into greenhouse gases in terms of CO2 equivalent (CO2e), usually expressed in kilograms. EarthEmission can answer questions like:

How much CO2e is emitted taking the train from Paris to Berlin? How much CO2e is emitted spending $1,000 on soft drinks in the US? How much CO2e is emitted staying a night at a hotel in China?

Your First Estimate

Let's estimate the greenhouse gas emissions of an average UK household based on electricity consumption (4,200 kWh per year) using the emission factor for the activity electricity-energy_source_grid_mix. This factor represents the average emission for the electricity grid.

Use curl to make an API call:

• Replace API_KEY with your API key and run the command in your terminal.
• The API endpoint that's used to estimate how carbon intensive an activity is, is located at: https://beta4.api.EarthEmission.io/estimate An API call to this endpoint looks like the block below.

curl --request POST \
--url https://beta4.api.EarthEmission.io/estimate \
--header 'Authorization: Bearer API_KEY' \
--data '{
        "emission_factor": {
            "activity_id": "electricity-supply_grid-source_residual_mix",
            "data_version": "^6"
        },
        "parameters":
            {
            "energy": 4200,
            "energy_unit": "kWh"
            }
        }'

In this example, we provide the parameters argument for the calculations and they indicate that we'd like it to calculate the emissions for 4.200 kWh.

Response You should get a response from the API back that looks like this:

{
    "co2e": 4008,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ar4",
    "co2e_calculation_origin": "source",
    "emission_factor": {
        "name": "Electricity supplied from grid - residual mix",
        "activity_id": "electricity-supply_grid-source_residual_mix",
        "id": "eefd06c3-1c7a-447c-aaf5-fe958bfa470e",
        "access_type": "public",
        "source": "AIB",
        "source_dataset": "European Residual Mix",
        "year": 2022,
        "region": "RS",
        "category": "Electricity",
        "source_lca_activity": "electricity_generation",
        "data_quality_flags": [
            "partial_factor",
            "notable_methodological_variance"
        ]
    },
    "constituent_gases": {
        "co2e_total": 4008,
        "co2e_other": null,
        "co2": 4008,
        "ch4": null,
        "n2o": null
    },
    "activity_data": {
        "activity_value": 4200,
        "activity_unit": "kWh"
    },
    "audit_trail": "selector"
}

The API returns quite a few values but the most relevant values are co2e and co2e_unit, which together describe how much CO2e is emitted by the given activity. In this case, yearly energy consumption emits approximately 4381 kg of CO2e.

(Check out this table to see a description of every attribute in the response)

If you've made it this far you've made your first API call and seen the results in your terminal!

Next Steps

• Explore more emission factors in the EarthEmission Data Explorer.
• Dive into the API docs or in-depth knowledge on using the API.