--- title: "Get CO₂e for given shipment" method: POST path: "/shipment/v2/report/co2" tags: ["For a shipment"] --- # Get CO₂e for given shipment `POST /shipment/v2/report/co2` ## Request - Base URL: `https://api.searoutes.com` - URL: `https://api.searoutes.com/shipment/v2/report/co2` - Auth: API key in header `x-api-key` > ❗️ 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](https://developer.searoutes.com/changelog/searoutes-cycle-21-pre-release-notice-preparing-for-shipment-api-v20-changes). You can also explore the new ISO-compliant version [here](/reference/getco2forshipment). 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.flight` to get the emissions based on the aircraft operated for this specific flight number. In case the flight number is not found but the carrier is, emissions will be modeled based on the mot representative aircraft for this carrier. If you don't know the flight number, you can choose to 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: ```JSON ... { "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: ```JSON "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: ```JSON 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. ## Query parameters - `generateCertificate` boolean ## Request body - Shipment - `metadata` object - `details` object - `id` string: We recommend to use this parameter instead of `shipmentId` (deprecated) - `referenceNumber` string: We recommend to use this parameter instead of `bookingNumber` (deprecated) - `status` 'BOOKED' | 'ARRIVED' - `carrier` object - `scac` string - `name` string - `client` object - `name` string - `shipmentId` string: We recommend to use the parameter `id` instead. - `bookingNumber` string: We recommend to use the parameter `referenceNumber` instead. - `orders` object[], required: We recommend to use this parameter instead of `containers` (deprecated). Maximum amount of orders is 5. - `type` 'CONTAINER' | 'PARCEL' | 'FCL' | 'LCL' | 'PALLET' | 'UNIT_LOAD', required - `sizeTypeCode` '20GP' | '22G1' | '2200' | '22G0' | '2202' | '2210' | '40GP' | '42G1' | '42G0' | '40G1' | '40HC' | '45G1' | '4500' | '45G0' | '22R1' | '2231' | '42R1' | '4531' | '40NOR' | '45R1' | '45R8' | '40REHC' | '53GP' - `quantity` number - `weight` number - `id` string - `legs` union[], required - union - RoadLeg - `from` string, required - `to` string, required - `mode` 'road', required - `details` RoadLegDetails - `truckSize` integer - `fuelType` 'DIESEL' | 'CNG' | 'LNG' | 'PETROL' | 'HVO' | 'ELEC' | 'LPG' | 'BIOLNG' | 'BIOCNG' | 'HYDROGEN_GASEOUS_FCV' | 'BIODIESEL' | 'B1' | 'B2' | 'B5' | 'B7' | 'B10' | 'B20' | 'B30' | 'B50' - `fuel` string: We recommend to use the parameter `fuelType` instead - `distance` number - `carrier` object - `scac` string - `dateTime` object - `departure` string, date-time - `arrival` string, date-time - `metadata` object - SeaLeg - `from` string, required - `to` string, required - `mode` 'sea', required - `details` SeaLegDetails - `voyageNumber` string - `carrier` object - `scac` string - `vessel` object - `imo` string - `name` string - `fuelType` 'HFO' | 'VLSFO' | 'ULSFO' | 'MDO' | 'MGO' | 'LNG' | 'BIOLNG' | 'LSMGO' | 'METHANOL' | 'BIOMETHANOL' | 'IFO380' | 'LNG_CMACGM_VAS' | 'UCO' | 'METHANOL_COAL' | 'METHANOL_GAS' | 'METHANOL_RENEWABLES' - `distance` number - `dateTime` object - `departure` string, date-time - `arrival` string, date-time - `metadata` object - RailLeg - `from` string, required - `to` string, required - `mode` 'rail', required - `details` RailLegDetails - `fuelType` 'ELEC' | 'DIESEL' | 'DEFAULT' - `fuel` string: We recommend to use the parameter `fuelType` instead - `distance` number - `dateTime` object - `departure` string, date-time - `arrival` string, date-time - `metadata` object - InlandWaterLeg - `from` string, required - `to` string, required - `mode` 'inland-water', required - `details` InlandWaterLegDetails - `vesselType` 'MOTOR_VESSEL' | 'COUPLED_CONVOY' | 'PUSHED_CONVOY' | 'CONTAINER_VESSEL_110' | 'CONTAINER_VESSEL_135' | 'CONTAINER_COUPLED' - `distance` number - `dateTime` object - `departure` string, date-time - `arrival` string, date-time - `metadata` object - AirLeg - `from` string, required - `to` string, required - `mode` 'air', required - `details` AirLegDetails - `aircraft` object - `iata` string - `type` 'CARGO' | 'PASSENGER' - `distance` number - `dateTime` object - `departure` string, date-time - `arrival` string, date-time - `flight` string: Flight is the combination of carrier iata code and flight number (`AF8448`) - `metadata` object - Hub - `mode` 'hub', required - `details` HubDetails, required - `hubType` 'WAREHOUSE' | 'TRANSHIPMENT_SITE' | 'STORAGE_TRANSHIPMENT' | 'LIQUID_BULK_TERMINAL' | 'MARITIME_CONTAINER_TERMINAL', required - `metadata` object - `containers` object[]: We recommend to use the parameter `bookings` instead. - `sizeTypeCode` '20GP' | '22G1' | '2200' | '22G0' | '2202' | '2210' | '40GP' | '42G1' | '42G0' | '40G1' | '40HC' | '45G1' | '4500' | '45G0' | '22R1' | '2231' | '42R1' | '4531' | '40NOR' | '45R1' | '45R8' | '40REHC' | '53GP' - `quantity` number - `weight` number - `type` 'CONTAINER' ## Response `200` OK ## Other responses - `400`: Bad request - `404`: Not Found - `418`: Multiple errors --- [API](https://skmtc.dev/searoutes/apis/old.md) - [All operations](https://skmtc.dev/searoutes/apis/old/llms.txt) - [OpenAPI document](https://skmtc.dev/searoutes/apis/old/revisions/16730852d9ff?raw)