API Reference

Get CO₂e for given shipment

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

❗️

Important

As part of our transition to ISO-14083 certification, we've made some adjustments that don't require any action on your part. You can find detailed information about the changes in our changelog. You can also explore the new ISO-compliant version here.

This endpoint computes CO₂e emissions (i.e CO2 equivalent emissions) for a given shipment. Shipment API allows you to define multiple route legs with multiple containers or parcels. The response contains CO2e per route leg as well as per order and total CO₂e of the shipment.

Shipment request is a nested json on the root level, it consists 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 CO₂e. 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 differentiate between container and parcel shipments using different type values.

The different types are FCL (or CONTAINER), LCL and PARCEL (with PALLET and UNIT_LOAD as aliases).

Each order must have at least one of the following properties: weight (weight of orders in kg) or quantity (number of containers for containerized shipping). You can optionally define sizeTypeCode (size and type of your container).
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. Request must contain at leas one transport leg and 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). While, air mode still accepts LCL shipments, note that the parameter will automatically default to PARCEL as air shipments cannot be containerized.
    To avoid an inaccurate increase in CO₂e when your shipment includes road and air legs, specify the truckSize parameter.

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 flows, and their impact is not to be overlooked. With our Shipment API, you can define hubs for your shipment as leg with mode hub. This type of leg does not include the standard properties of common legs but instead use a detail object with a hubType property. The hubType must be one of the following value:

  • WAREHOUSE
  • TRANSHIPMENT_SITE
  • STORAGE_TRANSHIPMENT
  • LIQUID_BULK_TERMINAL
  • MARITIME_CONTAINER_TERMINAL

As we are finalizing ISO-14083 compliance, we now automatically detect and include TRANSHIPMENT_SITE, and MARITIME_CONTAINER_TERMINAL in our calculations. Please be aware that these are not reflected in the response of this current version, so you may see a small increase in the total CO₂e as a result.

This is an example of such a leg:

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

Container shipment

For a container shipment the type of orders is required. The type can be CONTAINER, FCL or LCL. Result depends on sizeTypeCode and quantity of orders (1 by default), and if you provide the weight of the goods, this value will take priority over the quantity for the CO2 calculation in road and rail but also in sea and inland waters mode for LCL only.
See list of available sizeTypeCodes above. Container shipment cannot be used in combination with air transport.

Example of defined orders for container shipment:

"orders": [{
  "type": "CONTAINER",
  "quantity": 2,
}, {
  "type": "CONTAINER",
  "quantity": 1,
  "sizeTypeCode": "40GP"
}]

Parcel shipment

For a parcel shipment the weight of orders and type are required. See list of available parcel aliases above. Defining quantity of orders makes the request a container shipment.

Example of defined order for parcel shipment:

orders: [{
  type: "PALLET",
  weight: 7000, // in kilograms
}]

Response

The response contains parameters object which consist of orders and type specified in the request. The co2e object represents the CO2e of the entire shipment. You can also find a co2e object within each leg with the following properties:

  • co2e.total (value in grams)
  • co2e.ttw (Tank to Wheel - value in grams)
  • co2e.wtt (Well to Tank - value in grams)
  • co2e.intensity (value in Kg CO2e / t.km).

While we use actual distances for emissions modeling, please note that intensity and transport activity calculations now adhere to ISO-14083 rules. These rules rely on the shortest feasible distance (SFD), making it easier to evaluate and compare itinerary efficiency.

Legs also have properties field with data that were used to compute CO₂e. 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 CO₂e 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
Credentials
Header
Click Try It! to start a request and see the response here!