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

# Transport chains

> Use transportChain to describe single and multiple leg shipments.

A `transportChain` describes how cargo moves from the shipment origin to the shipment destination.
It is an ordered array of transport chain elements. Each element is either a transport operation or a `HUB`.

<Columns cols={2}>
  <Card title="Transport operations" icon="route">
    A transport operation represents movement by one requested mode.

    Supported operation types are:

    * [`UNKNOWN`](/content/guides/unknown-transport)
    * [`ROAD`](/content/guides/road-transport)
    * [`RAIL`](/content/guides/rail-transport)
    * [`WATER`](/content/guides/water-transport)
    * [`AIR`](/content/guides/air-transport)
    * [`WEIGHTED_MODES`](/content/guides/weighted-modes-transport)
  </Card>

  <Card title="Hubs" icon="warehouse">
    A `HUB` represents a connection point between transport operations, or a hub at the start or end of the chain.

    Hubs contain a [location](/content/guides/locations) and are covered in more detail in the [hubs guide](/content/guides/hubs).
  </Card>
</Columns>

***

## Basic shape

A simple chain contains one transport operation:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 1,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Madrid",
    "countryCode": "ES"
  },
  "destination": {
    "type": "PLACE",
    "city": "Barcelona",
    "countryCode": "ES"
  },
  "transportChain": [
    {
      "type": "ROAD"
    }
  ]
}
```

A multimodal chain uses hubs to separate transport operation legs:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 1,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "GBTIL"
  },
  "destination": {
    "type": "PLACE",
    "city": "Brussels",
    "countryCode": "BE"
  },
  "transportChain": [
    {
      "type": "WATER"
    }, {
      "type": "HUB",
      "location": {
        "type": "HARBOR",
        "unLoCode": "BEANR"
      }
    }, {
      "type": "ROAD"
    }
  ]
}
```

In this example:

* A ship runs from the top-level `origin` at the London container terminal within the port of Tilbury to Antwerp harbor.
* The `HUB` marks the transfer point and will contribute hub emissions.
* A final leg by road runs from Antwerp harbor to the top-level `destination` in Brussels.

