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

# Rail transport

> Use RAIL transport operations to calculate emissions for cargo moved by train.

Rail transport operations model cargo moved by train between rail yards.
Set the transport operation `type` to `RAIL` within a [transport chain](/content/guides/transport-chains) when a shipment leg is moved by rail.

TerraTwin can calculate rail emissions from a very small amount of information, but rail transport is sensitive to the train consist, the selected rail yards, the rail route, and whether each section of the route is operated using electric or diesel traction.

<Columns cols={2}>
  <Card title="Mode" icon="circle-nodes">
    Use `type: "RAIL"` in a `transportChain` transport element.

    TerraTwin treats that element as a requested rail leg between the surrounding transport chain locations.
  </Card>

  <Card title="Train" icon="train">
    Use `vehicle` when you know the train consist.

    If the exact consist is unknown, use `trainType`, `grossTrainWeight`, and `cargo.category` to guide train selection.
  </Card>

  <Card title="Rail yards" icon="warehouse">
    If the leg does not start or end at a `RAIL_YARD`, TerraTwin selects suitable rail yards automatically.

    The rail movement is routed between those rail yards.
  </Card>

  <Card title="Connectors" icon="truck">
    If the origin or destination is not already a rail yard, TerraTwin can automatically add first mile and last mile road transport.

    Use `firstMile` and `lastMile` when the road vehicle configuration is known.
  </Card>
</Columns>

<Note>
  Use `RAIL` when cargo is modeled as freight moving by train.
  A road journey that uses a roll-on/roll-off train service, such as the Channel Tunnel shuttle, is normally modeled as `ROAD`.
  When the selected road route uses the rail crossing, TerraTwin represents it as a sub-operation of the `ROAD` transport operation.
</Note>

***

## Basic shape

A minimal rail operation only needs `type: "RAIL"` in the transport chain:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 20,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "PLACE",
    "postcode": "CF10 1EP",
    "countryCode": "GB"
  },
  "destination": {
    "type": "PLACE",
    "postcode": "8000",
    "countryCode": "BE"
  },
  "transportChain": [
    {
      "type": "RAIL"
    }
  ]
}
```

<Frame caption="CF10 1EP Cardiff to 8000 Bruges">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/cardiff-to-bruges-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=a512606308d91dd807836dc9ff886c27" width="924" height="313" data-path="images/rail-transport/cardiff-to-bruges-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/cardiff-to-bruges-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=9cac0f012962f0980ccaf0ffdd768918" width="924" height="313" data-path="images/rail-transport/cardiff-to-bruges-dark.png" />
</Frame>

In this request, the transport mode is specified by the `type` property on the transport operation.
Because the origin and destination are places rather than rail yards, TerraTwin selects suitable rail yards and adds road connector movements where needed.

<Note>
  When TerraTwin adds first-mile or last-mile road transport, automatic hub insertion can also add `HUB` operations at the road-to-rail and rail-to-road transfers. See the [logistics hubs guide](/content/guides/hubs#automatic-hub-insertion) for how these hubs are selected and how to control them with `options.hubInsertion`.
</Note>

The more information you can provide about the train, the more accurately TerraTwin can model the transport operation. The most specific option is to provide the exact train `vehicle` and `energyType`:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 20,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "RAIL_YARD",
    "city": "Fukuoka",
    "countryCode": "JP"
  },
  "destination": {
    "type": "RAIL_YARD",
    "city": "Tokyo",
    "countryCode": "JP"
  },
  "transportChain": [
    {
      "type": "RAIL",
      "vehicle": "DOUBLE_CONTAINER_TRAIN",
      "energyType": "ELECTRICITY"
    }
  ]
}
```

<Frame caption="Fukuoka to Tokyo">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/fukuoka-to-tokyo-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=928bc363920ac3e50450d7bbc46388b8" width="1027" height="411" data-path="images/rail-transport/fukuoka-to-tokyo-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/fukuoka-to-tokyo-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=6d111d98690d598445142afe3546287b" width="1027" height="411" data-path="images/rail-transport/fukuoka-to-tokyo-dark.png" />
</Frame>

