Freight v2

• Climatiq is in the process of creating 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), and the new ISO standard, ISO 14083.
• We will not be able to backport the new GLEC v3 emissions factors to the freight v1 endpoint, so although that will continue to run once deprecated, we recommend all our freight users to update to use v2 as soon as possible once out of preview.

Freight v2-preview1

• Freight v2-preview1 is the first preview version of freight v2.
• This document will now list updates that are new in v2-preview1.

Notable changes

Freight v2-preview1 ships with several quality-of-life improvements, along with several new features. The most notable changes are.

• New emission factors from GLEC v3.
• New support for Electric trucks & vans, powered by the electricity endpoint and using location-based electricity emissions for the country where the leg departs from.
• Emissions from logistics hubs included. Logistics hubs emissions cover the transportation and movement of cargo from one mode of transportation to another, such as moving containers from a truck to a ship. They are automatically added when the mode of transportation changes. See below for more information.
• First class support for refrigerated goods. Pass in the refrigerated parameter in your API response, and you'll automatically get emissions for a refrigerated supply chain from end-to-end.

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.

Leg Details changes

We have however changed the leg_details parameters we accept. Some of this is due to the new emission factors from GLEC having different buckets for vehicle types weight ranges and loads, etc., and some of it is because we've simplified the number of e.g. vehicle types you could select. If you use leg_details you should go through the new API reference documentation and judge how your old leg_details best fit into the new vehicle & vessel types. Some changes you might need to make:

• Adjust vehicle/vessel types, weights or fuel types. In particular road has seen a large overhaul with e.g. hgv_rigid and hgv_articulated being renamed to rigid_truck and articulated_truck respectively.
• If you were using refrigerated_ variants before, use the new refrigerated cargo feature instead.
• For road, the parameter previously named fuel_type is now named fuel_source to better align with GLEC terminology and the other transport modes.

Logistics Hubs

From GLECv3:

[Logistics hubs], are a vital backbone to supply chains. Logistics hubs are where freight is stored and processed, and where myriad forms of transport intersect.

The new version of the freight API includes emissions from logistics hubs. Logistics hubs emissions cover the transportation and movement of cargo from one mode of transportation to another, such as moving containers from a truck to a ship. While the API automatically picks sensible defaults, if you need to override these defaults, you can specify that option on the LocationOptions object.

No air methodology choice

The new version of the GLEC framework has aligned on a single methodology for air estimates the ICAO/IATA methodology. The methodology field has been removed, and you do not need to supply it.

User-provided distances

Freight v1 accepted a leg parameter distance_km which expected an actual distance to be provided, it is replaced by planned_distance_km which expects Shortest Feasible Distance or Planned Distance. This acknowledges that our estimations are based on planned distance so more effort is required to use actual distances properly. It also reduces the risk of incorrect estimates caused by the wrong distance being provided.

LocationOption changes

• LocationOptions now also takes in an override_transition, in case you know of a private port, railway station or similar, that Climatiq does not. This change has been backported to v1 as well.
• When doing routing in China, previously we required you to always specify the country code. This is no longer a requirement. This change has been backported to v1 as well.

Different Roll On - Roll Off Behavior

In the previous version, when the ro_ro vessel type was explicitly selected, there was an option to account for the weight of the truck or trailer carrying the cargo via the trailer_only or truck_plus_trailer load types. These are no longer options and so the weight of any truck useed to transport the cargo must be taken into account when using ro_ro.

API Changes (Response)

The response has undergone a bit of a more significant change currently, due to much less information about the used emission factors. This is while we figure out how to best expose this API response for transparency and audit-ability. If you have any concerns, thoughts or want to be partners on this, please reach out.

• The response no longer contains the individual emission factors used for each estimation, but only the summary.
• Previously we were not always able to split all estimations into multiple categories, but we are now. The responses are now always split into three distinct categories:
  • vehicle_operations: The emissions from the combustion of the fuel, leakage of refrigerants etc. This approximately corresponds to Tank-to-wheel (TTW).
  • vehicle_energy_provision The emissions required to produce the fuel and ship it to the vehicle. This includes e.g. extraction of fuel, and transportation of the fuel. For transport types using electricity, this also includes the generation of the electricity, the sourcing of the fuel for the electricity and the transmission and distribution losses. This approximately corresponds to Well-to-tank (WTT).
  • hub_equipment: The emissions from equipment at logistics hubs used to move cargo between transport modes and store it temporarily.
• Some of the data, such as location names is now source from OpenStreetMap (OSM), and if you show this externally, you must show attribution. See the reference documentation for more details.

Methodological changes

Internally there's 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 organisation.
• When a road route uses a ferry, we now use the Ferry-RoPax vessel type instead of RoRo.
• For rail networks, we currently use the European track electrification of 62% but intend to estimate the track electrification of the calculated route.