Quickstart

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

Prerequisites for following this tutorial

  • You will need to be signed up for Climatiq and have your API key handy. If you're not sure how to get one, click here.
  • You have tried out curl before or other ways of interacting with HTTP APIs. If you're not familiar with curl you might want to check out this tutorial, or perhaps consider exploring the data in excel first.

Climatiq provides an API to help you estimate how much greenhouse gasses your activities emit, based on validated conversion factors known as “emission factors.” An emission factor is a way to convert different human activities into greenhouse gases. It will take that human activity and estimate how much CO2 equivalent (abbreviated CO2e, usually expressed in kilograms), that activity will emit.

Different emission factors can help us answer questions like:

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

Climatiq has a wide variety of emission factors available, that you can browse in our Data Explorer, to get a feel for the sort of questions Climatiq can help you answer.

This guide will walk you through making your first API call with a real-life example.

Let's try to figure out how much greenhouse gas the average household emits based on how much electricity they use. The average UK household consumes 4.200 kWh of electricity every year - but if you have your power bill close, you can also use your own numbers.

Let's see how an API call like this could look using curl The API endpoint that's used to estimate how carbon intensive an activity is, is located at: https://beta3.api.climatiq.io/estimate

An API call to this endpoint looks like the block below. Don't worry if it looks confusing - we'll dive into each part afterwards.

curl --request POST \
--url https://beta3.api.climatiq.io/estimate \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"emission_factor": "electricity-energy_source_grid_mix",
"parameters":
{
"energy": 4200,
"energy_unit": "kWh"
}
}'

The request is an HTTP POST request, and the body of the request (named data above) is what we're telling Climatiq we'd like calculations for.

In our case, it's the "emission factor" called electricity-energy_source_grid_mix which is an emission factor that represents an "average" emission for the electricity grid. We then provide it with the calculations we'd like performed. These are called parameters, and we tell it that we'd like it to calculate the emissions for 4.200 kWh, which is the average household electricity usage.

Now you try! Run the command above in your terminal of choice, and make sure to insert your API key instead of where it says YOUR_API_KEY above.

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

{
"co2e": 3791.3652,
"co2e_unit": "kg",
"co2e_calculation_method": "ar4",
"co2e_calculation_origin": "source",
"emission_factor": {
"id": "electricity-energy_source_grid_mix",
"source": "EPA",
"year": "2022",
"region": "US-WY",
"category": "Electricity",
"lca_activity": "electricity_generation"
},
"constituent_gases": {
"co2e_total": 3791.3652,
"co2e_other": null,
"co2": 3763.7754,
"ch4": 0.4032,
"n2o": 0.0588
}
}

The API returns quite a few values (Check out this table to see a description of every attribute in the response), but the relevant values for us right now, are co2e and co2e_unit, which together describe how much CO2e is emitted by the given activity. In our case it tells us that the yearly energy consumption will emit approximately 3791 kg of CO2e.

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

But Climatiq can do much more than just calculate emissions based on electricity. If you're curious about what emission factors exist you can browse around in the Climatiq Data Explorer, where you can view all the different emission factors.

You can also jump straight to the API docs for some more in-depth knowledge about how to use the API.