Changelog
Back to All

🚨 Upcoming changes to Shipment API

26 days ago by Marine GONZALEZ

This pre-notice outlines the key updates coming to our Shipment API (/shipment/v2/report/co2), scheduled for release in production on December 10th, 2024, as part of our efforts to achieve ISO 14083 compliance.

These updates ensure greater accuracy, transparency, and compliance while introducing a few necessary adjustments to our API logic.

🌍 ISO compliance : emissions for logistics hubs and intensity updates

We are finalizing compliance with ISO 14083 with two key updates required for certification:

  1. Emissions for logistics hubs

    • Automated detection of transshipment and maritime container terminal hubs is now integrated into our calculations, adding their related emissions to the total CO2e. Impact: the total CO2e now account for hub emissions, which result in a slight difference compared to the sum of individual legs. While this ensures compliance with ISO 14083 standards, the detailed breakdown of auto-generated hubs is not visible in the current API contract. To address this, API v2.1 will introduce full visibility for both auto-generated and manual hubs, enhancing transparency for users. This contract will be released in an upcoming cycle. For now, no action is required on your end, but rest assured that we have taken this visibility concern into account and have a solution ready. Since v2.1 will introduce breaking changes, it is not included in this release to avoid disruption.

  2. Intensity new calculation

    • Emissions modeling continues to prioritize actual distances, but intensity and transport activity calculations now use the shortest feasible distances (SFD), as per ISO 14083 requirements. Impact: returning intensity values based on SFD makes it easier to compare the efficiency of different itineraries.

⚠️ Breaking changes

  • Input must contain at least one transport leg
    Requests without at least one transport leg will return a bad request error.

πŸš€ Enhancements

Emissions for air freight: specific case of LCL shipments

  • LCL type is still accepted with air mode but is no longer compatible, as air shipments cannot be containerized. The Shipment API will accept the LCL parameter but automatically default it to parcel for all modes in these cases. Impact: this may significantly increase CO2e when your shipment also includes a road leg, as parcels typically use smaller, less efficient vehicles compared to containerized shipments. To mitigate this, specify the truckSize parameter when known, to prevent the logic from defaulting to the smallest truck size capable of carrying the shipment based on its weight characteristics. See our documentation for more details.

Improved error handling and resilience

  • Explicit error messages:
    Validation errors now provide field-specific details and error codes, making it easier for you to identify and resolve the error source(s) quickly and accurately.

Before:

{
	"timestamp": 1732615731572,
	"status": 404,
	"error": "Not Found",
	"errorCodes": [
		"1140"
	],
	"messages": [
		"We could not calculate relevant CO2 statistics for carrier 21 from CNSHA to FRPAR."
	]
}

After:

{
	"timestamp": 1732615716641,
	"status": 404,
	"error": "Not Found",
	"errorCodes": [
		"1140",
		"1020"
	],
	"messages": [
		"We could not calculate relevant CO2 statistics for carrier 21 from CNSHA to FRPAR.",
		"We could not find a route between 122.06550521343334,30.61798396262171 and 2.355570749697155,48.88080562346494 using sea with a 4.2m draft vessel with parameter allowIceAreas set to false."
	]
}

  • Improved fallback logic:

    • We now attempt to fallback with all models to maximize the value of your input, even after errors occurs in the first tested models.
    • When an invalid container size type code is provided, the API will now fallback to the default container size type code (20GP). This aligns with the existing behavior where 20GP is used when no container size type code is provided.

  • Validation improvements:

    • Invalid IMO formats no longer return a 400 error. Instead, we fallback to calculations without IMO and return a 200 response.

πŸ›  Bug Fixes

Emissions for inland-waterways

  • Prioritizes weight when provided, ensuring more accurate emissions calculations.

Emissions for logistics hubs

  • Default weight for container orders with no weight provided is now set to 10t, aligning with GLEC framework recommendations.

Emissions for Pallets

  • Pallet orders with a specified quantity are now correctly treated as pallets rather than containers.
    Impact: CO2e may increase for road mode, as pallets often use smaller vehicles than containerized shipments.

Properties for sea leg

  • The field leg[*].properties.orders[*].nTEU is now consistently returned in the response.

πŸ“ Documentation & support

  • All changes will be reflected in our API documentation.
  • This notice aims to prepare you for upcoming changes while maintaining the stability of your current workflows. If you have any questions or require assistance, please contact our support team. πŸš€