This asks TerraTwin to model the cargo as being transported by an electric, double-stack container freight train.
Because both endpoints are rail yards, no first-mile or last-mile road connectors are needed.

***

## Properties

| Property            | Required | What it does                                                                                                                                                                                           |
| ------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`              |      Yes | Selects rail transport. Use `RAIL`.                                                                                                                                                                    |
| `vehicle`           |       No | Identifies the train consist directly. When provided, it takes precedence over `trainType`, `grossTrainWeight`, and `cargo.category`.                                                                  |
| `trainType`         |       No | Selects the train selection strategy. Use `MANIFEST` for mixed cargo trains or `UNIT` for dedicated commodity trains.                                                                                  |
| `grossTrainWeight`  |       No | Gross train weight. Used to choose the size of a `MANIFEST` train. Ignored for `UNIT` trains.                                                                                                          |
| `energyType`        |       No | Requested traction energy. Use `ELECTRICITY` or `DIESEL`. The default is `ELECTRICITY`, but electric traction is only used where the rail line supports it.                                            |
| `departureDateTime` |       No | The departure date and time.                                                                                                                                                                           |
| `arrivalDateTime`   |       No | The arrival date and time.                                                                                                                                                                             |
| `firstMile`         |       No | Road vehicle configuration for the automatic road movement from a non-rail-yard origin to the selected origin rail yard.                                                                               |
| `lastMile`          |       No | Road vehicle configuration for the automatic road movement from the selected destination rail yard to a non-rail-yard destination.                                                                     |
| `id`                |       No | Optional identifier for the transport operation. When provided, the same identifier is returned on the corresponding result element, making it easier to match request operations to response results. |
| `context`           |       No | Caller provided metadata returned with the corresponding result element. Preserved if the rail operation falls back to another mode.                                                                   |

***

## Selecting rail as the mode

The mode is selected with the `type` property on a transport operation:

```json theme={null}
{
  "transportChain": [
    {
      "type": "RAIL"
    }
  ]
}
```

The rail 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": 15,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "USANC"
  },
  "destination": {
    "type": "HARBOR",
    "unLoCode": "CASJF"
  },
  "transportChain": [
    {
      "type": "WATER"
    }, {
      "type": "HUB",
      "location": {
        "type": "HARBOR",
        "unLoCode": "CAVAN"
      }
    }, {
      "type": "RAIL"
    }, {
      "type": "HUB",
      "location": {
        "type": "HARBOR",
        "unLoCode": "CAQUE"
      }
    }, {
      "type": "WATER"
    }
  ]
}
```

<Frame caption="Anchorage to St. John's via Vancouver and Quebec">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/anchorage-to-st-johns-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=8de039501ad6dd01c2d490592dfb1bb6" width="766" height="453" data-path="images/rail-transport/anchorage-to-st-johns-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/anchorage-to-st-johns-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=834bc2044ab22e2857a839d4ff701a2d" width="766" height="453" data-path="images/rail-transport/anchorage-to-st-johns-dark.png" />
</Frame>

In this example, the `HUB` elements explicitly separate the sea and rail legs.

