NAV Navbar

Introduction

Welcome to the Carbon Interface API!

Carbon Interface is an API that makes it easy to perform C02 emissions estimates for common C02 emitting activities. The Carbon Interface API is based on JSON and easy to integrate using any programming language.

Carbon Interface makes it easy to get accurate carbon estimates:

  1. Provide a few details on the activity that is emitting carbon
  2. The Carbon Interface API will use the most accurate estimation methodologies to compute the amount of C02 emitted
  3. A JSON response will be returned for you to use in your app

Estimates are calculated by leading C02 emissions estimates methodologies from scientists around the world. View our methodology document for more information on how emissions estimates are calculated.

Authentication

To test your API key:

curl "https://www.carboninterface.com/api/v1/auth"
  -H "Authorization: Bearer API_KEY"

The above request returns JSON structured like this:

{
  "message": "auth successful"
}

Authentication is done via the API key which you can find in the developer portal. To make a request, the API key must be included as a bearer token in the authorization header.

Carbon Interface expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

Estimates

Electricity Emissions Estimate

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"
      }

The above request returns JSON structured like this:

{
  "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 electricity estimate endpoint will provide carbon emissions in grams, pounds, kilograms and tonnes. To create an electricity estimate, provide the following params:

Parameter Type Description
type string electricity
electricity_unit
optional		 string Can be either megawatt hours mwh or kilowatt hours kwh. If a unit is not provided, mwh is the default.
electricity_value decimal Value of the unit of electricity consumption or generation noted above.
country string The country param allows the API to ensure the emission factor per kilowatt hour or megawatt hour is reflective of the countries' emissions for electricity generation. Currently, Carbon Interface only supports Canada (ca) and the US (us).
state
optional		 string Proving the state will allow the API to generate a more accurate eletrcitiy emissions estimate. Emissions data from electricity generation from all Canadian provinces and US states is supported. The state param needs to be the two letter ISO state code.

Flight Emissions Estimate

curl "https://www.carboninterface.com/api/v1/estimates"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -X POST
  -d {
        "type": "flight",
        "passengers": 2,
        "legs": [
          {"departure_airport": "sfo", "destination_airport": "yyz"},
          {"departure_airport": "yyz", "destination_airport": "sfo"}
        ]
      }

The above request returns JSON structured like this:

{
  "data": {
    "id": "d60edacc-cf6c-4da7-b5de-c538de4ce5ee",
    "type": "estimate",
    "attributes": {
      "passengers": 2,
      "legs": [
        {
          "departure_airport": "SFO",
          "destination_airport": "YYZ"
        },
        {
          "departure_airport": "YYZ",
          "destination_airport": "SFO"
        }
      ],
      "estimated_at": "2020-07-24T02:25:50.837Z",
      "carbon_g": 1077098,
      "carbon_lb": 2374,
      "carbon_kg": 1077,
      "carbon_mt": 1
    }
  }
}

The flight estimate request will accept passenger flight details and compute the carbon emissions for the trip. To compute the carbon emissions of a round trip ensure the legs param includes both the departure flight and the return flight.

Parameter Type Description
type string flight
passengers integer Number of passengers you want the emissions estimate to be calculated for.
legs array array of legs objects - see below for more details on the legs object.

Legs JSON Object

Parameter Type Description
departure_airport string The departure airport IATA code.
destination_airport string The destination airport IATA code.
cabin_class
optional		 string The seating class that the passengers are taking for the leg. Allowable values are: economy and premium. If no value is provided for this param, economy will be set by default.

Shipping Emissions Estimate

curl "https://www.carboninterface.com/api/v1/estimates"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -X POST
  -d {
      "type": "shipping",
      "weight_value": 200,
      "weight_unit": "g",
      "distance_value": 2000,
      "distance_unit": "km",
      "transport_method": "truck"
    }

The above request returns JSON structured like this:

{
  "data": {
    "id": "4746e4ba-6605-4acc-802b-fd229a9503b4",
    "type": "estimate",
    "attributes": {
      "distance_value": "2000.0",
      "distance_unit": "km",
      "weight_value": "200.0",
      "weight_unit": "g",
      "transport_method": "truck",
      "estimated_at": "2020-07-31T13:00:04.446Z",
      "carbon_g": 25,
      "carbon_lb": 0.06,
      "carbon_kg": 0.03,
      "carbon_mt": 0.0
    }
  }
}

The shipping estimate request will accept shipment details and compute the carbon emissions for the shipment.

Parameter Type Description
type string shipping
weight_unit string The weight unit that is being used. This param can be set to grams (g), pounds (lb), kilograms (kg) or tonnes (mt).
weight_value decimal The weight value of the shipment in the unit of measurement set above in the weight_unit param.
distance_unit string The distance unit can be miles (m) or kilometers (km).
distance_value decimal The distance value is the distance the shipment has travelled in the unit of measurement set above in the distance_value param.
transport_method string The method the shipment is travelling. Values for this param can be ship, train, truck and plane.

Vehicle Emissions Estimate

curl "https://www.carboninterface.com/api/v1/estimates"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -X POST
  -d {
      "type": "vehicle",
      "distance_unit": "mi",
      "distance_value": 100,
      "vehicle_model_id": "17b83590-9500-4460-92cd-f8ffdcc20102"
    }

The above request returns JSON structured like this:

{
  "data": {
    "id": "30e81e0b-596b-40c0-b6dd-847954e60078",
    "type": "estimate",
    "attributes": {
      "vehicle_model_id": "17b83590-9500-4460-92cd-f8ffdcc20102",
      "distance_value": 100.0,
      "vehicle_make": "toyota",
      "vehicle_model": "corolla",
      "vehicle_year": 2017,
      "distance_unit": "mi",
      "estimated_at": "2020-11-14T06:03:22.752Z",
      "carbon_g": 28900,
      "carbon_lb": 63.71,
      "carbon_kg": 28.9,
      "carbon_mt": 0.03
    }
  }
}

The vehicle estimate request will accept the vehicle and trip details to compute the carbon emissions for the trip.

Parameter Type Description
type string vehicle
distance_unit string The distance unit that is being used. This param can be set to miles (mi) or kilometers (km).
distance_value decimal The distance of the trip in the units specified in the distance_unit param.
vehicle_model_id string The full model name of the vehicle.

Get a Specific Estimate

curl "https://www.carboninterface.com/api/v1/estimates/9b1e2132-6216-4c64-84b2-23cf31eb472d"
  -H "Authorization: Bearer API_KEY"

The above request returns JSON structured like this:

// Electricity Estimate Object
{
  "data": {
    "id": "2d968fce-859d-4dc2-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
    }
  }
}

