Get CO₂e for a given shipment

📘 This API is fully ISO-14083 compliant If your are looking to migrate from the previous version, check out the Migration Guide. Need to access to the previous version? Check the documentation.

Table of Contents

• :wrench: Request Configuration
  • Headers
• :outbox_tray: Request Structure
  • Orders
  • Transport Chain Elements
  • Metadata
• :inbox_tray: Response Structure
  • Parameters
  • CO₂e Emissions
  • Transport Chain Elements
  • Metadata
• 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.

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 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:

ℹ️ 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
• 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.
• Optimize calculation accuracy by transport mode: explore our Optimizing Calculations Guide.
• Retrieve maritime carriers: use our Carriers endpoint to search for carrier information based on SCAC codes or names.
• Find locations: access accurate data via our Geocoding endpoint.
• Explore the list of Supported fields and values.
• Migration guide: review the Migration guide to transition from v2.0 to v2.1 with ease.
• Learn about Data models: visit the Data models guide in the methodology section.

{
  "metadata": {
    "id": "S00300133",
    "referenceNumber": "26616605",
    "status": "ARRIVED",
    "carrier": {
      "scac": "HLCU",
      "name": "Hapag-Lloyd"
    },
    "client": {
      "name": "ACME Corp"
    }
  },
  "orders": [
    {
      "type": "parcel",
      "weight": 300,
      "id": "OD45782"
    }
  ],
  "transportChainElements": [
    {
      "type": "leg",
      "from": "PVG",
      "to": "AMS",
      "mode": "air",
      "details": {
        "aircraft": {
          "iata": "74Y",
          "type": "CARGO"
        },
        "carrier": {
          "iata": "AF"
        },
        "flight": {
          "number": "8448"
        }
      }
    }
  ]
}