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:
- Provide a few details on the activity that is emitting carbon
- The Carbon Interface API will use the most accurate estimation methodologies to compute the amount of C02 emitted
- 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": "7268a9b7-17e8-4c8d-acca-57059252afe9"
}
The above request returns JSON structured like this:
{
"data": {
"id": "6108d711-be04-4dc4-93f9-43d969fd5273",
"type": "estimate",
"attributes": {
"distance_value": 100.0,
"vehicle_make": "Toyota",
"vehicle_model": "Corolla",
"vehicle_year": 1993,
"vehicle_model_id": "7268a9b7-17e8-4c8d-acca-57059252afe9",
"distance_unit": "mi",
"estimated_at": "2021-01-10T15:24:32.568Z",
"carbon_g": 37029,
"carbon_lb": 81.64,
"carbon_kg": 37.03,
"carbon_mt": 0.04
}
}
}
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!"
}