Electricity Estimate Tutorial

The electricity emissions tutorial will show you how to integrate the Carbon Interface API into your apps to obtain emissions estimates for electricity generation.. This tutorial has been created from examples provided in the API docs.

Authentication

API Key

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.

Testing your API Key

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.

Generating an estimate

Selecting your country and state

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 electricty. 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"

Selecting your electricity inputs

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 defailt, 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"

Making your request

With all the paramteres 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",
      "electricty_value": 42,
      "country": "us",
      "state": "fl"
    }

Handling the response

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.

Next steps

API Docs

For more information on how the Carbon Interface API works, visit out developer documentation.

Community

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.

Feedback

If you have ideas to improve this tutorial, please let us know at [email protected].