Using Python To Interact With The EarthEmission Api

Interacting with the earthemission API using Python

As the earthemission API is an HTTP-based REST API, you can use it with almost every programming language in existence - Python included!

You should always refer to the API reference for comprehensive documentation about how the API works, but included below are a few code examples that will show you how to perform different tasks in Python

The snippets expect you to have the requests package installed to perform HTTP requests. See here for installation instructions.

You will also need a earthemission API key. See here if you're uncertain about how to get one.

Searching

This example will show you how to use the search endpoint to query for the emission factors related to the electricity grid mix in Australia.

# Change this to be your API key.
MY_API_KEY="INSERT YOUR API KEY HERE"
 
url = "https://beta4.api.earthemission.io/search"
query="grid mix"
data_version = "^3"
 
query_params = {
    # Free text query can be writen as the "query" parameter
    "query": query,
    "data_version": data_version,
    # You can also filter on region, year, source and more
    # "AU" is Australia
    "region": "AU"
}
 
# You must always specify your AUTH token in the "Authorization" header like this.
authorization_headers = {"Authorization": f"Bearer: {MY_API_KEY}"}
 
# This performs the request and returns the result as JSON
response = requests.get(url, params=query_params, headers=authorization_headers).json()
 
# And here you can do whatever you want with the results
print(response)

Estimating

This is an example of how to use the estimate endpoint with Python, making an estimate for the electricity grid mix in Australia.

# Change this to be your API key
MY_API_KEY="INSERT YOUR API KEY HERE"
 
url = "https://beta4.api.earthemission.io/estimate"
 
# The activity ID for the emission factor. You can find this via the search endpoint listed above
# or via the Data Explorer.
activity_id = "electricity-supply_grid-source_residual_mix"
 
# We have many regions with the same activity id, representing the power grid in different countries.
# We'd like to get the power for Australia specifically, so we will need to specify a region.
# We do this by specifying the UN location code for the region
# You can also see the region for different emission factors in the data explorer.
region = "AU"
 
# We provide a data version on which we want to base our calculation. The recommended approach
# is to use the latest version.
data_version = "^3"
 
# We must also specify how much electricity generation we would like to make the estimation for.
# In this case we will do it for 100 kilowatt-hours.
# Different emission factors have different requirement as to what units they support estimates for.
# You can see the units supported by an emission factor in the data explorer
# and find more documentation about units
# in the API documentation.
parameters = {
    "energy": 100,
    "energy_unit": "kWh"
}
 
json_body = {
    "emission_factor": {
        "activity_id": activity_id,
        "data_version": data_version,
        "region": region,
    },
    # Specify how much energy we're estimating for
    "parameters": parameters
}
 
# You must always specify your AUTH token in the "Authorization" header like this.
authorization_headers = {"Authorization": f"Bearer: {MY_API_KEY}"}
 
# We send a POST request to the estimate endpoint with a json body
# and the correct authorization headers.
# This line will send the request and retrieve the body as JSON.
response = requests.post(url, json=json_body, headers=authorization_headers).json()
 
# You can now do anything you want with the response
print(response)