Get CO2 for given shipment

post https://api.searoutes.com/shipment/v2/report/co2

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, 22G1, 2200, 22G0, 2202, 2210 (20ft, General purpose (Standard)) [Default]
40GP, 42G1, 42G0, 40G1 (40ft, General purpose (Standard)),
40HC, 45G1, 45G0, 4500, 4510 (40ft High cube, General Purpose),
22R1, 2231 (20ft, Reefer),
40NOR, 42R1, 4531 (40ft, Reefer),
40REHC, 45R1, 45R8 (40ft High cube, Reefer),
53GP (53ft High cube).
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 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 or details.fuelType. You can define details.carrier.id, details.carrier.name or details.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 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. 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 and rail you can specify details.fuelType 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.id, details.carrier.name or 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.

Hubs

Logistics hubs are locations where freight is stored and processed, and handled from one vehicle or transport mode to another.

Hubs are an integral part of a shipment transport flow, and as such, their impact is not to be overlooked. Our Shipment API allows you to define hubs for your shipment. You can define hub as a leg with mode hub. This type of leg does not have common leg properties which we mentioned above. You can define detail object with property hubType. HubType must be one of the following value: WAREHOUSE, TRANSHIPMENT_SITE, STORAGE_TRANSHIPMENT, LIQUID_BULK_TERMINAL, MARITIME_CONTAINER_TERMINAL.

This is an example of such a leg:

... 
{ 
  "mode": "hub", 
  "details": { 
    "hubType": "TRANSHIPMENT_SITE"
    }
} 
...

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.

Language
Authorization
Header
Click Try It! to start a request and see the response here!