<Note>
  These intermediate hubs omit `hubType`.
  With automatic hub insertion enabled, TerraTwin selects their hub types from the surrounding `WATER` to `RAIL` and `RAIL` to `WATER` transitions.
  With `options.hubInsertion: "MANUAL"`, they remain location boundaries but do not add hub emissions. See the [How a hub type is selected](/content/guides/hubs#how-a-hub-type-is-selected) for hub type selection and insertion rules.
</Note>

***

## Train selection

Rail supports two broad train consist families:

<Columns cols={2}>
  <Card title="Manifest trains" icon="boxes-stacked">
    Use `trainType: "MANIFEST"` for general mixed cargo services using multiple wagon types.

    Emissions are calculated from the train size, which can be selected using `grossTrainWeight`.
  </Card>

  <Card title="Unit trains" icon="box">
    Use `trainType: "UNIT"` for dedicated services carrying one cargo type.

    Emissions are calculated from the cargo specific train configuration selected from `cargo.category`.
  </Card>
</Columns>

There are several ways to influence train selection. You do not need to provide all of them. In general, the more information you can provide about the train, the more accurately TerraTwin can model the transport operation.

TerraTwin applies train selection in this order:

| Priority | Inputs provided                              | Selection behavior                                                                                                                                                                          |
| -------: | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|        1 | `vehicle`                                    | Uses the specified train class directly.                                                                                                                                                    |
|        2 | `trainType: "MANIFEST"` + `grossTrainWeight` | Treats the operation as a manifest train and maps the gross train weight to a manifest train size.                                                                                          |
|        3 | `trainType: "UNIT"` + `cargo.category`       | Treats the operation as a unit train and maps the cargo category to a dedicated unit train configuration.                                                                                   |
|        4 | `trainType: "MANIFEST"` only                 | Treats the operation as a manifest train and selects a default manifest train size based on the region of operation.                                                                        |
|        5 | `trainType: "UNIT"` only                     | Treats the operation as a unit train and uses `cargo.category` to select the unit train. If `cargo.category` is omitted, it defaults to `GENERAL`, which is treated as containerized cargo. |
|        6 | `grossTrainWeight` only                      | Infers a manifest train and maps the gross train weight to a manifest train size.                                                                                                           |
|        7 | `cargo.category` only                        | Infers a unit train and maps the cargo category to a dedicated unit train configuration.                                                                                                    |

***

## Direct train selection with `vehicle`

Use `vehicle` when you know the train consist.
Supported train values include both manifest train sizes and unit train types:

| Train value                                                              | Description                                                                                                                   |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| <code className="whitespace-nowrap">LIGHT\_TRAIN</code>                  | Mixed cargo manifest train below 750 tonnes gross train weight.                                                               |
| <code className="whitespace-nowrap">AVERAGE\_TRAIN</code>                | Mixed cargo manifest train between 750 and 1,250 tonnes gross train weight.                                                   |
| <code className="whitespace-nowrap">LARGE\_TRAIN</code>                  | Mixed cargo manifest train between 1,250 and 1,750 tonnes gross train weight.                                                 |
| <code className="whitespace-nowrap">EXTRA\_LARGE\_TRAIN</code>           | Mixed cargo manifest train between 1,750 and 2,250 tonnes gross train weight.                                                 |
| <code className="whitespace-nowrap">HEAVY\_TRAIN</code>                  | Mixed cargo manifest train above 2,250 tonnes gross train weight.                                                             |
| <code className="whitespace-nowrap">AUTOMOBILE\_TRAIN</code>             | Dedicated unit train using autorack wagons for finished vehicles.                                                             |
| <code className="whitespace-nowrap">CHEMICALS\_TRAIN</code>              | Dedicated unit train using tank or specialized wagons for chemical products, oil, petroleum derivatives, and liquefied gases. |
| <code className="whitespace-nowrap">CONTAINER\_TRAIN</code>              | Dedicated unit train using flat or well wagons for containers.                                                                |
| <code className="whitespace-nowrap">DOUBLE\_CONTAINER\_TRAIN</code>      | Dedicated unit train using well wagons for double-stacked containers.                                                         |
| <code className="whitespace-nowrap">COAL\_AND\_STEEL\_TRAIN</code>       | Dedicated unit train using hopper and gondola wagons for coal and steel products.                                             |
| <code className="whitespace-nowrap">BUILDING\_MATERIALS\_TRAIN</code>    | Dedicated unit train for bulk and palletized building materials.                                                              |
| <code className="whitespace-nowrap">MANUFACTURED\_PRODUCTS\_TRAIN</code> | Dedicated unit train for consumer or industrial manufactured goods.                                                           |
| <code className="whitespace-nowrap">CEREALS\_TRAIN</code>                | Dedicated unit train using covered hopper wagons for cereal grains.                                                           |

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 500,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "RAIL_YARD",
    "address": "J5419 San Juan",
    "countryCode": "AR"
  },
  "destination": {
    "type": "HARBOR",
    "unLoCode": "ARBUE"
  },
  "transportChain": [
    {
      "type": "RAIL",
      "vehicle": "BUILDING_MATERIALS_TRAIN"
    }
  ]
}
```

<Frame caption="Building materials, such as cement, from San Juan to the Port of Buenos Aires">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/san-juan-to-buenos-aires-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=4e80c7b4ae1f424b12e10a7b4fa0e683" width="812" height="260" data-path="images/rail-transport/san-juan-to-buenos-aires-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/san-juan-to-buenos-aires-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=8bc46ae68f3efed4f82d5c9a66e37e49" width="812" height="260" data-path="images/rail-transport/san-juan-to-buenos-aires-dark.png" />
</Frame>

When `vehicle` is set, TerraTwin uses that vehicle class for train selection. Any `trainType`, `grossTrainWeight`, or `cargo.category` values are not used to choose the train.

<Note>
  `cargo.category` may still affect other parts of the calculation. For example, it can influence cargo density, climate-control defaults, connector road vehicle selection, and hub defaults. It is only ignored for the purpose of selecting the train when `vehicle` is provided.
</Note>

***

## Manifest trains and `grossTrainWeight`

Use `trainType: "MANIFEST"` when the cargo moves on a general mixed cargo freight train.
For manifest trains, `grossTrainWeight` is used to choose the train size.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 10,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "RAIL_YARD",
    "unLoCode": "AEFJR"
  },
  "destination": {
    "type": "RAIL_YARD",
    "address": "Al Ghuwaifat",
    "countryCode": "AE"
  },
  "transportChain": [
    {
      "type": "RAIL",
      "trainType": "MANIFEST",
      "grossTrainWeight": {
        "value": 1600,
        "unit": "METRIC_TONNE"
      }
    }
  ]
}
```

<Frame caption="Mixed cargo from the Port of Fujairah [`AEFJR`] to Al Ghuwaifat Station">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/fujairah-to-al-ghuwaifat-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=98e29ab5cdde8992814f8904db50f644" width="1038" height="557" data-path="images/rail-transport/fujairah-to-al-ghuwaifat-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/fujairah-to-al-ghuwaifat-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=1c0dc9867f860acfb6218e00c51c3b2e" width="1038" height="557" data-path="images/rail-transport/fujairah-to-al-ghuwaifat-dark.png" />
</Frame>

The gross weight is mapped to a manifest train class:

| Gross train weight        | Selected manifest train |
| ------------------------- | ----------------------- |
| Less than 750 tonnes      | `LIGHT_TRAIN`           |
| 750 to 1,250 tonnes       | `AVERAGE_TRAIN`         |
| 1,250 to 1,750 tonnes     | `LARGE_TRAIN`           |
| 1,750 to 2,250 tonnes     | `EXTRA_LARGE_TRAIN`     |
| Greater than 2,250 tonnes | `HEAVY_TRAIN`           |

`grossTrainWeight` supports these units:

| Unit           | Meaning                                             |
| -------------- | --------------------------------------------------- |
| `KILOGRAM`     | Kilograms.                                          |
| `METRIC_TONNE` | Metric tonnes, where 1 metric tonne is 1,000 kg.    |
| `POUND`        | Pounds.                                             |
| `US_SHORT_TON` | U.S. short tons, where 1 short ton is 2,000 pounds. |

<Note>
  If `trainType` is `MANIFEST` and `grossTrainWeight` is omitted, TerraTwin chooses a default manifest train size based on the region of operation.
  For example, `AVERAGE_TRAIN` is the European default and `HEAVY_TRAIN` is the USA and Canada default.
</Note>

***

## Unit trains and cargo category mappings

Use `trainType: "UNIT"` when the cargo moves on a dedicated freight train carrying one cargo type.
For unit trains, `grossTrainWeight` is ignored and `cargo.category` is used to select the train configuration.

```json theme={null}
{
  "cargo": {
    "category": "COAL_AND_STEEL",
    "weight": {
      "value": 5000,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "BEANR"
  },
  "destination": {
    "type": "PLACE",
    "address": "ArcelorMittal Eisenhüttenstadt",
    "countryCode": "DE"
  },
  "transportChain": [
    {
      "type": "RAIL",
      "trainType": "UNIT",
      "energyType": "ELECTRICITY"
    }
  ]
}
```

<Frame caption="Iron ore from the Port of Antwerp [`BEANR`] to the ArcelorMittal Eisenhüttenstadt steelworks">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/antwerp-to-eisenh%C3%BCttenstadt-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=1e99c49d647a2e5fd2ddfd05afcb987e" width="577" height="266" data-path="images/rail-transport/antwerp-to-eisenhüttenstadt-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/antwerp-to-eisenh%C3%BCttenstadt-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=ea5bd0a9ae09d0204092036e88422bb9" width="577" height="266" data-path="images/rail-transport/antwerp-to-eisenhüttenstadt-dark.png" />
</Frame>

The automatic unit train selection follows the cargo category:

| `cargo.category`                                                  | Typical selected unit train                                                                                                        | Notes                                                                                                                                          |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| <code className="whitespace-nowrap">AUTOMOBILES</code>            | <code className="whitespace-nowrap">AUTOMOBILE\_TRAIN</code>                                                                       | Finished vehicles carried on autorack wagons.                                                                                                  |
| <code className="whitespace-nowrap">BUILDING\_MATERIALS</code>    | <code className="whitespace-nowrap">BUILDING\_MATERIALS\_TRAIN</code>                                                              | Construction materials such as cement, aggregates, bricks, stone, and lumber.                                                                  |
| <code className="whitespace-nowrap">CEREALS</code>                | <code className="whitespace-nowrap">CEREALS\_TRAIN</code>                                                                          | Grain crops and similar agricultural bulk goods.                                                                                               |
| <code className="whitespace-nowrap">COAL\_AND\_STEEL</code>       | <code className="whitespace-nowrap">COAL\_AND\_STEEL\_TRAIN</code>                                                                 | Extra heavy bulk commodities such as coal and steel.                                                                                           |
| <code className="whitespace-nowrap">GENERAL</code>                | <code className="whitespace-nowrap">CONTAINER\_TRAIN</code> or <code className="whitespace-nowrap">DOUBLE\_CONTAINER\_TRAIN</code> | Treated as containerized. Region and route practices determine whether single-stack or double-stack container rail is used.                    |
| <code className="whitespace-nowrap">REFRIGERATED\_BULK</code>     | <code className="whitespace-nowrap">CONTAINER\_TRAIN</code> or <code className="whitespace-nowrap">DOUBLE\_CONTAINER\_TRAIN</code> | Treated as containerized refrigerated cargo. Region and route practices determine whether single-stack or double-stack container rail is used. |
| <code className="whitespace-nowrap">LIQUEFIED\_GAS</code>         | <code className="whitespace-nowrap">CHEMICALS\_TRAIN</code>                                                                        | Liquefied gases carried in specialized tank or pressure equipment.                                                                             |
| <code className="whitespace-nowrap">LIQUID\_CHEMICALS</code>      | <code className="whitespace-nowrap">CHEMICALS\_TRAIN</code>                                                                        | Liquid chemicals carried in tank or specialized wagons.                                                                                        |
| <code className="whitespace-nowrap">OIL</code>                    | <code className="whitespace-nowrap">CHEMICALS\_TRAIN</code>                                                                        | Crude oil or refined petroleum products carried in tank equipment.                                                                             |
| <code className="whitespace-nowrap">SOLID\_CHEMICALS</code>       | <code className="whitespace-nowrap">CHEMICALS\_TRAIN</code>                                                                        | Solid chemical products carried in appropriate specialized equipment.                                                                          |
| <code className="whitespace-nowrap">MANUFACTURED\_PRODUCTS</code> | <code className="whitespace-nowrap">MANUFACTURED\_PRODUCTS\_TRAIN</code>                                                           | Consumer or industrial manufactured goods.                                                                                                     |

For containerized categories such as GENERAL and REFRIGERATED\_BULK, TerraTwin applies country specific defaults when selecting the container train configuration. European container rail is modelled as single-stacked, while countries where double-stacking is typical, such as the USA and India, default to double-stacked container trains.

<Note>
  If `cargo.category` is omitted, it defaults to `GENERAL`. With `trainType: "UNIT"`, that means TerraTwin will usually treat the cargo as containerized unless you provide a more specific category.
</Note>

***

## Energy type and electrification

`energyType` influences rail emissions because electric and diesel traction use different emissions factors.
Rail supports two values:

| Energy type   | What it represents                                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ELECTRICITY` | Energy supplied from the national electrical grid, including transmission, distribution, and pantograph connection losses. |
| `DIESEL`      | Petroleum diesel fuel, with country-specific biofuel content where applicable.                                             |

The default is `ELECTRICITY`, but this does not mean the whole route is forced to be electric.
Electricity is only used where the rail line supports electric traction.
Where the route uses non-electrified rail infrastructure, TerraTwin models diesel traction for that part of the route.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 1,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "GBSOU"
  },
  "destination": {
    "type": "RAIL_YARD",
    "address": "Wentloog Freight Terminal",
    "countryCode": "GB"
  },
  "transportChain": [
    {
      "type": "RAIL",
      "trainType": "UNIT",
      "energyType": "ELECTRICITY"
    }
  ]
}
```

<Frame caption="Southampton to Cardiff, switching from diesel (orange) to electric (green) on the Filton Chord">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/rail-transport/southampton-to-cardiff-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=5ac659454e584b0ae736b2bae63add06" width="565" height="350" data-path="images/rail-transport/southampton-to-cardiff-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/rail-transport/southampton-to-cardiff-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=a15d0768584adc9dfb12305c7150adba" width="565" height="350" data-path="images/rail-transport/southampton-to-cardiff-dark.png" />
</Frame>

<Note>
  For electric rail sections, emissions are calculated country by country as the train passes through each national grid.
  When a rail route crosses a country border, TerraTwin switches the electricity emissions factor at that border.
  A route from Belgium through Germany into Poland, for example, can use Belgian grid factors, then German grid factors, then Polish grid factors for the electric portions in each country.
</Note>

***

## Dates and time zones

`departureDateTime` and `arrivalDateTime` are optional, but provide them when they are known.
They make emissions certificates and analytics more useful by linking results to the period in which the transport occurred.

```json theme={null}
{
  "type": "RAIL",
  "vehicle": "AVERAGE_TRAIN",
  "departureDateTime": "2025-03-28T09:00",
  "arrivalDateTime": "2025-03-28T18:30",
  "energyType": "ELECTRICITY"
}
```

Local date-times are interpreted using the time zone of the relevant rail yard:

* `departureDateTime` is resolved using the start location's time zone.
* `arrivalDateTime` is resolved using the end location's time zone.

Dates can be supplied in several formats:

**UTC**

```json theme={null}
{ "departureDateTime": "2026-04-12T08:30:00Z" }
```

**Local time**

```json theme={null}
{ "departureDateTime": "2026-04-12T08:30:00" }
```

Interpreted using the start location's time zone for `departureDateTime`, or the end location's time zone for `arrivalDateTime`.

**Explicit offset**

```json theme={null}
{ "departureDateTime": "2026-04-12T08:30:00+02:00" }
```

**Date only**

```json theme={null}
{ "departureDateTime": "2026-04-12" }
```

***

## Route polylines

By default, calculation results do not include the geometry of the calculated rail route.

Set the top-level `options.includeRoutePolylines` property to `true` when you need route geometry for mapping, visualization, or downstream spatial processing:

```json theme={null}
{
  "options": {
    "includeRoutePolylines": true
  },
  "cargo": {
    "weight": {
      "value": 20,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "PLACE",
    "postcode": "CF10 1EP",
    "countryCode": "GB"
  },
  "destination": {
    "type": "PLACE",
    "postcode": "8000",
    "countryCode": "BE"
  },
  "transportChain": [
    {
      "type": "RAIL"
    }
  ]
}
```

When enabled, the `RAIL` result includes a `route` property containing the full train route encoded using the Google Encoded Polyline Algorithm Format.

The rail polyline represents the train movement between the selected rail yards. If TerraTwin adds first-mile or last-mile road transport, those connector movements are returned as separate `ROAD` results. Because `includeRoutePolylines` is a top-level option, their corresponding `route` properties are also included.

<Note>
  `includeRoutePolylines` defaults to `false`. When it is omitted or set to `false`, `route` properties are not included in the response.
</Note>

***

## Routing failure and mode fallback

Rail routing can fail when TerraTwin cannot build a feasible rail operation for the requested leg.
This can happen when no rail yard can be reached from the start or end location, or when no connecting rail route can be found between the selected rail yards.

Use `options.fallbackTransportModes` to let TerraTwin switch to another transport mode when the requested rail operation cannot be realized.
Fallback modes are tried in the order you provide, excluding the mode that failed.

```json theme={null}
{
  "options": {
    "fallbackTransportModes": ["ROAD", "WATER", "AIR"]
  },
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Reykjavik",
    "countryCode": "IS"
  },
  "destination": {
    "type": "PLACE",
    "city": "Oslo",
    "countryCode": "NO"
  },
  "transportChain": [
    {
      "type": "RAIL"
    }
  ]
}
```

<Frame caption="Reykjavik to Oslo failover to `ROAD` (and RoRo ferry) transport">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/reykjavik-to-oslo-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=22736951b6cb2ce17cf014438e23c581" width="1740" height="879" data-path="images/rail-transport/reykjavik-to-oslo-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/rail-transport/reykjavik-to-oslo-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=57909ef27ff2c571f12af6e683781b9c" width="1740" height="879" data-path="images/rail-transport/reykjavik-to-oslo-dark.png" />
</Frame>

In this request, TerraTwin first attempts to calculate the leg as rail transport.
This fails because there are no railways on Iceland, so no rail route can be generated from Reykjavik.
TerraTwin then tries the fallback modes in order: `ROAD`, `WATER`, then `AIR`.
The `ROAD` fallback succeeds because the route can be calculated as a road journey with RoRo ferry connections from Seyðisfjörður to Kristiansand.
Since `ROAD` is the first fallback mode that can be routed and calculated, that result is returned.

If `firstMile` or `lastMile` settings are configured on the rail leg, TerraTwin applies them to fallback modes where they are relevant.
If every fallback attempt fails, the API returns the error from the final fallback mode attempted.

<Note>
  If a rail operation fails and TerraTwin uses a fallback mode instead, any `id` or `context` provided on the failed rail operation is preserved and returned with the replacement operation's result.
</Note>

***

## Recommendations

<Steps>
  <Step title="Set the rail mode explicitly">
    Use `type: "RAIL"` in the transport operation when the leg is known to move by train.
  </Step>

  <Step title="Provide the vehicle when the train is known">
    Set `vehicle` to the exact supported train class when the train consist is known. This avoids automatic selection and gives the most direct calculation input.
  </Step>

  <Step title="Use trainType for the operating pattern">
    Use `MANIFEST` for mixed cargo services and `UNIT` for dedicated commodity trains.
  </Step>

  <Step title="Add grossTrainWeight for manifest trains">
    For `MANIFEST` trains, provide gross train weight when known so TerraTwin can select the correct train size.
  </Step>

  <Step title="Set the cargo category for unit trains">
    For `UNIT` trains, provide `cargo.category` so TerraTwin can select the correct dedicated train type. Do not rely on the default `GENERAL` category unless the cargo should be treated as containerized general freight.
  </Step>

  <Step title="Review energy assumptions">
    The default is electric traction where supported, with diesel used on non-electrified rail sections. Set `energyType: "DIESEL"` when the service is known to be diesel hauled.
  </Step>

  <Step title="Configure first and last mile when known">
    Use `firstMile` and `lastMile` when the origin or destination is not a rail yard and you know the road vehicle details. Otherwise, let TerraTwin choose appropriate road defaults.
  </Step>

  <Step title="Include route geometry when needed">
    Set `options.includeRoutePolylines` to `true` when you need the calculated train route in the response. If the journey includes first-mile or last-mile road connectors, use the separate `route` value from each returned transport result to reconstruct the complete journey.
  </Step>

  <Step title="Use fallback modes for uncertain routability">
    Add `options.fallbackTransportModes` when a requested rail route may not be feasible and another mode should be attempted automatically.
  </Step>
</Steps>