Use ROAD transport operations to calculate emissions for cargo moved by road vehicle.
Road transport operations model cargo moved by road vehicle between locations.
Set the transport operation type to ROAD within a transport chain when a shipment leg is moved by truck, van, or another commercial road vehicle.Road calculations are most representative when the request provides the vehicle and loading details directly.
If these are omitted, TerraTwin selects suitable defaults using the route’s region of operation and relevant cargo properties, such as category, packaging, and density characteristics.
Mode
Use type: "ROAD" in a transportChain transport element.TerraTwin treats that element as a requested road leg between the surrounding transport chain locations.
Vehicle
Use grossWeightBand, grossWeight, maximumWeight, or emptyWeight when you know the vehicle size.If the exact size is unknown, use vehicle, structure, and packaging to help TerraTwin select a suitable default.
Loading
Use loadDistribution, loadFactor, and emptyRunning when you know how the vehicle capacity was used for the shipment.If loadFactor or emptyRunning are omitted, TerraTwin applies defaults based on the region of operation, selected vehicle class, packaging, and cargo density.
Primary data
Use energyConsumption when measured fuel, electricity, or efficiency data is available.Supplying energy consumption switches the calculation from vehicle modelled emissions to consumption based primary data.
A requested ROAD transport element may be realized as several sub-operations in the response when the road route includes roll-on/roll-off ferry or rail movements.
For example, a road route from France to Great Britain may include a Channel Tunnel rail sub-operation.
In this request, the transport mode is specified by the type property on the transport operation.Because no vehicle details are supplied, TerraTwin selects a default road vehicle from the origin country, cargo, trip, and routing context. In this case, the operation is modelled as an ARTICULATED_TRUCK_34000_TO_40000_KG with EURO_6AC emissions standard, fleet-average vehicle age, LTL load distribution, 72% load factor, and 30% empty running.
Aberdeen to Castlebay on the Isle of Barra
The more information you can provide about the road vehicle and loading, the more accurately TerraTwin can model the operation.For example, if the shipment moved as palletized cargo on a Swedish high-capacity articulated truck operating on BK4 roads, as part of a shared-load distribution journey, with a 64% load factor and 50% empty running, provide those vehicle and loading details directly.
Route locations, region of operation, departureDateTime, arrivalDateTime
The sections below describe how these properties are used and which ones take priority when several are provided.
Property
Required
What it does
type
Yes
Selects road transport. Use ROAD.
departureDateTime
No
The date and time the road vehicle departed the start location.
arrivalDateTime
No
The date and time the road vehicle arrived at the end location.
vehicle
No
Broad vehicle category used when only limited information is available. Less specific than weight-based vehicle selection.
structure
No
Vehicle configuration: ARTICULATED, RIGID, or DUMP. Used with weight and cargo category to refine vehicle selection.
grossWeightBand
No
Banded gross vehicle weight. Highest priority vehicle size input. Takes precedence over grossWeight when both are supplied.
grossWeight
No
Total vehicle weight at the time of measurement, including vehicle, cargo, and equipment.
maximumWeight
No
Maximum permitted or gross allowable vehicle weight. TerraTwin converts it into an estimated gross weight before vehicle selection.
emptyWeight
No
Unladen or tare weight of the vehicle. TerraTwin converts it into an estimated gross weight before vehicle selection.
yearOfManufacture
No
Vehicle manufacture year. If unsupported or omitted, TerraTwin uses a weighted vehicle age aggregation.
emissionsStandard
No
Vehicle emissions class, such as EURO_6 or EURO_6DE. If unsupported for the vehicle, energy, and year, the closest supported class is used.
loadFactor
No
Percentage utilization of vehicle capacity. Must be greater than 0. If omitted, TerraTwin defaults it from the selected vehicle and road model context.
emptyRunning
No
Percentage of distance completed without carrying a load. Must be at least 0 and less than 100.
packaging
No
Cargo packaging format. Use CONTAINER or PALLET. Used to help select an appropriate road vehicle and loading assumptions.
energyType
No
Propulsion energy. Use DIESEL, GASOLINE, ELECTRICITY, LNG, LPG, CNG, or HVO100.
loadDistribution
No
Cargo’s share of vehicle load. Use LTL or FTL. Defaults to LTL.
energyConsumption
No
Measured or calculated fuel, electricity, or efficiency data. When provided, TerraTwin calculates emissions from consumption as primary data.
id
No
Optional identifier for the transport operation. Returned on the corresponding result element.
context
No
Caller-provided metadata returned with the corresponding result element. Preserved if the road operation falls back to another mode.
The mode is selected with the type property on a transport operation:
{ "transportChain": [ { "type": "ROAD" } ]}
The road operation runs between the nearest chain boundaries.
Those boundaries come from the top-level origin and destination, or from surrounding HUB elements in a larger transportChain.
In this example, the HUB elements explicitly separates the road legs and the water leg.
Manchester to Dresden via the London Gateway [GBSHV] and Port of Szczecin [PLSZZ]
Use separate ROAD operations with an explicit HUB when the cargo is actually handled between vehicles, depots, or transport providers.
See the logistics hubs guide for choosing the hub location and hubType, and for controlling automatic hub insertion.Do not split out roll-on/roll-off ferry or train movements as separate transport chain operations when the cargo remains on the road vehicle, trailer, or swap body; TerraTwin includes those movements as sub-operations of the road route.
There are several ways to influence road vehicle selection.
You do not need to provide all of them.
In general, the more direct the vehicle size input, the more precise the selected road vehicle classification.Vehicle selection starts with the region of operation. TerraTwin determines this from the starting point of the road transport operation, then applies any supplied vehicle properties within that regional vehicle system.The supported road vehicle regions are:
North America
Europe
South America
India
China
Rest of Asia
Africa
After the region has been determined, TerraTwin applies the available vehicle inputs in priority order:
Priority
Inputs provided
Selection behavior
1
grossWeightBand and, optionally, structure
Uses the supplied gross vehicle weight band within the regional vehicle system. TerraTwin handles conversion between regional weight band systems automatically.
2
grossWeight and, optionally, structure
Uses the measured gross vehicle weight, then selects the matching vehicle class for the region.
3
maximumWeight and, optionally, structure
Converts maximum permitted weight into an estimated gross vehicle weight, then selects a vehicle class for the region.
4
emptyWeight and, optionally, structure
Converts empty or tare weight into an estimated gross vehicle weight, then selects a vehicle class for the region.
5
vehicle
Uses a broad vehicle category within the regional vehicle system. This is useful when only a general vehicle size is known, but is less precise than weight based selection.
6
structure
Selects from the requested structure where possible. ARTICULATED selects an articulated vehicle, RIGID selects a rigid vehicle, and DUMP selects a dump truck (China only)).
7
packaging
If packaging is CONTAINER, TerraTwin selects a container capable vehicle where no more specific vehicle information is available.
8
Country of origin
If no earlier rule selects a vehicle, TerraTwin defaults from the most common road freight vehicle in the country where the trip begins.
cargo.category can also influence road vehicle selection even though it is not a property of the road operation itself.
For example, BUILDING_MATERIALS may cause TerraTwin to prefer a dump truck vehicle where that is supported, while typically containerized cargo categories can lead to different vehicle and loading assumptions.
Use grossWeightBand when you know the road vehicle’s gross vehicle weight range.
This is the highest-priority vehicle size input.
When both grossWeightBand and grossWeight are supplied, grossWeightBand takes precedence.
Gross weight bands are related to the region of operation.
Different vehicle class systems are used in different regions.
TerraTwin handles conversion between these bands automatically, so you can provide the band you have and let the calculation map it to the most appropriate local vehicle class for the route.
If structure is not supplied with a weight input, TerraTwin infers it from the vehicle weight and cargo.category.
If structure is supplied without a vehicle weight input, it is used as a lower priority selector.
A requested DUMP structure is used where supported by the operating region; otherwise TerraTwin maps the request to the closest rigid vehicle class.
Use vehicle when you only know the general road vehicle size.
This is less precise than using grossWeightBand, grossWeight, maximumWeight, or emptyWeight, but it is useful for sparse carrier data.
Vehicle
Description
LCV_BELOW_3500_KG
Van or light commercial vehicle below 3.5 tonnes gross vehicle weight.
LCV_BELOW_8500_LB
North American van or light commercial vehicle below 8,500 lb gross vehicle weight.
LIGHT_DUTY_VEHICLE
Generic small distribution or service vehicle.
MEDIUM_DUTY_VEHICLE
Generic medium-sized truck for moderate freight movement.
HEAVY_DUTY_VEHICLE
Generic high-capacity vehicle for long-haul or heavy cargo.
packaging helps TerraTwin choose vehicle and loading assumptions when more specific vehicle data is not available.
It also affects loadFactor and emptyRunning defaults, because utilisation patterns vary by freight configuration.
Packaging
What it represents
CONTAINER
Cargo packed in a standard shipping container, such as a TEU, FEU, or tank container.
PALLET
Cargo packed on standard pallets, such as GMA, EUR, or ISO pallets.
{ "type": "ROAD", "packaging": "CONTAINER"}
If packaging is CONTAINER and no stronger vehicle selection input is provided, TerraTwin selects a container capable road vehicle.
If the cargo is not containerized or palletized, such as loose parcels, omit packaging.
Road emissions depend not only on the vehicle, but also on how that vehicle was used.
TerraTwin models this with loadDistribution, loadFactor, and emptyRunning.
loadDistribution describes whether the shipment shared vehicle capacity with other cargo or had exclusive use of the vehicle.
Less than truckload
Use loadDistribution: "LTL" when the shipment uses part of the vehicle capacity and the remaining capacity is shared with other cargo.LTL is the default.
Full truckload
Use loadDistribution: "FTL" when the shipment has exclusive use of the vehicle.If the cargo exceeds vehicle capacity, TerraTwin assumes multiple trips.
loadFactor is the percentage utilization of vehicle capacity.
It must be greater than 0 and can be up to 200; values above 100 represent overloading.For LTL movements, loadFactor represents the overall vehicle utilization used to allocate emissions across the cargo sharing the vehicle.For FTL movements, loadFactor is ignored. The shipment has exclusive use of the vehicle, so the operation is allocated as full truckload.
emptyRunning is the share of total vehicle distance associated with the operation that was driven empty.TerraTwin uses the GLEC / Smart Freight Centre definition of empty running, based on the traveled distance associated with the operation: loaded distance plus empty distance.
Empty running is based on total traveled distance: loaded distance plus empty distance.
For example, a loaded outbound trip followed by an equally long empty return has 50% empty running:This is different from the EcoTransIT empty trip factor, which expresses empty distance relative to loaded distance:
The EcoTransIT empty trip factor is based on loaded distance only.
Under that convention, the same loaded outbound trip and empty return would have an empty trip factor of 100%, not 50%.
Do not provide an EcoTransIT-style empty trip factor as emptyRunning.EcoTransIT expresses empty distance relative to loaded distance, while TerraTwin uses the GLEC / Smart Freight Centre definition based on total travelled distance. Using an EcoTransIT value here will overstate empty running and overstate the calculated emissions.A value of 100 is not valid for emptyRunning, because it would mean the whole associated vehicle distance was empty.
If emptyRunning is omitted, TerraTwin defaults it for the road operation.If loadDistribution is LTL and loadFactor is omitted, TerraTwin also defaults loadFactor.
For FTL movements, loadFactor is not used because the shipment has exclusive use of the vehicle.TerraTwin sets these defaults from the operating context, including:
Energy type affects the emissions factor and the model or methodology that can be used for the selected vehicle.
For electric vehicles, electricity emissions are calculated using the relevant electricity emissions factors for the operation.
For fuel vehicles, the supported fuel type determines the well-to-tank and tank-to-wheel emissions factors.
Use yearOfManufacture and emissionsStandard when you know the vehicle age or regulatory emissions class.
These properties refine the selected vehicle’s emissions profile.
If yearOfManufacture is omitted, TerraTwin uses a country level weighted aggregation of vehicle years based on the national age distribution.
If the specified year is not supported, TerraTwin falls back to that country-level weighted aggregation.Supported emissionsStandard values are:
Value
Meaning
EURO_1
Euro I.
EURO_2
Euro II.
EURO_3
Euro III.
EURO_4
Euro IV.
EURO_5
Euro V.
EURO_6
Euro VI.
EURO_6AB
Euro VI step A or B.
EURO_6AC
Euro VI step A or C.
EURO_6C
Euro VI step C.
EURO_6D_TEMP
Euro VI step D-TEMP.
EURO_6DE
Euro VI step D or E.
EURO_7
Euro VII.
If the specified class is unsupported for the selected vehicle type, energy type, and year of manufacture, TerraTwin uses the closest supported class instead.If no emissions standard is provided, the class is defaulted from the origin country, vehicle type, and energy type where relevant.
By default, road emissions are calculated from the selected vehicle, route, fuel or energy type, load assumptions, and the applicable road emissions model (HBEFA 5.1 / MOVES 5.0) or default factors (GLEC 3.2).When energyConsumption is provided, TerraTwin switches to a consumption-based calculation.
The supplied consumption value is treated as primary data and combined with energyType to calculate emissions directly.
This example supplies an absolute fuel quantity for the road operation.
The calculation uses the diesel volume directly rather than estimating fuel use from the selected road vehicle model.You can also supply a consumption rate or efficiency value:
When consumption data is provided, the response uses a consumption based methodology and a primary data calculation basis.
Absolute values are treated as total energy for the operation, while rate based values are applied to the calculated road distance.
Make sure the energyConsumption unit is compatible with energyType.
For example, use KILOWATT_HOURS or an electrical rate with ELECTRICITY, not with DIESEL.
departureDateTime and arrivalDateTime are optional, but provide them when they are known.
They make emissions certificates and analytics more useful by linking results to the period in which the transport occurred.
Road routes can include non-road movements when the road vehicle, trailer, or swap body remains intact and is carried by another mode.
TerraTwin represents these as sub-operations of the parent ROAD operation rather than as separate transport chain operations.The supported cases are:
RO-RO rail
A road vehicle, trailer, or swap body is loaded onto a train.The Channel Tunnel shuttle is a typical example of this kind of road route sub-operation.
RO-RO ferry
A road vehicle is driven onto a ferry and driven off again at the destination terminal.The cargo remains on the vehicle, trailer, or swap body during the ferry crossing.
In the response, the parent road operation will include a subOperations array.
The sub-operations are returned in the order they occur and may include:
Sub-operation type
What it represents
Example vehicle values
ROAD
A road segment that connects to a RO-RO ferry or rail movement.
The same road vehicle as the parent road operation.
RAIL
A roll-on/roll-off or swap-body rail movement used inside a road route.
`ROAD` to the Westerland Autoverladung (vehicle shuttle train)
Cargo travels by road from postcode 25980 in eastern Sylt to the Westerland Autoverladung terminal, where the vehicle boards a roll-on/roll-off road-rail shuttle train.
25980 Sylt to Westerland Autoverladung
2
`RAIL` between Westerland Autoverladung and Niebüll Autoverladung
The vehicle remains loaded while it travels between Westerland and Niebüll on the roll-on/roll-off road-rail shuttle train.
Westerland Autoverladung to Niebüll Autoverladung
3
`ROAD` from Niebüll shuttle train station to the Ystad Ferry Terminal
Cargo continues by road from the Niebüll Autoverladung terminal to the Ystad Ferry Terminal in southern Sweden, ready for the next roll-on/roll-off ferry leg.
Niebüll Autoverladung to Ystad Ferry Terminal
4
`WATER` from the Ystad Ferry Terminal to the Port of Rønne
The cargo crosses from Ystad to Rønne by roll-on/roll-off ferry, with the cargo remaining on the vehicle throughout the sea leg.
Ystad Ferry Terminal to the Port of Rønne
5
`ROAD` from the Port of Rønne to Bornholm Museum
The journey by road from the port of Rønne to Bornholm Museum at Sankt Mortens Gade 29.
Port of Rønne to Bornholm Museum
No hubs are inserted between these sub-operations, because the cargo is not transshipped.
The freight remains on the same vehicle, trailer, or swap body, so the operation is still treated as one road movement that happens to use a RO-RO ferry or rail service for part of the route.
Use a separate RAIL or WATER transport operation only when the cargo is actually handled as rail freight or maritime cargo between rail yards or harbors.
If the truck uses a ferry or train as part of a continuous road journey, model the requested leg as ROAD and let TerraTwin include the RO-RO sub-operations.
By default, calculation results do not include the geometry of the calculated route.Set the top-level options.includeRoutePolylines property to true when you need the route geometry for mapping, visualization, or downstream spatial processing:
When enabled, the road result includes a route property containing a polyline encoded using the Google Encoded Polyline Algorithm Format.For a road journey that includes roll-on/roll-off rail or ferry sub-operations, the parent ROAD result’s route represents the complete route, including the sub-operation segments. The returned ROAD, RAIL, and WATER sub-operation results also include their corresponding route values.
includeRoutePolylines defaults to false. When it is omitted or set to false, the route properties are not included in the response.
Road routing can fail when TerraTwin cannot build a feasible road operation for the requested leg.
This can happen when the start or end location is on an island with no road or roll-on/roll-off access, or when there is no continuous route using roads, RO-RO ferries, and RO-RO trains between the locations.Use options.fallbackTransportModes to let TerraTwin switch to another transport mode when the requested road operation cannot be realized.
Fallback modes are tried in the order you provide, excluding ROAD because it is the mode that failed.
In this pattern, TerraTwin first attempts to calculate the leg as road transport.
If no feasible road route exists, it tries the fallback modes in order.
The first fallback mode that can be routed and calculated is returned.
Fallback attempts use the fallback mode’s own defaulted configuration.
If every fallback attempt fails, the API returns the error from the final fallback mode attempted.
Houston to Honolulu falls back to WATER transport
If a road operation fails and TerraTwin uses a fallback mode instead, any id or context provided on the failed road operation is preserved and returned with the replacement operation’s result.
Use type: "ROAD" in the transport operation when the leg is known to move by road vehicle.
2
Prefer vehicle weight information
Provide grossWeightBand when available. If not, provide grossWeight, maximumWeight, or emptyWeight with units.
3
Add structure when known
Use ARTICULATED, RIGID, or DUMP to distinguish the vehicle configuration. This improves vehicle classification, especially when combined with a weight input.
4
Use the source region's weight band
Gross weight bands are region-sensitive. Use the band available in your source data; TerraTwin maps it to the appropriate local equivalent for the route.
5
Review loading assumptions
Provide loadDistribution, loadFactor, and emptyRunning when known. Otherwise let TerraTwin apply consistent defaults for the selected vehicle, region, and packaging.
6
Set energy type
Provide energyType when the vehicle fuel or energy is known.
If omitted, TerraTwin selects the most common energy type for the country of operation and vehicle size.
7
Use consumption data when available
Provide energyConsumption for measured fuel, electricity, or efficiency data. This switches the road calculation to consumption based primary data.
8
Provide dates when available
Add departureDateTime or arrivalDateTime when known. Dates improve reporting, certificates, analytics, and time-based interpretation.
9
Let RO-RO stay inside road
Do not manually insert hubs for roll-on/roll-off ferry or rail segments where the cargo remains on the vehicle, trailer, or swap body. TerraTwin includes those as road sub-operations.
10
Include route geometry when needed
Set options.includeRoutePolylines to true when you need the calculated route in the response. Decode returned route values using the Google Encoded Polyline Algorithm Format.
11
Use fallback modes for uncertain routability
Add options.fallbackTransportModes when a requested road route may not be feasible and another mode should be attempted automatically.
