Cargo - TerraTwin API Documentation

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.

Road

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.

Rail

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.

Water

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.

Hubs

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:

{
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  }
}

A more descriptive cargo object gives TerraTwin more to work with:

{
  "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:

{
  "cargo": {
    "weight": {
      "value": 2500,
      "unit": "KILOGRAM"
    }
  }
}

{
  "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:

{
  "cargo": {
    "category": "CEREALS",
    "weight": {
      "value": 28000,
      "unit": "KILOGRAM"
    }
  }
}

Temperature controlled cargo

Use climateControl: "REQUIRED" when goods need active temperature regulation.

{
  "cargo": {
    "category": "GENERAL",
    "climateControl": "REQUIRED",
    "weight": {
      "value": 8000,
      "unit": "KILOGRAM"
    }
  }
}

Or select the refrigerated bulk cargo category:

{
  "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.

Ambient cargo

Use AT_AMBIENT for goods moved under natural temperature conditions.This is the default for most categories.

Refrigerated cargo

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.

{
  "cargo": {
    "category": "MANUFACTURED_PRODUCTS",
    "densityCharacteristics": "LIGHT",
    "weight": {
      "value": 12,
      "unit": "METRIC_TONNE"
    }
  }
}

Example: heavy solid chemicals.

{
  "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

{
  "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

{
  "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)

{
  "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.

Barcelona to Corfu via Astakos
Astakos transfer

Barcelona to Corfu via Port of Astakos [`GRAST`]

4. Category affects harbor selection (part 2)

{
  "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.

Barcelona to Corfu direct
Corfu harbor transfer

Recommendations

Always provide weight

Include cargo.weight.value and cargo.weight.unit on every calculation request.

Provide category when you know it

Use cargo.category whenever the goods fit one of the supported categories. This improves default vehicle, hub, and temperature-control assumptions.

Override density for unusual goods

Set densityCharacteristics when the category default is not representative, such as lightweight furniture under manufactured products or unusually dense packaged cargo.

Set climate control explicitly

Use climateControl: "REQUIRED" for any temperature-controlled shipment, even if the cargo category is not REFRIGERATED_BULK.

Provide operational details when available

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.

Road

Rail

Water

Hubs

​The cargo object

​Properties

​Weight

​Cargo categories

​Temperature controlled cargo

Ambient cargo

Refrigerated cargo

​Density characteristics

​Examples

​1. Minimal request using defaults

​2. Climate controlled road shipment

​3. Category affects harbor selection (part 1)

​4. Category affects harbor selection (part 2)

​Recommendations

​Common mistakes

The cargo object

Properties

Weight

Cargo categories

Temperature controlled cargo

Density characteristics

Examples

1. Minimal request using defaults

2. Climate controlled road shipment

3. Category affects harbor selection (part 1)

4. Category affects harbor selection (part 2)

Recommendations

Common mistakes