API Reference
Freight v2 (preview 1)

Intermodal Freight v2 (preview 1) ADD-ONADD-ON

🚫
Newer version available

You are reading documentation for an older version of this feature. We recommend you view the documentation for the latest version of this feature, which is available here.

This version of the feature will be removed: December 2024

⚠️
Preview Feature

This feature is currently in preview. That means that we believe the feature is good enough to start using, but:

  • There might still be bugs or edge cases we haven't covered.
  • The documentation and error messages might be less detailed.
  • We might need to make further changes in the API surface.

We need the ability to iterate quickly on preview versions, so we offer less guarantees of stability. When we make changes to the preview version, we will release a new version, and you must migrate to this new version within one month. Read more about API versioning at Climatiq here.For this reason, preview endpoints are not available without explicitly opting in. If you would like to opt-in to this preview feature, please contact us.

Climatiq allows you to use emission factors from the Global Logistics Emissions Council(GLEC) (opens in a new tab) to calculate the carbon emissions for shipping freight around the world using multiple modes of transport such as by sea, air, road or rail.

⚠️
Read the guide or changelog first

This is the API reference for the intermodal freight feature.

If you're just getting started, we highly recommend that you start with the guide that explains the concepts you will need to understand to effectively use the endpoint

If you're already using version 1 and are interested in upgrading, we suggest you start with the changelog which highlights which sections of this document to concentrate on.

Estimate

POST Calculate total estimated emissions produced by shipping an amount of cargo by the specified route.

https://preview.api.climatiq.io/freight/v2-preview1/intermodal

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body
    • cargorequired object

      The details of the cargo being shipped

    • routerequired array of Route Legs or Locations

      An array of route parts that compose the route this cargo is taking. A route must start and end with a location, and have legs between each location. Sometimes you may omit some locations and rely on automatic routing.

curl --request POST \
--url https://preview.api.climatiq.io/freight/v2-preview1/intermodal \
--header "Authorization: Bearer $CLIMATIQ_API_KEY" \
--data '{
"route": [
{ "location": { "query": "Hamburg" } },
{
"transport_mode": "road",
"leg_details": {
"vehicle_type": "van",
"vehicle_weight": "lte_3.5t",
"fuel_source": "petrol"
}
},
{ "location": { "query": "Berlin" } }
],
"cargo": {
"weight": 10,
"weight_unit": "t"
}
}'

Response

A response consists of the following attributes.

Response parameters
    • co2efloat

      The total carbon dioxide equivalent emitted for the entire trip. This encompasses logistics hubs, vehicle operations and vehicle energy provisioning.

    • hub_equipment_co2efloat

      The carbon dioxide equivalent emitted for the operation of logistics hubs during the trip. This encompasses both operational and energy provisioning emissions. 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.

    • vehicle_operation_co2efloat

      The carbon dioxide equivalent emitted for the part of the trip where the vehicle is being operated, such as the combustion of fuel, leakage of refrigerants etc.

    • vehicle_energy_provision_co2efloat

      The carbon dioxide equivalent emitted for the provisioning of energy for the vehicle operations. This covers among others: electricity generation, electricity transmission and distribution losses, the production of fuel, and the transportation of fuel to the vehicle.

    • co2e_calculation_methodstring

      Which calculation methodology that was used for the calculation. The value of this is either "ipcc_ar4_gwp100", "ipcc_ar5_gwp100", "ipcc_ar6_gwp100" or "ipcc_mixed_gwp100". Learn more about calculation methods here.

    • co2e_unitstring

      The unit in which the CO2e field is expressed. The value of this is always kg

    • distance_kmfloat

      The distance in kilometers that the cargo has been shipped along the specified route.

    • cargo_tonnesfloat

      The weight in tonnes which is being shipped along the specified route.

    • An array that specifies the route the cargo took. This array will always consist of alternating response locations and response legs. It will always start and end with a location. Even if you have omitted any locations, they will not be omitted in the response.

    • noticesarray of Notices

      An array of notices that is relevant for understanding the result. This could be if Climatiq cannot accurately calculate the distance for a certain route, but still performed a less-accurate calculation.

