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 total CO2e of the shipment.
Shipment request is a nested json on the root level it consist of required properties - type
, containers
, legs
and optional properties - metadata
and details
.
Supported type
value is only CONTAINER
.
You can specify details
of shipment that will be displayed on the certificate (pdf). The following details
are allowed: shipmentId
, bookingNumber
, status
, carrier.scac
, carrier.name
and client.name
. Where status
can be BOOKED
or ARRIVED
and client.name
is the name of your client. None of this properties have any influence on how we compute CO2e.
You can define list of containers
that belong to your shipment. Each container must have at least one of the following properties: quantity
(number of containers) or weight
(weight of containers in kg). You can optionally defined sizeTypeCode
(size and type of your container). 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).
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 reqiures 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. You can definedetails.carrier.scac
per leg. In this case, you recive 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. - For modes
road
andrail
you can specifydetails.fuel
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.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 containers
is required. Result depends on sizeTypeCode
and quantity
of containers
disregarding weight
. See list of available sizeTypeCodes
above. FCL shipment cannot be used in combination with air
transport.
Example of defined containers for FCL shipment:
"containers": [{
"quantity": 2,
}, {
"quantity": 1,
"sizeTypeCode": "40GP"
}]
LCL shipment
For an LCL (Less than Container Load) shipment the weight
of containers
is required. Defining quantity
of containers
makes the request an FCL shipment.
Example of defined container for LCL shipment:
containers: [{
weight: 7000, // in kilograms
}]
Response
The response contains parameters
object which consist of containers
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 was used to compute CO2e for a particular leg. It for instance includes distance (value in meters) and weight (value in kilograms). 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.