<Note>
  This hub omits `hubType`. With automatic hub insertion enabled, TerraTwin selects a type using the configured or built-in `WATER` to `ROAD` rules.
  With `options.hubInsertion: "MANUAL"`, it remains a location boundary but does not contribute hub emissions.
  See [How a hub type is selected](/content/guides/hubs#how-a-hub-type-is-selected).
</Note>

***

<Tabs defaultTabIndex={1}>
  <Tab title="Tibury harbor departure">
    <Frame caption="Port of Tilbury [`GBTIL`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/tilbury-harbor-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=8d1f5d90546ead5b6c073054e93c1d89" width="1489" height="593" data-path="images/transport-chains/tilbury-harbor-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/tilbury-harbor-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=7b39ae0303c62dde0f87e6ddc4d8beb4" width="1489" height="593" data-path="images/transport-chains/tilbury-harbor-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Tilbury to Brussels">
    <Frame caption="Port of Tilbury [`GBTIL`] to Brussels">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/tilbury-to-brussels-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=b47a8d235a326e217ac1bd66e723d8ab" width="1639" height="579" data-path="images/transport-chains/tilbury-to-brussels-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/tilbury-to-brussels-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=d976a7ed26f6fc97c6e645eec06c5949" width="1639" height="579" data-path="images/transport-chains/tilbury-to-brussels-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Amsterdam transfer">
    <Frame caption="Port of Amsterdam [`NLAMS`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/amsterdam-transfer-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=5858e2018843e59d2bc2911674557bab" width="1428" height="735" data-path="images/transport-chains/amsterdam-transfer-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/amsterdam-transfer-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=fb7a365e12a65f9afd90d0182c54f56a" width="1428" height="735" data-path="images/transport-chains/amsterdam-transfer-dark.png" />
    </Frame>
  </Tab>
</Tabs>

***

## Legs and realized operations

A leg is one requested movement between two boundary locations.
Those boundaries come from the top-level `origin` and `destination`, or from the nearest `HUB` elements before and after the transport operation.

<Note>
  One requested leg is not always one realized operation. For non-road modes, TerraTwin may add first mile and last mile road movements automatically when the leg starts or ends at a general place instead of the required transport facility.
  See [Automatic hub insertion](/content/guides/hubs#automatic-hub-insertion) for the complete insertion rules and configuration options.
</Note>

For example, this request has one requested `AIR` leg:

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "address": "424 South C Street, Oxnard, CA 93030",
    "countryCode": "US"
  },
  "destination": {
    "type": "PLACE",
    "address": "1375 Buena Vista Drive, Lake Buena Vista, LF 32830",
    "countryCode": "US"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "B748"
    }
  ]
}
```

TerraTwin will realize that leg as multiple transport operations:

<Steps>
  <Step title="First mile road">
    Cargo is taken by road from the Oxnard address to Los Angeles International Airport \[IATA:`LAX`].

    <Frame caption="First mile road from Oxnard to Los Angeles International Airport">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/oxnard-to-lax-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=64991a3785d7930762c9932848877af0" width="887" height="313" data-path="images/transport-chains/oxnard-to-lax-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/oxnard-to-lax-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=f162bcfba1d495278437bb73d177e730" width="887" height="313" data-path="images/transport-chains/oxnard-to-lax-dark.png" />
    </Frame>
  </Step>

  <Step title="Air transport">
    Cargo flies from Los Angeles International Airport \[IATA:`LAX`] to Orlando International Airport \[IATA:`MCO`].

    <Frame caption="Air transport from Los Angeles International Airport to Orlando International Airport">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/los-angeles-to-orlando-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=03bb8bb46b174c00d22414e022839b2d" width="939" height="319" data-path="images/transport-chains/los-angeles-to-orlando-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/los-angeles-to-orlando-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=e147102cecff8c6b9320bdb2d36e2945" width="939" height="319" data-path="images/transport-chains/los-angeles-to-orlando-dark.png" />
    </Frame>
  </Step>

  <Step title="Last mile road">
    Cargo is trucked from Orlando International Airport \[IATA:`MCO`] to the 1375 East Buena Vista Drive address.

    <Frame caption="Last mile road from Orlando International Airport to Team Disney Orlando">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/orlando-to-epcot-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=5b0f5ce5fb424983f9600a5b96d03e36" width="916" height="290" data-path="images/transport-chains/orlando-to-epcot-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/orlando-to-epcot-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=81d40e531285d65cdc895289320ee0b9" width="916" height="290" data-path="images/transport-chains/orlando-to-epcot-dark.png" />
    </Frame>
  </Step>
</Steps>

The same pattern applies to `RAIL` and `WATER` when the boundary location is not already a rail yard or harbor.
If you use facility locations directly, such as `AIRPORT`, `RAIL_YARD`, or `HARBOR`, that part of the first mile or last mile movement is not needed.

<Note>
  By default, TerraTwin inserts `HUB` operations between the realized transport operations in the response. Each inserted hub has associated emissions, for example for transferring cargo from road to air, rail, or water transport. This is part of TerraTwin’s ISO 14083-aligned calculation model, where logistics hub emissions are included in addition to the movement emissions.
</Note>

***

## Hubs separate legs

Use a `HUB` when one requested transport operation ends and another begins.
The hub's `location` becomes the end location for the operation before it and the start location for the operation after it.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Munich",
    "countryCode": "DE"
  },
  "destination": {
    "type": "PLACE",
    "city": "Miami",
    "countryCode": "US"
  },
  "transportChain": [
    {
      "type": "RAIL"
    }, {
      "type": "HUB",
      "location": {
        "type": "PLACE",
        "city": "Lisbon",
        "countryCode": "PT"
      }
    }, {
      "type": "WATER"
    }, {
      "type": "HUB",
      "location": {
        "type": "PLACE",
        "city": "New York",
        "countryCode": "US"
      }
    }, {
      "type": "WATER"
    }
  ]
}
```

<Frame caption="Munich to Miami by train, ship, and truck">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/munich-to-miami-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=d3fe5f5941860cf1a69d9e8fc909d352" width="1038" height="309" data-path="images/transport-chains/munich-to-miami-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/munich-to-miami-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=30ce8610618682fb78541d302e568f8d" width="1038" height="309" data-path="images/transport-chains/munich-to-miami-dark.png" />
</Frame>

<Note>
  A hub is not itself a transport movement. It is the transfer point between the surrounding operations.
