Freight v3

• Climatiq has released a new version of the intermodal freight endpoint. This is the changelog & upgrade guide for that version. See our API versioning guide for how API versioning works at Climatiq.
• We’re launching a new breaking version of our freight endpoint to comply with the latest version of the GLEC Framework (GLEC v3.1).
• We will not backport the new GLEC v3.1 emissions factors to the freight v2 endpoint, to allow you to be in charge of when to adopt the new methdology.
• Freight v3 is now Generally Available at https://api.climatiq.io/freight/v3/intermodal. Freight v2 is now deprecated and will continue to run for at least one year (until September 2026).
• The changes needed in client applications to migrate from freight v2 are minimal.

Freight v3 GA (September 2025)

Freight v3 has been promoted from preview to General Availability. The main API endpoint is now available at https://api.climatiq.io/freight/v3/intermodal.

Breaking changes from v3-preview1 to v3 GA

• Stricter field validation: Unknown fields in location details and road details now cause 400 validation errors instead of being silently ignored
• Field name change: logistics_hubs_override has been renamed to logistics_hubs_type in location details

Migration from v3-preview1 to v3 GA

1. Update your endpoint URL from https://preview.api.climatiq.io/freight/v3-preview1/intermodal to https://api.climatiq.io/freight/v3/intermodal
2. Update field name if you use logistics_hubs_override in location_options, change it to logistics_hubs_type

The v3-preview1 endpoint remains available with the old behavior for backwards compatibility but is deprecated and will be removed in December 2025.

Freight v3-preview1

Notable changes

Notable changes in freight-v3-preview1 are:

• Methodology updated as specified in GLEC v3.1. This will influence the results of your calculations in accordance with the latest data on freight emissions.
• A new algorithm for rail routing has been enabled providing broader and more accurate coverage.
• Added the option to override our default sea route blocks. This allows you to control which sea passages are to be used when routing ships. For details see the sea route leg documentation.
• Better global coverage of locations and routes, by using a secondary provider if the primary one cannot find a location or route.

API Changes (Request)

The requests you send to the API should still look very familiar. If you’re using the default parameters for everything, your requests should continue working as-is. You can find the API documentation for freight v3 here.

Road Details in China

GLEC 3.1 added specific road emission factors for China. To select China-specific emission factors, you can provide a china object inside of the road_details section of leg_details to incorporate them. Have a look at the API reference documentation to learn about the possible parameter combinations.

If you are using road freight in China you should consider the new options available, otherwise your estimates will be made using our default vehicle details in China.

Renaming of fuel sources for trucks with HPDI engines

The fuel sources

• bio_lng_or_diesel
• cng_or_diesel
• lng_or_diesel

have been renamed to the more accurate forms

• bio_lng_and_diesel
• cng_and_diesel
• lng_and_diesel

Weight constraint changes for articulated trucks with alternative fuels

For articulated trucks using lng, cng, bio_lng, and their diesel variants (lng_and_diesel, cng_and_diesel, bio_lng_and_diesel), the vehicle_weight parameter has been updated from lte_40t to gt_34t_lte_40t to better align with the GLEC methodology and the weight class of other engine types.

Methodological changes

Internally, there are also some methodological changes that you might see reflected in your estimate values, but not in the API request/response.

• All the emission factors used have been updated to the newest value provided by the GLEC organization.
• All non-container sea freight, when refrigerated, now receives a 15% distance adjustment factor (DAF).
• All refrigerated rail freight now receives a unified 12% uplift. Previously, container rail freight had a 93% uplift.

New rail routing algorithm

We have added a new rail routing mechanism, which improves route finding, extends our coverage outside of Europe, and no longer falls back to using great circle distance (GCD) where no routes exist.

Geocoding and routing

In case our primary location provider - HereMaps - cannot find a location or a route, or if we judge that the result returned is not satisfactory, we now fall back to Google Maps. This change should increase the quality of our service, especially in geographically restricted regions, e.g. China.