> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terratwin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cargo
> Defines the goods being transported and helps TerraTwin to choose the right defaults for emissions modelling.
In TerraTwin, `weight` is the only required cargo input, but the additional cargo properties can materially improve the emissions calculation.
The `category`, `densityCharacteristics`, and `climateControl` properties help TerraTwin choose more appropriate defaults for vehicles,
routes, and logistics hubs.
**Defaults affected:** load factor, empty running, and temperature-control energy use.
`cargo.densityCharacteristics` affects road defaults for **load factor** and **empty running**. If it is not provided, TerraTwin defaults it from `cargo.category`.
Setting `cargo.climateControl` to `REQUIRED` increases energy consumption where temperature control is modelled.
**Defaults affected:** train type and temperature-control energy use.
When a train type is not supplied directly, TerraTwin uses `cargo.category` to select the default **train type**.
Setting `cargo.climateControl` to `REQUIRED` increases energy consumption where temperature control is modelled.
**Defaults affected:** vessel type and reefer container modelling.
When a vessel type is not supplied directly, TerraTwin uses `cargo.category` to select the default **vessel type**.
This lets liquid fuels, liquefied gases, dry bulk goods, automobiles, and manufactured goods map to different maritime equipment defaults.
Setting `cargo.climateControl` to `REQUIRED` causes **reefer containers** to be modelled where relevant, increasing emissions intensity.
**Defaults affected:** hub type and temperature-controlled handling.
When a hub type is not supplied directly, TerraTwin uses `cargo.category` to select the default **logistics hub type**.
Liquid cargo categories will default to `LIQUID_BULK_TERMINAL`, while maritime terminals are selected automatically for water transport operations.
Setting `cargo.climateControl` to `REQUIRED` increases hub emissions where temperature-controlled handling or storage is modelled.
The result is a more specific energy consumption and emissions rate selection. Instead of applying one generic freight assumption to everything, TerraTwin can model different equipment and operating patterns for different goods.
Think of `cargo.category` as a modelling hint. A tonne of crude oil, a tonne of clothing, and a tonne of refrigerated fish may weigh the same, but they usually move through very different logistics systems.
***
## The cargo object
A minimal cargo object only needs weight:
```json theme={null}
{
"cargo": {
"weight": {
"value": 100,
"unit": "KILOGRAM"
}
}
}
```
A more descriptive cargo object gives TerraTwin more to work with:
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"densityCharacteristics": "LIGHT",
"climateControl": "AT_AMBIENT",
"weight": {
"value": 12,
"unit": "METRIC_TONNE"
}
}
}
```
***
### Properties
| Property | Required | What it does |
| ----------------------------------------------------------------- | -------: | -------------------------------------------------------------------------------------------------------------------------- |
| weight | Yes | The net shipment mass used to scale activity and emissions. |
| category | No | Selects commodity specific defaults for vehicles, logistics hubs, density, and temperature control. Defaults to `GENERAL`. |
| densityCharacteristics | No | Indicates whether cargo is light, average, or heavy. Defaults from `category`. |
| climateControl | No | Adds active temperature control energy in transport operations. Defaults based on `category`. |
***
## Weight
`cargo.weight` is the only mandatory cargo property.
The weight should include the goods and the packaging provided by the shipper. It should **not** include carrier or logistics-service-provider handling equipment, such as pallets, shipping containers, or other equipment added after handover.
Supported units:
* `KILOGRAM`
* `POUND`
* `METRIC_TONNE`
* `US_SHORT_TON`
Examples:
```json theme={null}
{
"cargo": {
"weight": {
"value": 2500,
"unit": "KILOGRAM"
}
}
}
```
```json theme={null}
{
"cargo": {
"weight": {
"value": 40,
"unit": "US_SHORT_TON"
}
}
}
```
***
## Cargo categories
`cargo.category` describes the type of goods being transported. If it is omitted, TerraTwin uses `GENERAL`.
| Category | Typical use | Default density | Default climate control |
| ----------------------------------------------------------------- | ----------------------------------------------------- | --------------- | ----------------------- |
| AUTOMOBILES | Finished vehicles transported by specialized carriers | `AVERAGE_MIXED` | `AT_AMBIENT` |
| BUILDING\_MATERIALS | Cement, sand, gravel, bricks, stone, lumber | `HEAVY` | `AT_AMBIENT` |
| CEREALS | Grain crops and similar agricultural bulk goods | `HEAVY` | `AT_AMBIENT` |
| COAL\_AND\_STEEL | Extra heavy bulk where empty returns are common | `HEAVY` | `AT_AMBIENT` |
| GENERAL | Unspecified or miscellaneous cargo | `AVERAGE_MIXED` | `AT_AMBIENT` |
| LIQUEFIED\_GAS | LNG, LPG, and similar liquefied gases | `HEAVY` | `AT_AMBIENT` |
| LIQUID\_CHEMICALS | Bulk liquid chemical products | `HEAVY` | `AT_AMBIENT` |
| MANUFACTURED\_PRODUCTS | Consumer or industrial manufactured goods | `AVERAGE_MIXED` | `AT_AMBIENT` |
| OIL | Crude oil or refined petroleum products | `HEAVY` | `AT_AMBIENT` |
| REFRIGERATED\_BULK | Perishable goods that must be kept cold | `AVERAGE_MIXED` | `REQUIRED` |
| SOLID\_CHEMICALS | Powders, granules, pellets, or dry chemical bulk | `HEAVY` | `AT_AMBIENT` |
Example:
```json theme={null}
{
"cargo": {
"category": "CEREALS",
"weight": {
"value": 28000,
"unit": "KILOGRAM"
}
}
}
```
***
## Temperature controlled cargo
Use `climateControl: "REQUIRED"` when goods need active temperature regulation.
```json theme={null}
{
"cargo": {
"category": "GENERAL",
"climateControl": "REQUIRED",
"weight": {
"value": 8000,
"unit": "KILOGRAM"
}
}
}
```
Or select the refrigerated bulk cargo category:
```json theme={null}
{
"cargo": {
"category": "REFRIGERATED_BULK",
"weight": {
"value": 22,
"unit": "METRIC_TONNE"
}
}
}
```
`REFRIGERATED_BULK` defaults `climateControl` to `REQUIRED`.
When climate control is required, TerraTwin includes the extra energy used for powered temperature regulation. Depending on the operation, this can represent refrigeration power on trucks, reefer containers, or refrigerated bulk vessels.
Use `AT_AMBIENT` for goods moved under natural temperature conditions.
This is the default for most categories.
Use `REQUIRED` when the cargo needs active cooling or heating.
This increases emissions because powered temperature control consumes additional energy.
***
## Density characteristics
`densityCharacteristics` describes whether the cargo usually fills up a vehicle or container by weight or by space.
| Value | Meaning | Density assumption |
| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------: |
| `LIGHT` | Low-density cargo that often cubes out before it weighs out, such as furniture, clothing, and footwear | 6 tonnes per TEU |
| `AVERAGE_MIXED` | Medium-density or mixed cargo | 10 tonnes per TEU |
| `HEAVY` | Tightly packed high-density cargo, such as metals and raw or bulk commodities | 14.5 tonnes per TEU |
Example: light manufactured products.
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"densityCharacteristics": "LIGHT",
"weight": {
"value": 12,
"unit": "METRIC_TONNE"
}
}
}
```
Example: heavy solid chemicals.
```json theme={null}
{
"cargo": {
"category": "SOLID_CHEMICALS",
"densityCharacteristics": "HEAVY",
"weight": {
"value": 12,
"unit": "METRIC_TONNE"
}
}
}
```
These two examples have the same mass. The light cargo may need more container space or different vehicle utilisation assumptions than the heavy cargo, which can change both transport and hub emissions.
***
## Examples
### 1. Minimal request using defaults
```json theme={null}
{
"cargo": {
"weight": {
"value": 100,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"city": "London",
"countryCode": "GB"
},
"destination": {
"type": "PLACE",
"city": "Berlin",
"countryCode": "DE"
}
}
```
TerraTwin treats the cargo as `GENERAL`, with average mixed density and ambient temperature control.
***
### 2. Climate controlled road shipment
```json theme={null}
{
"cargo": {
"climateControl": "REQUIRED",
"weight": {
"value": 5000,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"city": "Stockholm",
"countryCode": "SE"
},
"destination": {
"type": "PLACE",
"city": "Oslo",
"countryCode": "NO"
},
"transportChain": [
{
"type": "ROAD"
}
]
}
```
This request sets `cargo.climateControl` directly to `REQUIRED`, so TerraTwin includes the additional energy needed for temperature controlled road transport.
***
### 3. Category affects harbor selection (part 1)
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 10,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "PLACE",
"city": "Barcelona",
"countryCode": "ES"
},
"destination": {
"type": "PLACE",
"city": "Corfu",
"countryCode": "GR"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
For manufactured products, Terratwin defaults to container shipping. Since the destination, Corfu, does not typically support container ships, the product is routed to an alternate port, Astakos \[`GRAST`], and then transported onward by truck and ferry.
***
### 4. Category affects harbor selection (part 2)
```json theme={null}
{
"cargo": {
"category": "BUILDING_MATERIALS",
"weight": {
"value": 10,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "PLACE",
"city": "Barcelona",
"countryCode": "ES"
},
"destination": {
"type": "PLACE",
"city": "Corfu",
"countryCode": "GR"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
Change the product category to building materials and the shipment follows different routing logic. This category defaults to a bulker vessel rather than container shipping, allowing the product to be shipped directly to the port of Corfu, where small bulker vessels are supported.
***
## Recommendations
Include `cargo.weight.value` and `cargo.weight.unit` on every calculation request.
Use `cargo.category` whenever the goods fit one of the supported categories. This improves default vehicle, hub, and temperature-control assumptions.
Set `densityCharacteristics` when the category default is not representative, such as lightweight furniture under manufactured products or unusually dense packaged cargo.
Use `climateControl: "REQUIRED"` for any temperature-controlled shipment, even if the cargo category is not `REFRIGERATED_BULK`.
Cargo-aware defaults are useful, but actual vehicle, vessel, train, fuel, electricity, load factor, and energy-consumption data should be provided when known.
***
## Common mistakes
* Omitting `weight` from `cargo`.
* Using `GENERAL` when a more precise category is known.
* Forgetting `climateControl: "REQUIRED"` for chilled, frozen, refrigerated, or otherwise temperature-controlled cargo outside the `REFRIGERATED_BULK` category.
* Treating `densityCharacteristics` as cosmetic metadata. It can affect road, rail, and terminal handling emissions.
* Including carrier-supplied pallets, containers, or handling equipment in `cargo.weight` when those are not part of the goods being transported.