{
"co2e": 2781,
"hub_equipment_co2e": 12,
"vehicle_operation_co2e": 2098,
"vehicle_energy_provision_co2e": 670.9,
"co2e_unit": "kg",
"co2e_calculation_method": "ipcc_ar6_gwp100",
"cargo_tonnes": 10,
"distance_km": 285.5,
"route": [
{
"type": "location",
"co2e": 6,
"co2e_unit": "kg",
"co2e_calculation_method": "ipcc_ar6_gwp100",
"source_trail": [
{
"data_category": "emission_factor",
"name": "Freight logistics - transshipment - ambient",
"source": "GLEC",
"source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0",
"year": "2023",
"region": "GLOBAL",
"region_name": "Global"
}
],
"name": "Hamburg, Germany",
"latitude": 53.55562,
"longitude": 9.98745,
"confidence_score": 1
},
{
"type": "leg",
"co2e": 2769,
"co2e_unit": "kg",
"co2e_calculation_method": "ipcc_ar6_gwp100",
"source_trail": [
{
"data_category": "emission_factor",
"name": "Van <3.5t - Petrol",
"source": "GLEC",
"source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0",
"year": "2023",
"region": "EU_S_AMERICA",
"region_name": "Europe and South America"
}
],
"vehicle_operation_co2e": 2098,
"vehicle_energy_provision_co2e": 670.9,
"transport_mode": "road",
"distance_km": 285.5
},
{
"type": "location",
"co2e": 6,
"co2e_unit": "kg",
"co2e_calculation_method": "ipcc_ar6_gwp100",
"source_trail": [
{
"data_category": "emission_factor",
"name": "Freight logistics - transshipment - ambient",
"source": "GLEC",
"source_dataset": "Default fuel efficiency and GHG emission intensity values v3.0",
"year": "2023",
"region": "GLOBAL",
"region_name": "Global"
}
],
"name": "Berlin, Germany",
"latitude": 52.51604,
"longitude": 13.37691,
"confidence_score": 1
}
],
"notices": []
}
OpenStreetMap attribution

Climatiq draws information from many sources, including OpenStreetMap (opens in a new tab). The license of that information requires you to provide attribution where this information comes from. If you display information such as routes and location names externally, you should make sure you correctly attribute this data to OpenStreetMaps, e.g. by writing "May contain information from OpenStreetMap".

Route Leg

Each route in the request has one or more legs. A leg is a transition between two locations. A leg contains the following properties.

  • transport_moderequired string

    How the goods are transported. Allowed values are air, sea, road, rail.

  • leg_detailsobject

    The details of the leg such as fuel and vessel type. Valid values here vary between transport_mode. Allowed values are RoadDetails, SeaDetails, AirDetails or RailDetails.

  • planned_distance_kmfloat

    Planned Distance or Shortest Feasible Distance for the leg. We will use this distance instead of the planned distance we would normally calculate. If you need to use an actual distance, be careful to apply a Distance Adjustment Factor (DAF) in order to reduce the distance. For example, GLEC suggests that for sea transport, a DAF of 15% can be used to account for average container sea transport distances being on average 15% longer than the shortest feasible distance - ie. divide the actual distance by 1.15 to get the appropriate planned distance. GLEC does not provide guidance for any other transport modes.

A route cannot by default have more than three legs. If you need more than three legs, you can call the API endpoint multiple times, or contact Climatiq (opens in a new tab) to get this limit raised

Road (Outside of North America)

A leg with the "transport_mode": "road", that is taking place outside of North America can specify further details about the journey by including this object under leg_details.

These options do not apply to trips with combustion vehicles within North America, where the input options are more limited. If your trip is in North America, see the section below on combustion vehicles for North America. or the section on electric vehicles which is globally applicable.

