Flexport provides a Carbon Calculator API which allows you to measure emissions generated from shipments to help you understand the environmental impact of your business. The calculator is accredited by the Smart Freight Centre in conformance with the Global Logistics Emissions Council (GLEC) Framework.

Endpoints

POST /carbon_calculation

In order to get going, you’ll first need to give us a little bit of information. You’ll need to tell us about how you want to use our calculator so that we can set you up with access to our API and platform. We’ll set up an account and issue you an API token. This is the key that you will use to authenticate to our API.

You can also access our documentation for technical reference on how to call the API at https://apidocs.flexport.com/v3/tag/Carbon-Calculation. Be aware that we cap the number of requests to 1,000 per hour.

We take inputs about your shipments including weight, mode, and distance to calculate the emissions of a shipment. The full list of inputs can be found here, but we’ll cover some common examples in this tutorial.

Let’s make a simple call to the calculator:

curl -X POST "https://api.flexport.com/carbon_calculation" \
    -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
    -H 'content-type: application/json' \
    -H 'flexport-version: 3' \
    -d $'{
        "weight": {
            "_object": "/quantity/weight",
            "value": "1000.0",
            "unit": "kg"
        },
        "distance": {
            "_object": "/quantity/distance",
            "value": "1000.0",
            "unit": "km"
        },
        "transportation_mode": "air"
    }'

Notice the request is an HTTP POST to URL

https://api.flexport.com/carbon_calculation
using the familiar JSON HTTP headers. The data parameter contains several fields which are used in the calculation. The HTTP response to this call is:

{
    "_object": "/api/response",
    "self": "https://api.flexport.com/carbon_calculation",
    "version": 3,
    "data":{
        "_object": "/carbon_calculation",
        "co2e_emissions": {
            "value": 1.13,
            "unit": "t",
            "_object": "/quantity/weight"
        }
    }
}

The pertinent part of the response is contained in the co2e_emissions element. It contains a value field and a unit field which are 0.13 and t, respectively. The calculation has informed us that the equivalent of 0.13 tonnes of carbon dioxide equivalent (TCO₂e) were emitted in the hypothetical example.

Looking back at the original data in our example request, you might believe that it is lacking a bunch of information needed to make an accurate calculation. You would be correct. This example is very contrived. We’ll need to take a look at the data fields that the API provides before we go further.

So, what fields are available in the API? Here's the list, with explanations.

Requests to the Carbon Calculation API require the following information:

• Either weight or teus is required
• Either a distance object, or both an origin and destination object
• transportation_mode: The mode of transportation for calculation

Also notice that there are numerous conditional requirements for individual objects mentioned in the list above.

Let’s look at several examples to get a little more familiar with the API.

Example 1: Ocean Shipment from San Francisco to Oakland using city

Here’s a simple example to start. We’ll calculate the CO2-equivalent emissions for a shipment of two TEUs from one city to another.

JSON Request data

{
  "teus": "2",
  "transportation_mode": "ocean",
  "origin_address": {
    "city": "Shanghai",
    "country_code": "CN"
  },
  "destination_address": {
    "city": "San Francisco",
    "country_code": "US"
  }
}

JSON Response

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/carbon_calculation",
  "version": 3,
  "data": {
    "_object": "/carbon_calculation",
    "co2e_emissions": {
      "value": 1.67651,
      "unit": "t",
      "_object": "/quantity/weight"
    }
  },
  "error": null
}

Example 2: Truck last mile shipment from San Francisco to Oakland using zip code

This example is very specific in that the requestor only wishes to calculate CO2 emissions emitted during the truck’s last mile of travel. To do so, the transportation_mode element is set to truck, and more importantly, trucking_service_type is set to last_mile:

JSON Request data

{
  "weight": {
    "value": 2000,
    "unit": "kg"
  },
  "transportation_mode": "truck",
  "trucking_service_type": "last_mile",
  "origin_address": {
    "zip": "94607",
    "country_code": "US"
  },
  "destination_address": {
    "zip": "94102",
    "country_code": "US"
  }
}

JSON Response

{
  "_object": "/api/response",
  "self": "https://api.anycompany.com/carbon_calculation",
  "version": 3,
  "data": {
    "_object": "/carbon_calculation",
    "co2e_emissions": {
      "value": 0.02022,
      "unit": "t",
      "_object": "/quantity/weight"
    }
  },
  "error": null
}

Example 3: Air shipment using distance

Finally, we present a typical case where we’d like to calculate emissions via air transport. Besides the obvious weight and distance values, this request declares the transportation_mode as air:

JSON Request data

{
  "weight": {
    "value": 3000,
    "unit": "kg"
  },
  "distance": {
    "value": 3000,
    "unit": "km"
  },
  "transportation_mode": "air",
  "origin_address": {
    "country_code": "US"
  },
  "destination_address": {
    "country_code": "KR"
  }
}

JSON Response

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/carbon_calculation",
  "version": 3,
  "data": {
    "_object": "/carbon_calculation",
    "co2e_emissions": {
      "value": 6.3,
      "unit": "t",
      "_object": "/quantity/weight"
    }
  },
  "error": null
}

On occasion, things don’t always proceed as you expect. Naturally, various HTTP error codes, along with an exception JSON object, are returned to help you build your exception handling routines.

An example of an Error Response is shown below.

{
  "_object":"/api/error",
  "status":400,
  "code":"bad_request",
  "message":"Validation Error: `country_code` is required and must be in ISO3166-1 alpha-2 format for destination_address."
}

A status value of 400 typically denotes a logical error found in the JSON data included in your request. Here are some error messages you may receive, and actions to help you resolve those issues.

You may encounter problems with your calls to the API. Let’s take a look at some common errors.

• BadRequestError: Any one of the following messages will trigger a BadRequestError:
  • country_code is required and must be in ISO3166-1 alpha-2 format for origin_address.
  • country_code is required and must be in ISO3166-1 alpha-2 format for destination_address.
  • Must supply one of weight or teus.
  • Must supply distance or one of origin_coordinates, origin_address, or origin_port.
  • Must supply distance or one of destination_coordinates, destination_address, or destination_port.
• Error Status 429
  • Too many requests per hour, or, You’ve exceeded the hourly request limit of 1000 requests per hour. Try throttling the rate of your requests.

We’ve had a problem with our back end systems. Wait for a short period and resend your request.