Freight v2

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

Notable changes

Freight v2 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.
• There is no list of co2e values for each used emission factor. Instead, the source trail provides information about what data points went into the calculation.

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 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 vehicle types you can select. If you use leg_details, you should go through the new API reference documentation and determine how your previous 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 transport has seen a large overhaul with 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 called fuel_source to better align with GLEC terminology and the other transport modes.
• Previously for road trips, the valid leg details varied depending on whether a trip was inside or outside of North America. Now you can supply two different sets of parameters in each request: One for North America, and one for the rest of the world. The API will use the correct parameters depending on where the trip takes place.

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 distances, 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 accepts an override_transition parameter, 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 options are no longer available, and the weight of any truck used to transport the cargo must be taken into account when using ro_ro.

Country no longer required for CoordinateLocation

When specifying a location via coordinates, previously you also had to specify a country the coordinates were placed in. This is no longer necessary, as it can be determined automatically. This change has been backported to v1 as well.

API Changes (Response)

The response has undergone a bit more of a significant change due to information about the used emission factors being returned via source trail and not as a list inside the response.

• 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 able to do so. 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 the extraction and transportation of fuel. For transport types using electricity, this also includes the generation of the electricity, the sourcing of 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 sourced from OpenStreetMap (OSM). If you show this externally, you must show attribution. See the reference documentation for more details.
• The notices array has moved from a top-level array to an array on each ResponseLeg, so it is easier to see which parts of the route a notice belongs to.
• If you had the feature enabled where the entire path was returned in the response, this format has changed. Previously, the format was a GeoJSON object, but it is now encoded in the Flexible Polyline (opens in a new tab) format. This is much more space-efficient but might require additional parsing on your side.

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