Different vehicle_types have different requirements and options. Please consult the table further down for the list of valid parameter combinations.

  • vehicle_typerequired string

    The type of vehicle that is used for the transportation. articulated and rigid refers to truck types. All valid values are: van, rigid_truck, articulated_truck, articulated_truck_incl_lightweight_trailer

  • vehicle_weightrequired string

    The carrying capacity of the vehicle, as a string specifying the range. E.g. gt_60t_lte_72tmeans a carrying capacity greater than 60tons and less than or equal to 72tons. Refer to the table below for all valid combinations of values.

  • fuel_sourcerequired string

    The fuel source that the vehicle is running on. Valid values vary depending on the vehicle type, but all valid values are: diesel, cng, lng, bio_lng, bio_lng_or_diesel, cng_or_diesel,lng_or_diesel, petrol, electricity

  • load_typestring
    Default value: Average

    The type of load the vehicle carries. Valid values vary depending on the vehicle type, but all valid values are: light, heavy, container.

Valid parameter combinations (Outside of North America)

Please consult this table to see what valid combinations of values are when outside of north america, this includes electrical vehicles:

vehicle_type Parameterfuel_source Parametervehicle_weight Parameterload_type Parameter
articulated_trucklng, lng_or_diesel, bio_lng, bio_lng_or_diesel, cng, cng_or_diesellte_40tcontainer, null
diesellte_34t, gt_34t_lte_40tcontainer, null
gt_40t_lte_44tcontainer, heavy, light, null
gt_44t_lte_60tcontainer, heavy, null`
gt_60t_lte_72tcontainer, heavy
articulated_truck_incl_lightweight_trailerdiesellte_40theavy
rigid_truckcnggt_3.5t_lte_7.5t, gt_7.5t_lte_12t, gt_12t_lte_20t, gt_20t_lte_26tnull
dieselgt_3.5t_lte_7.5t, gt_7.5t_lte_12t, gt_12t_lte_20t, gt_20t_lte_26tnull
gt_26t_lte_32tcontainer, null
lnggt_20t_lte_26tnull
electricitygt_3.5t_lte_7.5t, gt_7.5t_lte_12t, gt_12t_lte_20t gt_26t_lte_40tlight, null
vandiesel, petrol, cng, lpg, electricitylte_3.5tnull

Road (Combustion vehicles within North America)

A leg with the "transport_mode": "road", taking place inside North America and using a combustion vehicle can specify further details about the journey by including this object under leg_details.

These options only apply to trips with combustion vehicles within North America. If your trip is outside of North America, see the section above on vehicles outside of North America. or, if the trip is using an electric vehicle, see the section on electric vehicles which is globally applicable.

  • vehicle_typerequired string
    Default value: general

    The type of vehicle that is used for the transportation. All valid values are: auto_carrier, dray, expedited, flatbed, general, heavy_bulk, ltl_or_dry_van, mixed, moving, package, refrigerated, specialized, tanker, tl_or_dry_van, van

Road (Electric Vehicles)

A leg with the "transport_mode": "road", with an electric car can specify further details about the journey by including this object under leg_details. If the fuel_source is electricity, the vehicle is considered an electric vehicle.

These options are valid globally (both inside and outside of North America), but only apply to electric vehicles. If your transportation uses combustion engine, see the above sections

Different vehicle_types have different requirements and options. Please consult the table further down for the list of valid parameter combinations.

  • fuel_sourcerequired string

    Must be electricity for electric vehicles.

  • vehicle_typerequired string

    The type of vehicle that is used for the transportation. All valid values are: van, rigid_truck

  • vehicle_weightrequired string

    The carrying capacity of the vehicle, as a string specifying the range. E.g. gt_34t_lte_40tmeans a carrying capacity greater than 34tonnes and less than or equal to 40tonnes. Refer to the table below for all valid combinations of values.

  • load_typestring
    Default value: Average

    The type of load the vehicle carries. Valid values vary depending on the vehicle type, but all valid values are: light

Valid parameter combinations (Electric only)

Please consult this table to see what valid combinations of values are then using Electric trucks worldwide:

fuel_source Parametervehicle_type Parametervehicle_weight Parameterload_type Parameter
electricityrigid_truckgt_3.5t_lte_7.5t, gt_7.5t_lte_12t, gt_12t_lte_20t gt_26t_lte_40tlight, null
electricityvanlte_3.5tnull

Sea

A leg with the "transport_mode": "sea", can specify further details about the journey by including this object under leg_details.

  • vessel_typerequired string
    Default value: container

    The type of vessel that is used for the transportation. Refer to the table below for all valid combinations of values.

  • tonnagestring

    The tonnage the ship can carry, as a string specifying the range E.g. gte_5dwkt_lt_10dwkt means more than (or equal to) 5 deadweight kilotonnes, and less than 10 deadweight kilotonnes. You might also see the abbreviation gt for gross tonnage. Refer to the table below for all valid combinations of values.

  • fuel_sourcestring

    The type of fuel that the ship uses. Refer to the table below for all valid combinations of values.

Valid parameter combinations

Please consult this table to see what valid combinations of values are:

vessel_type Parametertonnage Parameterfuel_source Parameter
containernullnull
bulk_carrier

lt_10dwkt, gte_10dwkt_lt_35dwkt, gte_35dwkt_lt_60dwkt, gte_60dwkt_lt_100dwkt, gte_100dwkt_lt_200dwkt, gte_200dwkt

hfo, vlsfo, mdo
chemical_tankerlt_5dwkt, gte_5dwkt_lt_10dwkt, gte_10dwkt_lt_20dwkt, gte_20dwkt_lt_40dwkt, gte_40dwkthfo, vlsfo, mdo
ferry_ropaxlt_2000gt, gte_2000gt_lt_5000gt, gte_5000gt_lt_10000gt, gte_10000gt_lt_20000gt, gte_20000gthfo, vlsfo, mdo
general_cargolt_5dwkt, gte_5dwkt_lt_10dwkt, gte_10dwkt_lt_20dwkt, gte_20dwkthfo, vlsfo, mdo
liquefied_gas_tankerlt_50000cbm, gte_50000cbm_lt_100000cbm, gte_100000cbm_lt_200000cbm, gte_200000cbmhfo, vlsfo, mdo
oil_tankerlt_5dwkt, gte_5dwkt_lt_10dwkt, gte_10dwkt_lt_20dwkt, gte_20dwkt_lt_60dwkt, gte_60dwkt_lt_80dwkt, gte_80dwkt_lt_120dwkt, gte_120dwkt_lt_200dwkt, gte_200dwkthfo, vlsfo, mdo
other_liquids_tankerslt_1dwkt, gte_1dwkthfo, vlsfo, mdo
refrigerated_bulklt_2dwkt, gte_2dwkt_lt_6dwkt, gte_6dwkt_lt_10dwkt, gte_10dwkthfo, vlsfo, mdo
ro_rolt_5dwkt, gte_5dwkt_lt_10dwkt, gte_10dwkt_lt_15dwkt, gte_15dwkthfo, vlsfo, mdo
vehiclelt_30000gt, gte_30000gt_lt_50000gt, gte_50000gthfo, vlsfo, mdo
⚠️
Roll on - Roll off (ro-ro) vessel type behavior

The emission factors for the ro_ro (Roll on - Roll off) vessel type are calculated differently than other types of vessels. For ro_ro vessels, the weight should include both the vehicle and any cargo it carries. In contrast, for other vessel types, only the weight of the cargo should be considered.

If you're shipping cargo using a vehicle on a ro_ro vessel, you'll need to adjust your API request accordingly. You may also choose to attribute only a portion of the emissions to yourself if you are transporting only part of the vehicle's cargo.

Please note that the Climatiq API does not automatically select ro_ro vessels as the default option, so you only need to take this into account if you explicitly choose this vessel type.

Air

A leg with the "transport_mode": "air", can specify further details about the journey by including this object under leg_details.

  • aircraft_typestring
    Default value: Average

    The aircraft type used to carry the shipment. Use freighter if it is a dedicated cargo plane, or belly_freight if it is transported in the belly of a passenger plane.

  • radiative_forcing_indexfloat
    Default value: 2

    The radiative forcing index to multiply the emissions by (see info box below). If you do not want a radiative forcing index to be applied, you may specify 1

Air travel and radiative forcing

GLEC default emission factors do not include a Radiative Forcing Index (RFI) (opens in a new tab). RFIs are applied to account for the increased impact on global heating made by greenhouse gases released directly into the upper atmosphere by aircraft. RFI values depend on things like altitude and trip length and are subject to uncertainty and disagreements. To perform the most accurate calculations, this endpoint currently applies an RFI of 2 to all flights, based on the latest available science (opens in a new tab). If a Radiative Forcing Index has been applied, a notice will be returned.

Rail

A leg with the "transport_mode": "rail"; you can specify further details about the journey by including this object under leg_details.

  • fuel_sourcestring
    Default value: Regional average or default

    The fuel type that the train runs on. Valid values are diesel, electricity; do not include if hybrid or unknown (an averaged factor will be applied). electric can only be specified for journeys within Europe or Asia.

  • load_typestring
    Default value: Average

    The load that the train is carrying. Valid values are building_materials, cars, cereals, chemicals, coal_steel, container, manufactured_products, trailer_only_on_train, truck_plus_trailer_on_train

  • preview_routingboolean
    Default value: false

    Whether or not to enable the new rail routing that has global coverage. This will become the default in the future.

Rail freight outside of Europe

We have not yet implemented network distance calculations for rail outside of Europe; in the interim we fallback to using the great circle distance between the points.

The GLEC emission factors have a good coverage of Europe, with diesel and electric options and different load types represented. US has more basic factors , while for the rest of the world, in absence of applicable factors, under GLEC guidance we fall back to using a factor reflecting the European average.

Notices should be present in your response if your query has hit any of these limitations.

Location

A trip always has two or more locations.

Request Location AttributesRequired
location Location
Either a QueryLocation, an IataCodeLocation, an UNLocodeLocation or a CoordinateLocation
required
location_options Location Options
Extra options that a location can have. See section below.
optional

Query Location

Query Location AttributesRequired
query string
A free text query describing the location, such as "Berlin, Germany", or "10 Downing Street".
optional
country string
The 2-letter ISO-3166 country code (opens in a new tab) for a given location.
optional
postal_code string
The postal (or zip) code for the given location. If used, country or query must also be specified.
optional

All the properties are optional, but you must specify at least a query or a country + postal_code. You may specify all three. Note that not all countries have support for postal codes, and the format might be different from country to country. See this table (opens in a new tab) for details on postal codes.

IATA Code Location

IataLocation AttributesRequired
iata string
An IATA airport code.
required

UN/LOCODE Location

UNLocode Location AttributesRequired
locode string
An UN/LOCODE (opens in a new tab) of the format DE-BER for Berlin. The Locode must contain both country and location.
required

Coordinate Location

Coordinate Location AttributesRequired
longitude float
The longitude of the coordinate.
required
latitude float
The latitude of the coordinate.
required
country string
Climatiq automatically determines the country the coordinates are within. If you need to, you can override this selection by supplying a 2-letter country code.
optional

Location Options

There are other options that are sometimes relevant to change. If a location is adjacent to a fixed-transition point leg, Climatiq automatically makes small corrections to turn your provided location into the proper port, airport or railway station. See Automatic Location Correction for more details.

Location Options AttributesRequiredDefault
override_transition boolean
If the location is known to be valid for transition between different modalities, for example when providing the coordinates of a private railway terminal or dock, this overrides our attempts to automatically correct the location to a known fixed transition point and prevents errors.
optionalfalse
tolerance_km float
The maximum distance, in km, that we would correct a location to match a mixed transition point. Increasing this can help with some errors which occur with very large ports, etc. for which different locations may be identified.
optional10
logistics_hubs_type string
The type of logistics hub operation performed at this location, if you wish to override the default. Logistics hubs are where freight is stored and processed, and where freight is moved between vehicles. Valid values are: none, transshipment, storage_and_transshipment, warehouse, liquid_bulk_terminals and maritime_container_terminals. Refrigerated variants exist for all these values, and are selected if the cargo is marked as refrigerated.
optionaltransshipment unless one of the adjacent legs is sea container shipping, then maritime_container_terminals

Response Models

These are more in-depth explanations of the models returned by the intermodal freight endpoint.

ResponseLocation

The location in the route array of the response will contain the following properties

Response Location attributes
type "location"
constant to easily show whether the item is a location or leg
co2e float
The carbon dioxide equivalent emitted for the operation of logistics hubs at this location. This encompasses both operational and energy provisioning emissions. 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.
co2e_calculation_method string or null
Which calculation methodology that was used for the calculation. The value of this is either "ipcc_ar4_gwp100", "ipcc_ar5_gwp100", "ipcc_ar6_gwp100", "ipcc_mixed_gwp100" or null (if the request specified that no transshipment should be estimated).
Learn more about calculation methods here.
co2e_unit string
The unit in which the CO2e fields is expressed. The value of this is always kg
name string
A human-readable name of the location
latitude string or null
The latitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
longitude string or null
The longitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
confidence_score float
A confidence score between 0 and 1, determining how certain we are that the location matches your query. Only exists if the input location was a QueryLocation
source_trail array of SourceDataPoint
An array of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.

ResponseLeg

The leg in the route array of the response will contain the following properties

Response Leg attributes
type "leg"
constant to easily show whether the item is a location or leg
co2e float
The total carbon dioxide equivalent emitted for this leg of the trip. This encompasses both vehicle operations and vehicle energy provisioning.
co2e_calculation_method string
Which calculation methodology that was used for the calculation. The value of this is either ipcc_ar4_gwp100, ipcc_ar5_gwp100, ipcc_ar6_gwp100 or ipcc_mixed_gwp100.
Learn more about calculation methods here.
co2e_unit string
The unit in which the CO2e fields is expressed. The value of this is always kg
vehicle_operation_co2e float
The carbon dioxide equivalent emitted for the part of the trip where the vehicle is being operated, such as the combustion of fuel, leakage of refrigerants etc.
vehicle_energy_provision_co2e float
The carbon dioxide equivalent emitted for the provisioning of energy for the vehicle operations. This covers among others: electricity generation, electricity transmission and distribution losses, the production of fuel, and the transportation of fuel to the vehicle.
transport_mode string
What transport mode this leg corresponds to. Will be "road", "air", "sea" or "rail"
distance_km float
The distance in kilometers for this leg of the trip.
source_trail array of SourceDataPoint
An array of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.

Notice

The notices array can contain these objects:

Notice attributes
severity string
Either warning or info. warning is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. info is for information that will help you understand the calculation result better.
message string
An explanation of the notice.
leg_index integer
An optional number describing which leg of the journey this notice belongs to.
code string
A programmatic value you can use to disambiguate the different notice types.

The different possible values for code are as follows. You should not treat this list as exhaustive as more values may be added with time:

Notice code valuedescription
great_circle_distance_usedGreat Circle Distance was used for the whole route in absence of more detailed routing capability.
truck_ferry_usedThe truck used for the journey was put on a ferry for part of the journey, sea factors were used for the covered distance
truck_rail_usedThe truck used for the journey was put on a train for part of the journey, rail factors were used for the covered distance
partial_great_circle_distance_usedWe were not able to route all parts successfully. Parts of the route were filled with great circle distance calculations.
region_fallbackFactors or calculation methods for the exact region are not available, we have used a fallback region which we believe best covers the specified region
radiative_forcing_appliedAn adjustment was applied to the co2e of the estimate, due to the effects of radiative forcing.
global_electricity_factor_usedA country-specific electricity factor wasn't available, so global was used instead.