This API is fully ISO-14083 compliant
If your are looking to migrate from the previous version, check out the Migration Guide. Need to access to the previous version? Check the documentation.
Table of Contents
This endpoint calculates CO₂ equivalent (CO₂e) emissions for a shipment that includes multiple transport chain elements, such as legs and hubs. It supports a variety of shipment types, from containers to parcels.
The response provides CO₂e emissions data at three levels:
- Total shipment emissions: overall CO₂e emissions of the shipment.
- Per order: breakdown of emissions for each individual order within the shipment.
- Per transport chain element: CO₂e emissions data segmented by each leg or hub of the route.
Request Configuration
Headers
x-api-key
: your unique API key, required for authenticationAccept-Version
: specifies the contract version.- Required for v2.1: set to
"2.1"
to access the latest version, which is ISO-compliant. ⚠️ If no Accept-Version header is provided, the API defaults to version 2.0, allowing existing integrations to work without modification.
Request Structure
Every request is formatted as a nested JSON object containing both required and optional properties that define the shipment's details. Here’s a breakdown:
Orders
orders
: defines each order within the shipment, with a maximum of 5 orders.
-
Required field:
type
: specifies the order type. Accepted values:FCL
LCL
parcel
bulk
breakbulk
nContainers
: number of containers. Required only when the order type isFCL
.weight
: total weight of the order (in kilograms). Required for all order types exceptFCL
.
-
Optional fields:
containerSizeTypeCode
: specifies the container size/type code (e.g.,20gp
). See the full list of accepted values here.
Transport Chain Elements
transportChainElements
: defines the shipment’s transport chain, with each item in the array representing either a leg
or a hub
.
-
Legs
- Required fields:
type
: must be set to"leg"
.from
andto
: specifies the origin and destination of the leg (can be a location,locode
,iata
, or coordinates).mode
: specifies transport mode (sea
,road
,rail
,air
,inland_water
).
- Optional fields:
distance
: useful if a custom distance is preferred to our calculated distance.details
: mode-specific details, such asfuelType
for road mode,vesselImo
for sea mode.- You can find all the possible fields in our request builder below
- Required fields:
-
Hubs
- Required fields:
type
: must be set to"hub"
.hubType
: specifies the type of hub, such aswarehouse
.
- Required fields:
Metadata
Can contain any information you want to add to your request, for example, to help you identify your shipment. You can pass any key-value pair.
Response Structure
The response includes CO₂e emissions data at various levels and details for each transport chain element.
Parameters
parameters
: reflects the submitted orders
.
- Fields:
orders
: array reflecting the structure of each submitted order, includingtype
,quantity
,weight
, andContainerSizeTypeCode
.
CO₂e Emissions
co2e
: provides total emissions values for the shipment.
- Fields:
total
: total CO₂e emissions (in grams).wtt
andttw
: emissions broken down by Well-to-Tank and Tank-to-Wheel (in grams).intensity
: CO₂e intensity (in kg CO₂e per ton-km).
Transport Chain Elements
transportChainElements
: array of objects that lists each transport element (leg
or hub
) in the sequence, including associated emissions data and properties.
- Legs:
- Fields:
type
:leg
.from
andto
: origin and destination, with fields likelocode
,iata
,coordinates
,city
,country
, andregion
.mode
: transport mode used (e.g.,sea
,road
,air
...).co2e
: emissions object with fields liketotal
,wtt
,ttw
, andintensity
.properties
: additional details such asdistance
,vessel
,fuelType
andmodel
. You can find out more about our models here
- Fields:
- Hubs:
- Fields:
type
:hub
.location
: object with location details, including fields likelocode
,coordinates
,city
,country
, andregion
.properties.hubType
: specifies the hub type, such aswarehouse
ormaritime_container_terminal
.source
: indicates the origin of the hub ("user_input"
or"auto_generated"
).co2e
: emissions object with fields liketotal
,wtt
, andttw
.
- Fields:
Metadata
Contains everything you passed in the input field metadata.
Support endpoints and resources
- Understand how
weight
andcontainerSizeTypeCode
impact calculations across all transport modes: visit our Weight and Container Guide. - Optimize calculation accuracy by transport mode: explore our Optimizing Calculations Guide.
- Retrieve maritime carriers: use our Carriers endpoint to search for carrier information based on SCAC codes or names.
- Find locations: access accurate data via our Geocoding endpoint.
- Explore the list of Supported fields and values.
- Migration guide: review the Migration guide to transition from v2.0 to v2.1 with ease.
- Learn about Data models: visit the Data models guide in the methodology section.