</Note>

For more detail on how to describe hub sites and emissions intensity, see the [hubs guide](/content/guides/hubs).
For more detail on `PLACE`, `AIRPORT`, `RAIL_YARD`, and `HARBOR`, see the [locations guide](/content/guides/locations).

***

## Hubs at the origin and destination

A `HUB` can also be the first or last item in the `transportChain` array.
This lets the chain start and/or finish at a logistics hub, replacing the top-level origin or destination for the chain boundary and potentially stipulating emissions at that origin or destination hub.

```json theme={null}
{
  "cargo": {
    "category": "OIL",
    "weight": {
      "unit": "METRIC_TONNE",
      "value": 1000
    },
  },
  "transportChain": [
    {
      "type": "HUB",
      "hubType": "LIQUID_BULK_TERMINAL",
      "location": {
        "type": "HARBOR",
        "unLoCode": "LYMHR"
      }
    }, {
      "type": "WATER"
    }, {
      "type": "HUB",
      "hubType": "LIQUID_BULK_TERMINAL",
      "location": {
        "type": "HARBOR",
        "unLoCode": "ESCAS"
      }
    }
  ]
}
```

<Frame caption="Marsa al Hariga tank farm to Castellon tank farm">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/marsa-al-hariga-to-castellon-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=bac79cb493c6c0449213f06dd9814a8a" width="971" height="427" data-path="images/transport-chains/marsa-al-hariga-to-castellon-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/transport-chains/marsa-al-hariga-to-castellon-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=ae1fda449aff2756b72854b00181815c" width="971" height="427" data-path="images/transport-chains/marsa-al-hariga-to-castellon-dark.png" />
</Frame>

***

## Operation specific guides

Each transport operation type has its own fields, defaults, and routing behavior.
Use the focused operation guides when you are ready to configure a particular leg:

<Columns cols={2}>
  <Card title="Road" icon="truck">
    Use [`ROAD`](/content/guides/road-transport) for road-only legs and explicitly modeled road movements.
  </Card>

  <Card title="Rail" icon="train">
    Use [`RAIL`](/content/guides/rail-transport) for train movements between rail yards or automatically selected rail facilities.
  </Card>

  <Card title="Water" icon="ship">
    Use [`WATER`](/content/guides/water-transport) for maritime movements between harbors.
  </Card>

  <Card title="Air" icon="plane">
    Use [`AIR`](/content/guides/air-transport) for flights between airports.
  </Card>
</Columns>

<Card title="Weighted modes" icon="percent">
  Use [`WEIGHTED_MODES`](/content/guides/weighted-modes-transport) when the same leg could have been performed by several alternative modes and you want emissions weighted by percentage.
</Card>

***

## Recommendations

<Steps>
  <Step title="Model the chain in shipment order">
    Arrange `transportChain` elements in the order the cargo moves. Use the top level `origin` as the boundary before the first transport operation and the top level `destination` as the boundary after the last transport operation.
  </Step>

  <Step title="Use hubs to define known transfer points">
    Put a `HUB` between transport operations when you know where one leg ends and the next leg starts. The hub `location` becomes the end location for the previous operation and the start location for the next operation.
  </Step>

  <Step title="Use start and end hubs deliberately">
    Add a `HUB` as the first or last `transportChain` element only when the shipment should start or finish at that logistics hub instead of using the top level `origin` or `destination` as the chain boundary.
  </Step>

  <Step title="Choose boundary location types deliberately">
    Use `PLACE` when TerraTwin should resolve the general place and add first-mile or last-mile connector movements where needed. Use `AIRPORT`, `HARBOR`, or `RAIL_YARD` when you want to anchor a leg to a specific transport facility type.
  </Step>
</Steps>

***

## Common mistakes

* Placing two transport operations next to each other without a `HUB` between them.
* Adding a `HUB` without a `location`, or putting a location object directly in `transportChain` instead of wrapping it in a hub element.
* Using `PLACE` when a specific airport, harbor, or rail yard is required. For `AIR`, `WATER`, and `RAIL`, a general place allows TerraTwin to select a suitable facility and may add connector road movements.
* Leaving `transportChain` empty, or using `UNKNOWN`, when the transport mode is known. Fallback modes are tried with defaulted configuration and may select a different mode than expected.