---
title: "Get CO₂e for a given shipment"
method: POST
path: "/shipment/v2/report/co2"
tags: ["For a shipment"]
---

# Get CO₂e for a given shipment

`POST /shipment/v2/report/co2`

> 📘 This API is fully ISO-14083 compliant
> If your are looking to migrate from the previous version, check out the [Migration Guide](/docs/migrate-from-v20-to-v21). Need to access to the previous version? Check the [documentation](/reference/getco2forshipment-1).

## Table of Contents
- :wrench:  [Request Configuration](#request-configuration)
    - [Headers](#headers)
- :outbox_tray: [Request Structure](#request-structure)
    - [Orders](#orders)
    - [Transport Chain Elements](#transport-chain-elements)
    - [Metadata](#metadata)
- :inbox_tray: [Response Structure](#response-structure)
    - [Parameters](#parameters)
    - [CO₂e Emissions](#co2e-emissions)
    - [Transport Chain Elements](#transport-chain-elements-1)
    - [Metadata](#metadata-1)
- [Support endpoints and resources](#support-endpoints-and-resources)

<br>

This endpoint calculates CO₂ equivalent (CO₂e) emissions for a shipment that includes multiple transport chain elements, such as legs and hubs. It supports a variety of shipment types, from containers to parcels.

The response provides CO₂e emissions data at three levels:

- **Total shipment emissions:** overall CO₂e emissions of the shipment.
- **Per order:** breakdown of emissions for each individual order within the shipment.
- **Per transport chain element:** CO₂e emissions data segmented by each leg or hub of the route.

## Request Configuration

### Headers
- `x-api-key`: your unique API key, required for authentication
- `Accept-Version`: specifies the contract version.
 - **Required for v2.1**: set to `"2.1"` to access the latest version, which is ISO-compliant. 
:warning: **If no Accept-Version header is provided, the API defaults to version 2.0, allowing existing integrations to work without modification.**

## Request Structure

Every request is formatted as a nested JSON object containing both **required** and **optional** properties that define the shipment's details. Here’s a breakdown:

### Orders

`orders`: defines each order within the shipment, with a maximum of 5 orders.

- **Required field**:
  - `type`: specifies the order type. Accepted values:
    - `FCL`
    - `LCL`
    - `parcel`
    - `bulk`
    - `breakbulk`
  - `nContainers`: number of containers. Required only when the order type is `FCL`.
  - `weight`: total weight of the order (in kilograms). Required for all order types except `FCL`.

- **Optional fields**:
  - `containerSizeTypeCode`: specifies the container size/type code (e.g., `20gp`). See the full list of accepted values [here](/reference/container-size-type-codes).

### Transport Chain Elements
`transportChainElements`: defines the shipment’s transport chain, with each item in the array representing either a `leg` or a `hub`.

- **Legs**
  - **Required fields**:
    - `type`: must be set to `"leg"`.
    - `from` and `to`: specifies the origin and destination of the leg (can be a location, `locode`, `iata`, or coordinates).
    - `mode`: specifies transport mode (`sea`, `road`, `rail`, `air`, `inland_water`).
  - **Optional fields**:
    - `distance`: useful if a custom distance is preferred to our calculated distance.
    - `details`: mode-specific details, such as `fuelType` for road mode, `vesselImo` for sea mode.
    - You can find all the possible fields in our [request builder](#form-body-getCO2ForShipment) below

- **Hubs**
  - **Required fields**:
    - `type`: must be set to `"hub"`.
    - `hubType`: specifies the type of hub, such as `warehouse`.

### Metadata

Can contain any information you want to add to your request, for example, to help you identify your shipment. You can pass any key-value pair and it will be echoed back in the response.

When using `generateCertificate=true`, the following fields in `metadata` are used to populate the PDF certificate:

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `id` | string | Shipment identifier | `"S00300133"` |
| `referenceNumber` | string | Booking or reference number | `"26616605"` |
| `status` | string | Shipment status | `"ARRIVED"` |
| `carrier` | object | Carrier information (`scac`, `name`) | `{"scac": "HLCU", "name": "Hapag-Lloyd"}` |
| `client` | object | Client information (`name`) | `{"name": "ACME Corp"}` |

> ℹ️ Note: `metadata.carrier` is used **only for the PDF certificate display**. For the actual CO₂e calculation, carrier information should be provided in `transportChainElements[].details.carrier`.

## Response Structure

The response includes **CO₂e emissions data** at various levels and details for each transport chain element.

### Parameters

`parameters`: reflects the submitted `orders`.

- **Fields**:
  - `orders`: array reflecting the structure of each submitted order, including `type`, `quantity`, `weight`, and `ContainerSizeTypeCode`.
### CO₂e Emissions
`co2e`: provides total emissions values for the shipment.

- **Fields**:
  - `total`: total CO₂e emissions (in grams).
  - `wtt` and `ttw`: emissions broken down by Well-to-Tank and Tank-to-Wheel (in grams).
  - `intensity`: CO₂e intensity (in kg CO₂e per ton-km).

### Transport Chain Elements
`transportChainElements`: array of objects that lists each transport element (`leg` or `hub`) in the sequence, including associated emissions data and properties.

- **Legs**:
  - **Fields**:
    - `type`: `leg`.
    - `from` and `to`: origin and destination, with fields like `locode`, `iata`, `coordinates`, `city`, `country`, and `region`.
    - `mode`: transport mode used (e.g., `sea`, `road`, `air` ...).
    - `co2e`: emissions object with fields like `total`, `wtt`, `ttw`, and `intensity`.
    - `properties`: additional details such as `distance`, `vessel`, `fuelType` and `model`. You can find out more about our models [here](/docs/our-data-models)
- **Hubs**:
  - **Fields**:
    - `type`: `hub`.
    - `location`: object with location details, including fields like `locode`, `coordinates`, `city`, `country`, and `region`.
    - `properties.hubType`: specifies the hub type, such as `warehouse` or `maritime_container_terminal`.
    - `source`: indicates the origin of the hub (`"user_input"` or `"auto_generated"`).
    - `co2e`: emissions object with fields like `total`, `wtt`, and `ttw`.

### Metadata
Contains everything you passed in the input field `metadata`.

### Certificate URL
`certificateUrl`: returned when the query parameter `generateCertificate=true` is set. Contains a URL to download the shipment's PDF certificate. The certificate includes shipment details, emissions breakdown, and any structured metadata fields (`id`, `referenceNumber`, `status`, `carrier`, `client`) you provided.

## Support endpoints and resources
- **Understand how `weight` and `containerSizeTypeCode` impact calculations** across all transport modes: visit our [Weight and Container Guide](/docs/weight-and-containers-size-and-type).
- **Optimize calculation accuracy by transport mode**: explore our [Optimizing Calculations Guide](/docs/sea-transport).
- **Retrieve maritime carriers**: use our [Carriers endpoint](/reference/getcarrierbynameorscac) to search for carrier information based on SCAC codes or names.
- **Find locations**: access accurate data via our [Geocoding endpoint](/reference/getgeocodingall).
- **Explore the list of [Supported fields and values](/reference/container-size-type-codes)**.
- **Migration guide**: review the [Migration guide](/docs/migrate-from-v20-to-v21) to transition from v2.0 to v2.1 with ease.
- **Learn about Data models**: visit the [Data models guide](/docs/our-data-models) in the methodology section.

## Query parameters

- `generateCertificate` boolean

## Headers

- `Accept-Version` '2.1', required

## Request body

- Shipment
  - `metadata` object — Freeform key-value pairs echoed back in the response. When using `generateCertificate=true`, the following fields are used to populate the PDF certificate.
    - `id` string — Shipment identifier
    - `referenceNumber` string — Booking or reference number
    - `status` string — Shipment status
    - `carrier` object — Carrier information
      - `scac` string
      - `name` string
    - `client` object — Client information
      - `name` string
  - `orders` object[], required — Maximum amount of orders is 5
    - `type` 'FCL' | 'LCL' | 'parcel' | 'bulk' | 'breakbulk', required
    - `containerSizeTypeCode` '20GP' | '22G1' | '2200' | '22G0' | '2202' | '2210' | '40GP' | '42G1' | '42G0' | '40G1' | '40HC' | '45G1' | '4500' | '45G0' | '22R1' | '2231' | '42R1' | '4531' | '40RF' | '45R1' | '45R8' | 'LNR1' | '45RH' | '40REHC' | '53GP' | '4510' | 'L5G1' | '45HC' | '20NOR' | '40NOR' | '40HCNOR'
    - `nContainers` number — Required for `fcl` type
    - `weight` number
    - `id` string
  - `transportChainElements` union[], required — List of transport elements, such as `legs` or `hubs`
    - union
      - AirLeg
        - `type` 'leg', required
        - `from` string, required
        - `to` string, required
        - `mode` 'air', required
        - `details` AirLegDetails
          - `aircraft` object
            - `iata` string
            - `type` 'CARGO' | 'PASSENGER'
          - `carrier` object
            - `iata` string
          - `dateTime` object
            - `departure` string, date-time
            - `arrival` string, date-time
          - `distance` number
          - `flight` object
            - `number` string — Number is either flight number (e.g. `8448`) or combination of carrier iata code and flight number (`AF8448`)
        - `metadata` object
      - InlandWaterLeg
        - `type` 'leg', required
        - `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
      - RailLeg
        - `type` 'leg', required
        - `from` string, required
        - `to` string, required
        - `mode` 'rail', required
        - `details` RailLegDetails
          - `fuelType` 'ELEC' | 'DIESEL' | 'DEFAULT'
          - `distance` number
          - `dateTime` object
            - `departure` string, date-time
            - `arrival` string, date-time
        - `metadata` object
      - RoadLeg
        - `type` 'leg', required
        - `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'
          - `distance` number
          - `carrier` object
            - `scac` string
          - `dateTime` object
            - `departure` string, date-time
            - `arrival` string, date-time
        - `metadata` object
      - SeaLeg
        - `type` 'leg', required
        - `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
      - Hub
        - `type` 'hub', required
        - `hubType` 'warehouse' | 'storage_transhipment' | 'liquid_bulk_terminal', required
        - `metadata` object

## Response `200`

OK

## Other responses

- `400` — Bad request
- `404` — Not Found

---

[API](https://skmtc.dev/searoutes/apis/geocoding.md) · [All operations](https://skmtc.dev/searoutes/apis/geocoding/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/searoutes/geocoding/revisions/59f769fc4f39/schema)