Intermodal Freight v1 ADD-ONADD-ON

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.

🚫

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: September 2025

⚠️

Read the guide 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

Estimate

POST Calculate total estimated emissions produced by shipping an amount of cargo by the specified route. This endpoint still has a few limitations. More information here.

https://api.climatiq.io/freight/v1/intermodal

Request

This endpoint accepts the following parameters:

Request parametersShould be sent as a JSON object in the body

cargorequired Weight object
The weight 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://api.climatiq.io/freight/v1/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"
            }
        },
        { "location": { "query": "Berlin" } }
    ],
    "cargo": {
        "weight": 10,
        "weight_unit": "t"
    }
}'

Response

A response consists of the following attributes.

Response parameters

co2enumber
The carbon dioxide equivalent emitted for the entire trip.
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.
routearray of ResponseLocations or ResponseLegs
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": 1945,
    "co2e_unit": "kg",
    "distance_km": 286,
    "route": [
        {
            "type": "location",
            "name": "Hamburg, Germany",
            "latitude": 53.55562,
            "longitude": 9.98745,
            "confidence_score": 1
        },
        {
            "type": "leg",
            "co2e": 1945,
            "co2e_unit": "kg",
            "co2e_calculation_method": "ipcc_ar4_gwp100",
            "source_trail": [
                {
                    "data_category": "emission_factor",
                    "name": "Van =< 3.5 t",
                    "source": "GLEC",
                    "source_dataset": "Default Fuel Efficiency and CO2e Intensity Factors",
                    "year": "2019",
                    "region": "EU_S_AMERICA",
                    "region_name": "Europe and South America"
                }
            ],
            "transport_mode": "road",
            "distance_km": 286,
            "estimates": [
                {
                    "co2e": 1945,
                    "co2e_unit": "kg",
                    "co2e_calculation_method": "ar4",
                    "co2e_calculation_origin": "source",
                    "emission_factor": {
                        "name": "Van =< 3.5 t",
                        "activity_id": "freight_vehicle-vehicle_type_van-fuel_source_na-vehicle_weight_lte_3.5t-distance_uplift_included",
                        "id": "221b2e08-6bf6-4c21-8357-4ca3bfa135ca",
                        "access_type": "public",
                        "source": "GLEC",
                        "source_dataset": "Default Fuel Efficiency and CO2e Intensity Factors",
                        "year": 2019,
                        "region": "EU_S_AMERICA",
                        "category": "Road Freight",
                        "source_lca_activity": "well_to_wheel",
                        "data_quality_flags": []
                    },
                    "constituent_gases": {
                        "co2e_total": 1945,
                        "co2e_other": null,
                        "co2": null,
                        "ch4": null,
                        "n2o": null
                    },
                    "activity_data": {
                        "activity_value": 2860,
                        "activity_unit": "tonne-km"
                    },
                    "audit_trail": "enabled"
                }
            ]
        },
        {
            "type": "location",
            "name": "Berlin, Germany",
            "latitude": 52.51604,
            "longitude": 13.37691,
            "confidence_score": 1
        }
    ],
    "notices": []
}

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.
distance_kmfloat
If you have an actual distance for this leg in kilometers you can input the distance here. Climatiq will then use this distance instead of the planned distance it would normally calculate. If you are calculating your own planned distance you can also supply it here. However to comply with the GLEC framework you should multiply any planned distances provided by 1.05263 for road travel and 1.17647 for sea travel. Adjustments for other modes of transportation are not needed.

Road (Except North America)

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

These options do not apply to trips within North America, where the input options are more limited. If your trip is in North America, see the section below.

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

vehicle_typerequired string
Default value: hgv
The type of vehicle that is used for the transportation. The values have a few abbreviations such as hgv meaning heavy goods vehicle and mgv meaning medium goods vehicle. articulated and rigid refers to truck types. refrigerated refers to whether or not the cargo is refrigerated.
All valid values are:

hgv, hgv_articulated, hgv_articulated_hpdi, hgv_articulated_hpdi_refrigerated, hgv_articulated_refrigerated, hgv_articulated_si_engine, hgv_articulated_si_engine_refrigerated, hgv_refrigerated, hgv_rigid, hgv_rigid_refrigerated, mgv, mgv_refrigerated, urban_truck, urban_truck_refrigerated, van, van_refrigerated
Default Value
hgv
vehicle_weightstring
Default value: gt_20t
The carrying capacity of the vehicle, as a string specifying the range. E.g. gt_60t_lt_72tmeans a carrying capacity greater than 60tons and less than 72tons. Valid values vary depending on the vehicle type, but all valid values are:

