The electricity emissions tutorial will show you how to integrate the Carbon Interface API into your apps to obtain CO2 emissions estimates for electricity generation. This tutorial has been created from examples provided in the API docs.
To generate emissions estimates from the Carbon Interface API, you need your API key. To get an API key, create a Carbon Interface account and copy your API key from the API Key section of your account into the authentication steps detailed below.
To test your API key, make a request to the /auth endpoint. Make sure to use Bearer authentication and replace API_KEY with the API key you copied from your account.
curl "https://www.carboninterface.com/api/v1/auth"
-H "Authorization: Bearer API_KEY"
If you receive a "message": "auth successful" response then your API key is valid and you can move forward with your integration. If you don't receive a "message": "auth successful" response, go back into your Carbon Interface account and ensure you are copying and pasting your API key correctly.
To generate an electricity emissions estimate you need to specify the region that you want an electricity emissions estimate from. Every region that Carbon Interface has emissions data on (US States and Canadian Provinces) emit different levels of emissions to generate electricity. Enter the two character state and country codes in the country and state attributes in your POST request.
In this example, we want to obtain an electricity generation emissions estimate for generating electricity in the US state of Florida. We are setting the country attribute to us and the state attribute to fl.
"country": "us",
"state": "fl"
To complete the body of the POST request to generate an electricity emissions estimate you need to specify the amount of electricity consumed and the unit. By default, electricity_unit is set to kwh. However, if you'd prefer to use mwh you can set that as the value of electricity_unit.
"electricity_value": 42,
"electricity_unit": "mwh"
With all the parameters of our POST request set, we're ready to generate our emissions estimate! The request needs to be made to https://www.carboninterface.com/api/v1/estimates in order to receive a response.
curl "https://www.carboninterface.com/api/v1/estimates"
-H "Authorization: Bearer API_KEY"
-H "Content-Type: application/json"
-X POST
-d {
"type": "electricity",
"electricity_unit": "mwh",
"electricity_value": 42,
"country": "us",
"state": "fl"
}
When you make a successful request to the estimates API you will receive a JSON response that includes the following:
{
"data": {
"id": "2d968fce-859d-4dc1-9489-987e795f42bb",
"type": "estimate",
"attributes": {
"country": "us",
"state": "fl",
"electricity_unit": "mwh",
"electricity_value": "42.0",
"estimated_at": "2020-07-24T02:23:24.441Z",
"carbon_g": 18051428,
"carbon_lb": 39796,
"carbon_kg": 18051,
"carbon_mt": 18
}
}
}
The response will include all of the original parameters that were sent in the request, in addition to id, estimated_at, carbon_g, carbon_lb, carbon_kg and carbon_mt that are all nested under the attributes key.
Now you can use the data in the response to display the emissions estimate to your users or include in other calculations.
For more information on how the Carbon Interface API works, visit out developer documentation.
The community of developers using Carbon Interface to generate emissions estimates is growing every day. Join our Discord Server to ask questions or provide feedback to the Carbon Interface team.
If you have ideas to improve this tutorial, please let us know at [email protected].