Intermodal Freight Endpoint version: V3 (preview 1)V3 (preview 1) 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.

Estimate

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

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

Request

This endpoint accepts the following parameters:

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

Response

A response consists of the following attributes.

{
    "co2e": 2951,
    "hub_equipment_co2e": 26,
    "vehicle_operation_co2e": 2216,
    "vehicle_energy_provision_co2e": 708.8,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ipcc_ar6_gwp100",
    "cargo_tonnes": 10,
    "distance_km": 290.5,
    "route": [
        {
            "type": "location",
            "co2e": 13,
            "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.1",
                    "year": "2024",
                    "region": "GLOBAL",
                    "region_name": "Global",
                    "id": "6207e899-11d9-425e-a3d7-10f7bb1b17cb"
                }
            ],
            "name": "Hamburg, Germany",
            "latitude": 53.55562,
            "longitude": 9.98745,
            "confidence_score": 1
        },
        {
            "type": "leg",
            "co2e": 2925,
            "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.1",
                    "year": "2024",
                    "region": "EU_S_AMERICA",
                    "region_name": "Europe and South America",
                    "id": "20f49f02-821e-49a7-a98d-55158f48ef28"
                },
                {
                    "data_category": "emission_factor",
                    "name": "Van <3.5t - Petrol",
                    "source": "GLEC",
                    "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.1",
                    "year": "2024",
                    "region": "EU_S_AMERICA",
                    "region_name": "Europe and South America",
                    "id": "bac33059-8af3-4099-b6b6-741218db6ab9"
                }
            ],
            "vehicle_operation_co2e": 2216,
            "vehicle_energy_provision_co2e": 708.8,
            "transport_mode": "road",
            "distance_km": 290.5,
            "notices": []
        },
        {
            "type": "location",
            "co2e": 13,
            "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.1",
                    "year": "2024",
                    "region": "GLOBAL",
                    "region_name": "Global",
                    "id": "6207e899-11d9-425e-a3d7-10f7bb1b17cb"
                }
            ],
            "name": "Berlin, Germany",
            "latitude": 52.51604,
            "longitude": 13.37691,
            "confidence_score": 1
        }
    ]
}

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

A leg with the "transport_mode": "road" can include more specific journey details through the leg_details object.

As GLEC uses different methodologies and sources for North America, China, and the rest of the world, the parameters you can provide are different for these regions. The API allows you to provide parameters for all regions, and the API will only use the relevant one, depending on the actual trip taken.

For more information on vehicle types for road transport, see the vehicle types section.

• north_americaobject

  Default value: See here

  Details used for trips within North America. These parameters can always be provided, but will only apply to road legs within North America. Use this object for combustion vehicles or this object for electric vehicles.

  Default Value

  See here
• chinaobject

  Default value: See here

  Details used for trips within China. These parameters can always be provided, but will only apply to road legs within China. Use this object for all vehicles.

  Default Value

  See here
• rest_of_worldobject

  Default value: See here

  Details used for trips in other regions. These parameters can always be provided, but will only apply to road legs outside of North America and China. Use this object for combustion vehicles or this object for electric vehicles.

  Default Value

  See here

Road in China

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

• vehicle_typerequired string

  Default value: rigid_truck

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

  Default Value

  rigid_truck
• vehicle_weightrequired string

  Default value: gt_16t_lte_20t

  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.

  Default Value

  gt_16t_lte_20t
• fuel_sourcerequired string

  Default value: diesel

  The fuel source that the vehicle is running on. Valid values vary depending on the vehicle type, but all valid values are: diesel, lng, electricity, hydrogen

  Default Value

  diesel

Valid parameter combinations in China

Road in 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.north_america.

• 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

For electric vehicles in North America, see valid parameter combinations for electric vehicles in other regions.

Road in other regions

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

These options do not apply to trips within North America or China. If your trip is in one of these regions, see the corresponding section.

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: articulated_truck

  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

  Default Value

  articulated_truck
• vehicle_weightrequired string

  Default value: lte_34t

  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.

  Default Value

  lte_34t
• fuel_sourcerequired string

  Default value: diesel

  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

  Default Value

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

  Default Value

  Average

Valid parameter combinations in other regions

Please consult this table to see what valid combinations of values are for other regions, this includes electrical vehicles:

Valid parameter combinations (Electric only)

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

These options are valid globally (with the exception of China), 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

  Default Value

  Average

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

Vehicle types

Here is an overview of some of the different types of vehicle:

Sea

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

• vessel_typestring

  Default value: container

  The type of vessel that is used for the transportation. Refer to the table below for all valid combinations of values. See Typical vessel types by cargo for an overview of what types of cargo typically go on which kind of vessel.

  Default Value

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

• avoid_zonesarray of strings

  Default value: [northeast, northwest, magellan, kiel, corinth, bering]

  Sea zones to avoid in the routing step. Any sea passage in this array is disregarded during routing and port discovery, i.e. sea lanes and ports located in such a passage are not used. If this is null or unspecified, the default value is used. The following sea routes are available: northeast, northwest, dover, magellan, suez, panama, kiel, corinth, malacca, bering, babelmandeb, gibraltar. It is recommended to consider the default values when specifying this parameter, i.e. if you want to block the Panama Canal, extend the default array by panama instead of just sending [panama].

  Default Value

  [northeast, northwest, magellan, kiel, corinth, bering]