gt_20t, gt_34t_lt_40t, gt_40t_lt_44t, gt_44t_lt_60t, gt_60t_lt_72t, lt_34t, lt_40t, gt_12t_lt_20t, gt_20t_lt_26t, gt_3.5t_lt_7.5t, gt_7.5t_lt_12t, gt_26t_lt_32t, gt_7.5t_lt_20t, lte_3.5t, lt_3.5t
Default Value
gt_20t
fuel_sourcestring
Default value: Average
The fuel source that the vehicle is running on. Valid values vary depending on the vehicle type, but all valid values are: diesel_5_percent_biodiesel_blend, bio_lng_or_diesel, cng_or_diesel, lng_or_diesel, bio_lng, cng, lng, lpg, petrol
Default Value
Average
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: heavy, container, light.
Default Value
Average

Valid parameter combinations

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

`vehicle_type` Parameter	`vehicle_weight` Parameter	`fuel_source` Parameter	`load_type` Parameter
`hgv`, `hgv_refrigerated`	`gt_20t`	`null`	`null`
`hgv_articulated`, `hgv_articulated_refrigerated`	`lt_34t`	`diesel_5_percent_biodiesel_blend`	`container`, `null`
	`lt_40t`	`diesel_5_percent_biodiesel_blend`	`heavy`
	`gt_34t_lt_40t`	`diesel_5_percent_biodiesel_blend`	`container`, `null`
	`gt_40t_lt_44t`	`diesel_5_percent_biodiesel_blend`	`container`, `heavy`, `light`, `null`
	`gt_44t_lt_60t`	`diesel_5_percent_biodiesel_blend`	`container`, `heavy`, `null`
	`gt_60t_lt_72t`	`diesel_5_percent_biodiesel_blend`	`container`, `heavy`
`hgv_articulated_hpdi`, `hgv_articulated_hpdi_refrigerated`	`lt_40t`	`bio_lng_or_diesel`, `cng_or_diesel`, `lng_or_diesel`	`container`, `null`
`hgv_articulated_si_engine`, `hgv_articulated_si_engine_refrigerated`	`lt_40t`	`bio_lng`, `cng`, `lng`	`container`, `null`
`hgv_rigid`, `hgv_rigid_refrigerated`	`gt_3.5t_lt_7.5t`	`cng`, `diesel_5_percent_biodiesel_blend`	`null`
	`gt_7.5t_lt_12t`	`cng`, `diesel_5_percent_biodiesel_blend`	`null`
	`gt_12t_lt_20t`	`cng`, `diesel_5_percent_biodiesel_blend`, `lng`	`null`
	`gt_20t_lt_26t`	`cng`, `diesel_5_percent_biodiesel_blend`, `lng`	`null`
	`gt_26t_lt_32t`	`diesel_5_percent_biodiesel_blend`	`container`, `null`
`mgv`, `mgv_refrigerated`	`gt_7.5t_lt_20t`	`null`	`null`
`urban_truck`, `urban_truck_refrigerated`	`gt_3.5t_lt_7.5t`	`null`	`null`
`van`, `van_refrigerated`	`lte_3.5t`	`cng`, `diesel_5_percent_biodiesel_blend`, `lpg`, `petrol`, `null`	`null`

Road (North America)

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

These options only apply to trip inside North America. North American trips cannot specify other parameters than vehicle_type. If your trip is outside of North America, see the section above.

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
Default Value
general

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. All valid values are:
container, container_reefer_refrigerated, bulk_carrier, bulk_carrier_ignition_ship, bulk_carrier_medium_speed_ship, bulk_carrier_slow_speed_ship, general_cargo, oil_tanker, oil_tanker_ignition_ship, oil_tanker_medium_speed_ship, oil_tanker_slow_speed_ship, ro_pax, ro_ro
Default Value
container
tonnagestring
The tonnage the ship can carry, as a string specifying the range E.g. gt_10dwkt_lt_20dwkt means more than 10 deadweight kilotons, and less than 20 deadweight kilotons. Valid values vary depending on the vessel type, but all valid values are:
gt_100dwkt, gt_10dwkt_lt_100dwkt, lt_10dwkt, gt_10dwkt_lt_20dwkt, gt_200dwkt, gt_5dwkt_lt_60dwkt, gt_60dwkt_lt_200dwkt, lt_5dwkt
fuel_sourcestring
The type of fuel that the ship uses. Valid values vary depending on the vessel type, but all valid values are: hfo, mgo, lng
load_typestring
The type of load that the ship is carrying. Valid values vary depending on the vessel type, but all valid values are: heavy, trailer_only, truck_plus_trailer