// Flight Estimate Object
{
  "data": {
    "id": "9b1e2132-7216-4c64-84b2-23cf31eb472e",
    "type": "estimate",
    "attributes": {
      "passengers": 2,
      "legs": [
        {
          "departure_airport": "SFO",
          "destination_airport": "YYZ"
        },
        {
          "departure_airport": "YYZ",
          "destination_airport": "SFO"
        }
      ],
      "estimated_at": "2020-07-28T00:52:01.373Z",
      "carbon_g": 2140866,
      "carbon_lb": 4719.8,
      "carbon_kg": 2140.87,
      "carbon_mt": 2.14
    }
  }
}

// Shipping Estimate Object
{
  "data": {
    "id": "4746e4ba-6505-4acc-802b-fd229a9503b5",
    "type": "estimate",
    "attributes": {
      "distance_value": "2000.0",
      "distance_unit": "km",
      "weight_value": "200.0",
      "weight_unit": "g",
      "transport_method": "truck",
      "estimated_at": "2020-07-31T13:00:04.446Z",
      "carbon_g": 25,
      "carbon_lb": 0.06,
      "carbon_kg": 0.03,
      "carbon_mt": 0.0
    }
  }
}

// Vehicle Estimate Object
{
  "data": {
    "id": "30e81e0b-596b-40c0-b6dd-847954e60078",
    "type": "estimate",
    "attributes": {
      "distance_value": 100.0,
      "vehicle_make": "toyota",
      "vehicle_model": "corolla",
      "vehicle_year": 2017,
      "distance_unit": "mi",
      "estimated_at": "2020-11-14T06:03:22.752Z",
      "carbon_g": 28900,
      "carbon_lb": 63.71,
      "carbon_kg": 28.9,
      "carbon_mt": 0.03
    }
  }
}

