Emission API

Are you in the right place?

BigMile provides two kinds of API:

• Emission API
• Process API

This guide concerns the Emission API, not the Process API.

The Process API works by uploading a CSV/Excel file via API, this allows you to automate your uploading process for your Carbon Analytics (dashboarding & reporting environment. Link to Process API documenation

The Emission API is a web service, you can use this API to calculate Co2e transport emissions instantly by providing transport information about the shipment in an API request. Link to Emission API documentation

Type of requests

There are four types of requests our emission API supports:

Transport based emission calculations

Calculates the total emissions for transport legs based on the provided activity data (distance, fuel consumption, modality, etc.). No allocation of shipment emissions is performed.

Transport based emission allocation

Calculates the total emissions of transport legs based on the provided activity data (distance, fuel consumption, modality, etc.), with emissions being then allocated per shipment. To be ISO 14083/GLEC compliant, you will need to use the allocation request.

Location based emission calculation

Calculates the total emissions originating from a specific facility based on the provided activity data (fuel/electricity consumption, fuel type, mass transported, etc.). No allocation of shipment emissions is performed. Note that facility emissions only relate directly to shipment activity (e.g. cooling, forklift).

Location based emission allocation

Calculates the total emissions originating from a specific facility based on the provided activity data (fuel consumption, fuel type, mass transported, etc.), with emissions being then allocated per shipment. Note that facility emissions only relate directly to shipment activity (e.g. cooling, forklift). To be ISO 14083/GLEC compliant, you will need to use the allocation request.

Calculation type

Every request type supports two calculation methods. Depending on the data available, you can choose between a consumption-based or an intensity-based calculation.

Consumption based calculation

Uses fuel/electricity consumption as the primary basis for calculating emissions. Essential input data for this calculation consists of the actual fuel/electricity consumed, as well as the type of fuel used for each leg or facility.

Since consumption data is typically derived from operational sources, it is generally considered primary data. As a result, consumption based calculations usually provide more accurate emission estimates, although the principle of garbage in garbage out still applies.

Intensity based calculation

Uses mass and distance as the primary basis for calculating emissions. Essential input data for this calculation includes activity data such as the origin and destination of a trip, as well as the transported amount expressed in the relevant unit (e.g., kilograms). Then an internal GLEC intensity factor is used to estimate emissions.

Since intensity data relies on transport characteristics rather than actual fuel consumption, it is considered secondary data. As a result, emission estimates are typically less accurate than consumption based calculations. Due to GLEC intensity factors being more conservative, intensity based calculations may produce higher emission values than actually observed.

Why Consignment rather than Trips for Allocation?

The GLEC Framework allocates emissions at the consignment level rather than at the trip level. Therefore, emission requests using the allocation endpoint should always be constructed from a consignment perspective. Key data includes having a means of identifying individual consignments, the consignments (estimated) weight, as well as its origin and destination.

A transport trip often carries multiple consignments belonging to different customers. Calculating emissions solely at the trip level would assign the same emissions to all stakeholders, regardless of the weight or distance associated with their individual consignments. This could lead to an unfair distribution of responsibility.

Instead, ISO14083 allocates the total emissions of a round trip to individual consignments based on each consignment's share of the total direct tonne-kilometres (tkm). This approach ensures that each stakeholder is assigned emissions proportional to the transport service they actually used. Emissions resulting from empty running are automatically incorporated into the allocation.

Navigating BigMile API documentation

The API documentation page has an overview of necessary information, sources and examples for structuring your data and its expected output. BigMile Emission API

The API documentation page provides important information such as

1. the relevant location based or transport based emission;
2. and if they are calculation based and allocation based;
3. note that you can expand the calculations tab to find important fields;
4. and that these fields may also be expandable and contain required data

You can also find to the right of the page a request sample per request scenario, showing:

1. the http link used;
2. the content (data) type needed;
3. the selectable request scenarios;
4. and the associated scenarios example body;

API case builder

BigMile also offers a step-by-step case builder which assists you in mapping out the framework, vehicle type and calculation method. It can then also generate an example based on your build. Link to API case Builder

The case builder can be helpful for testing, especially In case you want to test non generic requests. If requests that more closely match your logistics, we recommend using the case builder to create the emission cases with different modalities, vehicle types etc.

if you’re looking for a list of acceptable vehicle categories, hub intensities or fuels, then please review the linked document found in the documentation section.

Postman

Postman is a API platform that can be used to view JSON files and test if the requests are functioning. Your organization probably uses a different program to execute the requests on a day-to-day basis.

Download Postman | Get Started for Free

API Key

In order to use the BigMile API, such as for using the example file, you will need to generate an API key, manually save it in a secure location on your device, and then past it into into the authorization value:

Generating a BigMile API Key:

1. Under Settings in BigMile :
2. Select Admin
3. Then select API (Link to API)
4. Then select Generate a new API key

Once you have manually saved the key in a secure location on your device, run Postman (and import the example file via the ‘⋯’ on the top left).

1. Under Authorization
2. Select API Key
3. Then paste your API key into the value field

If everything was done correctly, you should now be able to access our API calculation product

We also have a video that addresses the API Key process it the first half: BigMile KnowledgeHub - API Key

Note that the video goes on to explain our API Process, but for the purposes of inserting the API Key it is essentially the same for API calculation.

When should you make the API call?

When you kick off the API call is an important decision to make and depends on your use case, if you want to put the Co2e on a preliminary invoice for example you can execute the request before the transport takes place. However, generally it is best to only do the API request after you know the transport characteristics won’t change anymore, and if they do recalculate the emissions to match reality as closely as possible.

While many of the required fields require specific input, not all values need to be known with complete certainty. In many cases, estimates can be used. For example, if the exact fuel consumption for every transport leg in a given year is not available, an estimated quarterly or yearly average across all relevant legs can still be used to provide a reasonable estimate. Thus, clients have the flexibility to balance accuracy against practicality, with ISO 14083 even encouraging organizations to start with the data they have and continuously improve data quality over time.

Switching between environments

In case you also have our other BigMile products, such as our Carbon or NOx Analytics, then you can easily switch between environments by clicking your profile on the top right, then selecting ‘products’.