Get CO2 for given shipment

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 specify details.voyageNumber and details.vessel. Object vessel has two properties name and imo. Specifying imo of the vessel increases accuracy of CO2e values. Different way of improving accuracy of CO2e values is defining a carrier. You can define details.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 define details.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 and rail you can specify details.fuel to get a more accurate CO2e. Furthermore, you can specify details.truckSize (integer) for mode road. If you don't pass the trucksize we will choose appropriate truckSize for you. To improve accuracy of CO2e values for mode road you can define details.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 specify vesselType with one of the following values: MOTOR_VESSEL, COUPLED_CONVOY, PUSHED_CONVOY, CONTAINER_VESSEL_110, CONTAINER_VESSEL_135 or CONTAINER_COUPLED. Default value is MOTOR_VESSEL.
• For mode air you can specify details.aircraft with two optional properties: iata (IATA designator of the aircraft type) and type (either PASSENGER or CARGO). 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.