Intermodal Freight Endpoint version: V2V2 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://api.climatiq.io/freight/v2/intermodal

Request

This endpoint accepts the following parameters:

curl --request POST \
--url https://api.climatiq.io/freight/v2/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"
                }
            }
        },
        { "location": { "query": "Berlin" } }
    ],
    "cargo": {
        "weight": 10,
        "weight_unit": "t"
    }
}'

Response

A response consists of the following attributes.

{
    "co2e": 2781,
    "hub_equipment_co2e": 12,
    "vehicle_operation_co2e": 2099,
    "vehicle_energy_provision_co2e": 671,
    "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": 2099,
            "vehicle_energy_provision_co2e": 671,
            "transport_mode": "road",
            "distance_km": 285.5,
            "notices": []
        },
        {
            "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
        }
    ]
}

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 for North America and the rest of the world, the parameters you can provide are different for these two regions. The API allows you to provide parameters for both regions, and the API will only use the relevant one, depending on the actual trip taken.

• rest_of_worldobject

  Default value: See here

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

  Default Value

  See here
• 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

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

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 work for both regions.

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

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

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 works for both regions.

• 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

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 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 (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

  Default Value

  Average

Valid parameter combinations (Electric only)

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

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.

  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.

Valid parameter combinations

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

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: