Transport chains - TerraTwin API Documentation

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.

Transport operations

A transport operation represents movement by one requested mode.Supported operation types are:

Hubs

A HUB represents a connection point between transport operations, or a hub at the start or end of the chain.Hubs contain a location and are covered in more detail in the hubs guide.

Basic shape

A simple chain contains one transport operation:

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

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

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.

Tibury harbor departure
Tilbury to Brussels
Amsterdam transfer

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.

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 for the complete insertion rules and configuration options.

For example, this request has one requested AIR leg:

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

First mile road

Cargo is taken by road from the Oxnard address to Los Angeles International Airport [IATA:LAX].

Air transport

Cargo flies from Los Angeles International Airport [IATA:LAX] to Orlando International Airport [IATA:MCO].

Last mile road

Cargo is trucked from Orlando International Airport [IATA:MCO] to the 1375 East Buena Vista Drive address.

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.

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.

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.

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

Munich to Miami by train, ship, and truck

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

For more detail on how to describe hub sites and emissions intensity, see the hubs guide. For more detail on PLACE, AIRPORT, RAIL_YARD, and HARBOR, see the locations guide.

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.

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

Marsa al Hariga tank farm to Castellon tank farm

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:

Road

Use ROAD for road-only legs and explicitly modeled road movements.

Rail

Use RAIL for train movements between rail yards or automatically selected rail facilities.

Water

Use WATER for maritime movements between harbors.

Air

Use AIR for flights between airports.

Weighted modes

Use WEIGHTED_MODES when the same leg could have been performed by several alternative modes and you want emissions weighted by percentage.

Recommendations

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.

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.

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.

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.

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.

Transport operations

Hubs

​Basic shape

​Legs and realized operations

​Hubs separate legs

​Hubs at the origin and destination

​Operation specific guides

Road

Rail

Water

Air

Weighted modes

​Recommendations

​Common mistakes

Basic shape

Legs and realized operations

Hubs separate legs

Hubs at the origin and destination

Operation specific guides

Recommendations

Common mistakes