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

• 🔧 Request Configuration
  • Headers
• 📤 Request Structure
  • Orders
  • Transport Chain Elements
  • Metadata
• 📥 Response Structure
  • Parameters
  • CO₂e Emissions
  • Transport Chain Elements
  • Metadata
• Support endpoints and resources

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.
  ⚠️ 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

• Optional fields:

  • nContainers: Number of containers.
  • containerSizeTypeCode: Specifies the container size/type code (e.g., 20gp). See the full list of accepted values here.
  • weight: Total weight of the order (in kilograms).

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: Distance of the leg (useful if a custom distance is preferred).
    • details: Contains mode-specific details (e.g., fuelType for road mode, vesselName 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.

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, 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.

Support endpoints and resources

• Understand the impact of weight and containerSizeTypeCode parameters: visit our Guide on Weight and Container size and type to learn how these fields influence calculations across all transport modes.
• Optimize calculation accuracy by transport mode: explore the Optimizing calculations by transport mode guides for best practices and detailed insights into parameter impacts and interactions for each mode.
• Retrieve maritime carriers: use our Carriers endpoint to search for carrier information based on SCAC codes or names.
• Find locations: use our Geocoding endpoint to access accurate location data.
• Supported fields and values: refer to the Supported fields and values section for a complete list of accepted inputs for the Shipment API.
• 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 to explore how our models work and when they are applied.