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.
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 562,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "HARBOR",
"UnLoCode": "SESTO"
},
"destination": {
"type": "PLACE",
"postcode": "652 24",
"countryCode": "SE"
},
"transportChain": [
{
"type": "ROAD",
"structure": "ARTICULATED",
"grossWeightBand": "64000_TO_72000_KG",
"energyType": "DIESEL",
"loadDistribution": "LTL",
"loadFactor": 64,
"emptyRunning": 50,
"packaging": "PALLET"
}
]
}
```
***
## Properties
Road transport has a large set of optional modelling inputs.
The most important inputs fall into four groups:
| Input group | Useful properties |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| Vehicle identity | `grossWeightBand`, `grossWeight`, `maximumWeight`, `emptyWeight`, `vehicle`, `structure` |
| Vehicle technology | `energyType`, `yearOfManufacture`, `emissionsStandard` |
| Loading and cargo context | `loadDistribution`, `loadFactor`, `emptyRunning`, `cargo.category`, `packaging` |
| Operating context | 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. |
***
## Selecting road as the mode
The mode is selected with the `type` property on a transport operation:
```json theme={null}
{
"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`.
```json theme={null}
{
"cargo": {
"weight": {
"value": 8,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "PLACE",
"postcode": "M13 9PL",
"countryCode": "GB"
},
"destination": {
"type": "PLACE",
"city": "Dresden",
"countryCode": "DE"
},
"transportChain": [
{
"type": "ROAD",
"structure": "RIGID",
"grossWeightBand": "20000_TO_26000_KG",
"energyType": "ELECTRICITY"
}, {
"type": "HUB",
"hubType": "MARITIME_TERMINAL",
"location": {
"type": "HARBOR",
"unLoCode": "GBSHV"
}
}, {
"type": "WATER",
}, {
"type": "HUB",
"hubType": "MARITIME_TERMINAL",
"location": {
"type": "HARBOR",
"unLoCode": "PLSZZ"
}
}, {
"type": "ROAD",
"structure": "ARTICULATED",
"grossWeight": {
"value": 40,
"unit": "METRIC_TONNE"
},
"energyType": "DIESEL"
}
]
}
```
In this example, the `HUB` elements explicitly separates the road legs and the water leg.
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](/content/guides/hubs) 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.
***
## Vehicle selection
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:
* 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. |
```json theme={null}
{
"type": "ROAD",
"vehicle": "HEAVY_DUTY_VEHICLE",
"energyType": "DIESEL"
}
```
***
## Packaging
`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. |
```json theme={null}
{
"type": "ROAD",
"packaging": "CONTAINER"
}
```
If `packaging` is `CONTAINER` and no stronger vehicle selection input is provided, TerraTwin selects a container capable road vehicle.