Valid parameter combinations

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

`vessel_type` Parameter	`tonnage` Parameter	`fuel_source` Parameter	`load_type` Parameter
`container`, `container_reefer_refrigerated`	`null`	`null`	`null`
`bulk_carrier`	`lt_10dwkt`	`hfo`, `mgo`	`null`
	`gt_10dwkt_lt_100dwkt`, `gt_100dwkt`	`hfo`, `mgo`	`heavy, null`
`bulk_carrier_ignition_ship`, `bulk_carrier_slow_speed_ship`, `bulk_carrier_medium_speed_ship`	`gt_100dwkt`	`lng`	`heavy, null`
`general_cargo`	`lt_10dwkt`, `gt_10dwkt_lt_20dwkt`	`hfo`, `mgo`	`null`
`oil_tanker`	`lt_5dwkt`, `gt_5dwkt_lt_60dwkt`, `gt_60dwkt_lt_200dwkt`, `gt_200dwkt`	`hfo`, `mgo`	`heavy`
`oil_tanker_ignition_ship`, `oil_tanker_slow_speed_ship`, `oil_tanker_medium_speed_ship`	`gt_200dwkt`	`lng`	`heavy`
`ro_pax`	`null`	`hfo`, `mgo`	`null`
`ro_ro`	`null`	`hfo`, `mgo`	`null, trailer_only, truck_plus_trailer`

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.
Default Value
Average
methodologystring
Default value: en16258
The methodology used to calculate the emissions. Valid values are en16258 or iata_rp1678. Climatiq defaults to en16258 as we consider that the most valid of the two methods.
Default Value
en16258
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
Default Value
2

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_typestring
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)
Default Value
regional average or default
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
Default Value
Average

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 Attributes	Required
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 Attributes	Required
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 Attributes	Required
iata string An IATA airport code.	required

UN/LOCODE Location

UNLocode Location Attributes	Required
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 Attributes	Required
longitude number The longitude of the coordinate.	required
latitude number The latitude of the coordinate.	required
country number The 2-letter country code for the country that this coordinate is located within.	required

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 Attributes	Required	Default
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.	optional	`false`
tolerance_km number 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.	optional	`10`

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
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 number 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`

ResponseLeg

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

Response Leg attributes
co2e number The carbon dioxide equivalent emitted for this leg of the trip.
co2e_unit string The unit in which the co2e field is expressed. The value of this is always `kg`
co2e_calculation_method string Which calculation methodology that was used for the entire 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.
transport_mode string What transport mode this leg corresponds to. Will be `"road"`, `"air"`, `"sea"` or `"rail"`
distance_km number The distance in kilometers for this leg of the trip.
estimates array of Estimation An array of estimations performed to achieve the final co2e value for this leg. Depending on the LCA attributes of the relevant emission factors, this will generally be 1-2 emission factors. Climatiq will always prioritize giving you two emission factors for `well_to_tank` and `tank_to_wheel` if possible. For `road` routes where the truck takes a ferry, this might be more.
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 `critical` or `info`. `critical` 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 number 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 value	description
`distance_added`	Additional distance was added based on methodological recommendations
`great_circle_distance_used`	Great Circle Distance was used for the whole route in absence of more detailed routing capability.
`truck_ferry_used`	The 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_used`	The 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_used`	We were not able to route all parts successfully. Parts of the route were filled with great circle distance calculations.
`region_fallback`	Factors or calculation methods for the exact region are not available, we have used a fallback region which we believe best covers the specified region
`actual_distance_adjusted`	An adjustment was applied to the provided actual distance as the factors we are using are based on planned distance and the user provided an actual distance
`radiative_forcing_applied`	An adjustment was applied to the co2e of the estimate, due to the effects of radiative forcing.

Freight v2 Freight v2 (preview 1)