This endpoint retrieves a specific Estimate. The JSON response will return the estimate object based on the type of estimate.

HTTP Request

GET https://www.carboninterface.com/api/v1/<ID>

URL Parameters

Parameter Description
ID The ID of the Estimate to retrieve

Vehicles

Vehicle Makes

curl "https://www.carboninterface.com/api/v1/vehicle_makes"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -X GET

The above request returns JSON structured like this:

[
  {
    "data": {
      "id": "4c1e16e1-7967-4394-b3cb-15f4577dffa1",
      "type": "vehicle_make",
      "attributes": {
          "name": "Ferrari",
          "number_of_models": 243
      }
    }
  },
  {
    "data": {
      "id": "c0d79b67-76e8-442d-b105-2c73501948a9",
      "type": "vehicle_make",
      "attributes": {
          "name": "Dodge",
          "number_of_models": 2608
      }
    }
  },
  {
    "data": {
      "id": "c983d62d-e823-4bfb-92a8-45d161be1fe1",
      "type": "vehicle_make",
      "attributes": {
          "name": "Subaru",
          "number_of_models": 924
      }
    }
  },
  {
    "data": {
      "id": "2b1d0cd5-59be-4010-83b3-b60c5e5342da",
      "type": "vehicle_make",
      "attributes": {
          "name": "Toyota",
          "number_of_models": 2162
      }
    }
  }
]

The Vehicle Makes endpoint will return an array of Vehicle Makes that can be queried for their specific Vehicle Models.

HTTP Request

GET https://www.carboninterface.com/api/v1/vehicle_makes

Vehicle Models

curl "https://www.carboninterface.com/api/v1/vehicle_makes/2b1d0cd5-59be-4010-83b3-b60c5e5342da/vehicle_models"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json"
  -X GET

The above request returns JSON structured like this:

[
  {
    "data": {
      "id": "7268a9b7-17e8-4c8d-acca-57059252afe9",
      "type": "vehicle_model",
      "attributes": {
          "name": "Corolla",
          "year": 1993,
          "vehicle_make": "Toyota"
      }
    }
  },
  {
    "data": {
      "id": "a2d97d19-14c0-4c60-870c-e734796e014e",
      "type": "vehicle_model",
      "attributes": {
          "name": "Camry",
          "year": 1993,
          "vehicle_make": "Toyota"
      }
    }
  },
  {
    "data": {
      "id": "14949244-b6d1-4a11-970f-73f75408f931",
      "type": "vehicle_model",
      "attributes": {
          "name": "Corolla Wagon",
          "year": 1993,
          "vehicle_make": "Toyota"
      }
    }
  }
]

The Vehicle Models endpoint accepts a single parameter in the url, vehicle_make_id and then returns all of the Vehicle Models that belong to the specified Vehicle Make. Once you identify the Vehicle Model you want to perform a vehicle estimate on, copy the id from the Vehicle Model and set that as the vehicle_model_id in the Vehicle estimate paramters.

HTTP Request

GET https://www.carboninterface.com/api/v1/vehicle_make/<vehicle_make_id>/vehicle_models

URL Parameters

Parameter Description
vehicle_make_id The ID of the Vehicle Make

Status Codes

The Carbon Interface API returns standard HTTP success or error status codes. For errors, the API will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes that might be returned are listed below.

Status Code Meaning
200 OK - Your request was successful
201 Created - Your estimate was created successfully.
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is invalid.
401 Unauthorized - Request Limit Reached -- You reached your monthly request limit.
401 Unauthorized - Invalid Subscription -- You don't have an active subscription.
403 Forbidden -- The estimate requested is hidden for administrators only.
404 Not Found -- The specified estimate could not be found.
422 Invalid Estimate Type -- Invalid estimate type provided in the request.
422 Unprocessable Entity -- Entity couldn't be created.
422 Unprocessable Entity -- Invalid Estimate Type -- Entity couldn't be created.
422 Unprocessable Entity -- Invalid Cabin Class -- Entity couldn't be created.
429 Too Many Requests -- You're making too many API requests!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Errors will be returned in the following JSON format

{
  "message": "I'm a helpful error message!"
}