Valid parameter combinations

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

Typical vessel types by cargo

The following table stems from the Fourth IMO Greenhouse Gas Study (opens in a new tab). It lists examples of cargo types and appropriate vessel types to transport them with.

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: Unknown

  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

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

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). electricity can only be specified for journeys within Europe or Asia.

  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

Location

A trip always has two or more locations.

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.

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

ResponseLeg

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

Notice

The notices array can contain these objects:

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:

FAQ

What's the difference between using automatic routing versus specifying exact locations for each leg of my route?

Automatic routing allows you to omit intermediate locations and let the API find the closest ports, airports, or rail stations automatically. See more details here

When you specify exact locations, you have full control over which specific ports, airports, or terminals to use, and you can define the exact route path your shipment takes. This is particularly useful for private terminals or non-standard locations.

Use automatic routing when you don't know exact port or airport locations, want simplified route specification, or trust the API's location selection. Use exact locations when: your route contains specific terminals or hubs, when automatic selection picks wrong locations, or when you're using private facilities (in which case you should set override_transition: true).

How should I handle the regional differences in parameter availability, like North America vs rest of world for road transport?

The simplest approach is to provide both parameter objects and let the API use the appropriate one. For road transport, you can include both north_america and rest_of_world objects in your request:

{
    "transport_mode": "road",
    "leg_details": {
        "north_america": {
            "vehicle_type": "general"
        },
        "rest_of_world": {
            "vehicle_type": "articulated_truck",
            "vehicle_weight": "lte_34t",
            "fuel_source": "diesel"
        }
    }
}

The API automatically uses north_america parameters for routes within North America, uses the default values for china as no object was provided and uses rest_of_world parameters for routes outside of those regions. This way your application will use the correct parameters, and you don't need to know where your routes are located ahead of time.

When calculating emissions for a large shipment, should I use the total weight or break it down by individual items? Does it make a difference?

If the route and the cargo type is identical, use the total weight - breaking down by individual items doesn't change the emission calculation. Since emission factors scale linearly with weight and all items follow the same route with the same emission factors, using total weight is more computationally efficient with one API call instead of multiple.

You might want to break it down when items take different routes, use different transport modes (some by air, others by sea), have different characteristics (some refrigerated, others ambient), or when you need separate reporting for individual item carbon footprints. As a best practice, use total weight for efficiency unless you have specific business requirements for item-level tracking.

What if I don't know the main transport type for my shipment?

The API requires you to input a main transport type. If you do not know one, you can attempt to make a qualified guess:

• For longer routes and international shipping, sea is a good first guess. Around 80% of global freight moves via the ocean (opens in a new tab).
• For shorter inland routes, or last-mile delivery, road freight is the most common.
• For large volumes of goods, particularly across Europe or North America, rail transportation is also popular.
• Air freight is mostly used for time-sensitive or highly valuable cargo.

How do I handle last mile delivery in my route calculations?

If you know your distribution center, you can handle last-mile delivery like this:

• First API call
• Transport the goods from your production center to your delivery hub
• Second API call
• Transport the goods from your delivery hub to your end-user

By default, the API supports 3 legs per trip, requiring you to use 2 calls. If you need to handle last-mile delivery, you can also contact Climatiq to have this limit raised, allowing you to handle the entire trip in one call.

What should I do if the API picks a port or airport that wouldn't be the right one for my shipment?

If you know the airport or port that is used for a shipment, you should specify it explicitly in the API request. That way you will get the most appropriate route for your shipment.

Do I need to account for empty return trips when calculating emissions?

You do not. The GLEC emission factors we use already account for things like idle-running and empty return trips.

How do I handle cases where I get an error that no coordinates are found for a valid LOCODE?

Please contact Climatiq, and we might be able to update our internal LOCODE database. As a temporary workaround, you can use a CoordinateLocation to manually specify the coordinates.

Does the API account for vehicle idling time in the emission calculations?

Yes, the GLEC emission factors we use already account for things like idle-running and empty return trips.

Does the location input mean anything in a request if we're also using planned_distance_km?

Yes, the location input still matter even when overriding the calculated distance using planned_distance_km, as the API uses the locations to determine the appropriate emission factors to use.

For Scope 2 electric vehicles, should I use the Energy or the Freight feature?

It depends on what data you have available and how you want to use the data:

• If you know the total electricity (kWh) consumed by the electric vehicle, allocated to your particular package, you should use the Energy feature, as it will be more accurate for Scope 2 calculations.
• If you only have the shipping details, such as the cargo weight and location/destination, you should use the Freight feature. It will estimate the electricity consumption based on the journey specifics.
• If you know the total electricity consumed by the electric vehicle, but not how much of it can be allocated to your specific package, you can either:
• Figure out how to allocate parts of the electricity consumption to your package, if you need to report carbon emissions per shipment. You can then use the Energy feature to calculate the emissions per package.
• Use the energy endpoint to calculate the emissions for the entire truck, e.g. if all packages in the truck belong to you, and you do not need per-package emissions.
• Use the Freight feature if none of the above options makes sense for you, e.g. if you cannot perform allocation, or part of the shipping route is not electrified.

If you have both electricity consumption per package and shipping details, you should prefer the energy endpoint for Scope 2 reporting, as the estimate will be more accurate and granular.