This endpoint computes CO2e emissions (i.e CO2 equivalent emissions) for a given shipment. Shipment API allows you to define multiple route legs with multiple containers. The response contains CO2e per route leg as well as per order and total CO2e of the shipment.
Shipment request is a nested json on the root level it consist of required properties - orders
, legs
and optional properties - metadata
and details
.
You can specify details
of shipment that will be displayed on the certificate (pdf). The following details
are allowed: id
, referenceNumber
, status
, carrier.id
, carrier.scac
, carrier.name
and client.name
. Where status
can be BOOKED
or ARRIVED
and client.name
is the name of your client. Provided carrier id, name or scac are the only parameters taken into account when computing CO2e. However, legs[0].details.carrier
id, scac or name will take precedence if has been provided. To be more specific, /search/v2/carriers
endpoint can be used to retrieve a carrier object by its name or scac and can be used in details.carrier
or legs[0].details.carrier
.
You can define list of orders
that belong to your shipment with maximum number of 5. All orders must include the type
value. You can differenciate between FCL
and LCL
using different type
values. FCL
has aliases CONTAINER
or FCL
and LCL
has aliases LCL
, PARCEL
, PALLET
or UNIT_LOAD
. Each order must have at least one of the following properties: quantity
(number of orders) or weight
(weight of orders in kg). You can optionally defined sizeTypeCode
(size and type of your order). The supported values and their meanings are: 20GP or 22G1 (20ft, General purpose (Standard)), 40GP or 42G1 (40ft, General purpose (Standard)), 40HC or 45G1 (40ft High cube, General Purpose) and 22R1 (20ft, Reefer), 42R1 or 40NOR (40ft, Reefer), 45R1 or 40REHC (40ft High cube, Reefer). You can also optionally provide id
of your order.
Field legs
is a list of routes that are part of the shipment. Maximum number of legs is 10.
Each leg requires from
and to
(origin and destination). The value could be coordinates "59.11;6.14"
or a string that could be geolocated "hamburg"
.
Each leg requires a mode
. The following modes are supported: sea
, road
, rail
, inland-water
and air
.
Each leg can have an optional details
. For all modes you can specify dateTime
with arrival
and departure
properties in ISO_8601 format, preferrably with timezone YYYY-MM-DDTHH-mm-ssTZD
(2022-02-22T15:00:00+01:00
). if you want to use different distance than the one we calculate you can specify optional distance
property.
- For mode
sea
you can specifydetails.voyageNumber
anddetails.vessel
. Objectvessel
has two propertiesname
andimo
. Specifyingimo
of thevessel
increases accuracy of CO2e values. Different way of improving accuracy of CO2e values is defining a carrier ordetails.fuelType
. You can definedetails.carrier.id
,details.carrier.name
ordetails.carrier.scac
per leg. In this case, you receive CO2e values that are calculated as average values of all the itineraries for given carrier on given route. If you definedetails.carrier.scac
you are required to use UNLOCODES for origin (from
) and destination (to
) of your leg. Passing coordinates or location string will not pass our validation. If you provide both a vessel imo and a carrier id, scac or name the imo will take the precedence over the carrier. - For modes
road
andrail
you can specifydetails.fuelType
to get a more accurate CO2e. Furthermore, you can specifydetails.truckSize
(integer) for moderoad
. If you don't pass the trucksize we will choose appropriate truckSize for you. To improve accuracy of CO2e values for moderoad
you can definedetails.carrier.id
,details.carrier.name
ordetails.carrier.scac
. This works only for North America region and the computation uses SmartWay carrier data (Dray (CONTAINER) and Mix (AVERAGE_MIXED)). If the SCAC passed is not valid or we don't have enough data to compute CO2e, the computation will be based on GLEC defaults. - For mode
inland-water
you can specifyvesselType
with one of the following values:MOTOR_VESSEL
,COUPLED_CONVOY
,PUSHED_CONVOY
,CONTAINER_VESSEL_110
,CONTAINER_VESSEL_135
orCONTAINER_COUPLED
. Default value isMOTOR_VESSEL.
- For mode
air
you can specifydetails.aircraft
with two optional properties:iata
(IATA designator of the aircraft type) andtype
(eitherPASSENGER
orCARGO
).air
mode can be used only for LCL shipment
Each leg can have optional metadata
. You can add any information you want to metadata
object and it will be returned to you in the response. Contents of metadata
do not influence CO2e calculation.
You can generate a certificate document (pdf) by setting the optional query parameter generateCertificate
to true
.
FCL Shipment
For an FCL (Full Container Load) shipment the quantity
of orders
and type
are required. See list of available FCL aliases above. Result depends on sizeTypeCode
and quantity
of orders
disregarding weight
. See list of available sizeTypeCodes
above. FCL shipment cannot be used in combination with air
transport.
Example of defined orders for FCL shipment:
"orders": [{
"type": "CONTAINER",
"quantity": 2,
}, {
"type": "CONTAINER",
"quantity": 1,
"sizeTypeCode": "40GP"
}]
LCL shipment
For an LCL (Less than Container Load) shipment the weight
of orders
and type
are required. See list of available LCL aliases above. Defining quantity
of orders
makes the request an FCL shipment.
Example of defined order for LCL shipment:
orders: [{
type: "PALLET",
weight: 7000, // in kilograms
}]
Response
The response contains parameters
object which consist of orders
and type
specified in the request. Co2e
object stands for CO2e of entire shipment. You can also find co2e
object in each leg
. It has following properties: co2e.total
(value in grams), co2e.ttw
(Tank to Wheel - value in grams), co2e.wtt
(Well to Tank - value in grams) and co2e.intensity
(value in Kg CO2e / t.km). Legs also have properties
field with data that were used to compute CO2e. You can find common properties for all leg - order CO2e requests in the root of the properties and order specific data in particular order object for instance properties.orders[0]
. Each order contains co2e object and has a common structure accross the whole shipment which is located in legs[0].properties.orders[0].co2e
. Parameters
property inside a leg holds details
that were used in the request. from
and to
are objects containing coordinates
, locode
(if exists), country
and city
.
The certificateUrl
is where you can download certificate for your shipment in pdf format. We recommend saving this pdf right after receiving the response.