> ## 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.
# Water transport
> Use WATER transport operations to calculate emissions for cargo moved by maritime vessel.
Water transport operations model cargo moved by vessel between harbors.
Set the transport operation `type` to `WATER` within a [transport chain](/content/guides/transport-chains) when a shipment leg is moved by sea, coastal shipping, inland waterway vessel, or another harbor-to-harbor maritime service.
TerraTwin can calculate water emissions from a very small amount of information, but water transport is especially sensitive to the vessel, the harbors used, the cargo category, and route constraints such as canals and Arctic passages.
The selected vessel affects emissions intensity, harbor compatibility, capacity assumptions, and which waterways can be used.
Use `type: "WATER"` in a `transportChain` transport element.
TerraTwin treats that element as a requested water leg between the surrounding transport chain locations.
Use `vehicle` when you know the vessel family.
If the vessel is not supplied, TerraTwin uses `cargo.category` to select a suitable vessel type, then determines capacity from `capacity`, `size`, or harbor compatibility.
If the leg does not start or end at a `HARBOR`, TerraTwin selects suitable harbors automatically.
Harbor selection considers vessel compatibility, proximity, and customs-border effects.
If the origin or destination is not already a harbor, TerraTwin can automatically add first-mile and last-mile road transport.
Use `firstMile` and `lastMile` when the road vehicle configuration is known.
Use `WATER` when cargo is modeled as maritime cargo moving between harbors. A road journey that happens to use a roll-on/roll-off ferry is normally modeled as `ROAD`; TerraTwin can include those ferry movements as sub-operations of the road route.
***
## Basic shape
A minimal water operation only needs `type: "WATER"` in the transport chain:
```json theme={null}
{
"cargo": {
"weight": {
"value": 100,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"postcode": "131-0045",
"countryCode": "JP"
},
"destination": {
"type": "PLACE",
"postcode": "60306",
"countryCode": "DE"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
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 harbors, TerraTwin selects suitable harbors and adds road connector movements where needed.
The more information you can provide about the vessel and cargo, the more accurately TerraTwin can model the transport operation.
For example, if the shipment is known to move as container cargo between two named ports, provide the harbors, vessel family, size/capacity, and container type code:
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 12,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "HARBOR",
"unLoCode": "USLGB"
},
"destination": {
"type": "HARBOR",
"unLoCode": "ITCVV"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "CONTAINER",
"size": "PANAMAX",
"containerTypeCode": "22T4"
}
]
}
```
This asks TerraTwin to model manufactured products moving on a `PANAMAX` container vessel, using an ISO 6346 container size/type code.
Because both endpoints are harbors, no automatic first-mile or last-mile road connectors are needed.
***
## Properties
| Property | Required | What it does |
| ---------------------------------------------------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type | Yes | Selects the transport mode. Use `WATER`. |
| vehicle | No | Identifies the vessel type directly, such as `CONTAINER`, `BULKER`, or `OIL_TANKER`. When omitted, TerraTwin defaults the vessel type from `cargo.category`. |
| capacity | No | Numeric vessel capacity. Requires `value` and `unit`. Used to select a capacity band for the chosen vessel type. |
| size | No | Vessel size class, such as `PANAMAX`, `NEO_PANAMAX`, `HANDYMAX`, or `VLCC`. Used when `capacity` is not provided. |
| containerTypeCode | No | ISO 6346 container size/type code. Used for container vessels to distinguish 20-foot containers, 40-foot containers, and ISO tanks. |
| energyType | No | Vessel propulsion energy. Use `HFO`, `VLSFO`, or `MDO` when known. Otherwise TerraTwin defaults it from vessel type, capacity, and voyage region. |
| navigationConstraints | No | Canals and passages that the water route must avoid, such as `AVOID_SUEZ_CANAL` or `AVOID_PANAMA_CANAL`. |
| 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-harbor origin to the selected departure harbor. |
| lastMile | No | Road vehicle configuration for the automatic road movement from the selected arrival harbor to a non-harbor 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 water operation falls back to another mode. |
***
## Selecting water as the mode
The mode is selected with the `type` property on a transport operation:
```json theme={null}
{
"transportChain": [
{
"type": "WATER"
}
]
}
```
The water 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": 500,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"address": "33460 Margaux-Cantenac",
"countryCode": "FR"
},
"destination": {
"type": "PLACE",
"address": "La Cave du Moulin",
"countryCode": "BG"
},
"transportChain": [
{
"type": "RAIL"
}, {
"type": "HUB",
"hubType": "MARITIME_TERMINAL",
"location": {
"type": "HARBOR",
"unLoCode": "FRMRS"
}
}, {
"type": "WATER"
}, {
"type": "HUB",
"hubType": "MARITIME_TERMINAL",
"location": {
"type": "HARBOR",
"unLoCode": "BGBOJ"
}
}, {
"type": "ROAD"
}
]
}
```
In this example, the `HUB` elements explicitly separate the road, water, and rail legs.
The water leg runs from the Marseille harbor hub to the Burgas harbor hub.
See the [logistics hubs guide](/content/guides/hubs) for selecting the hub location and `hubType`.
***
## Vessel selection
There are several ways to influence vessel selection.
You do not need to provide all of them.
In general, the more information you can provide about the vessel, cargo, and capacity, the more accurately TerraTwin can calculate emissions.
TerraTwin applies vessel and capacity selection in this order:
| Priority | Inputs provided | Selection behavior |
| -------: | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 1 | `vehicle` | Uses the specified vessel type directly. |
| 2 | `cargo.category` | Defaults the vessel type from the cargo category when `vehicle` is not provided. |
| 3 | `capacity` | Maps the supplied numeric capacity to the selected vessel type's capacity band. |
| 4 | `size` | Converts the supplied vessel size class to a capacity band when `capacity` is not provided. |
| 5 | Harbor compatibility | Defaults to the largest capacity band of the selected vessel type that can be accommodated by both origin and destination harbors. |
`vehicle` controls the vessel family. `capacity` and `size` control the capacity band within that family. If you know both the vessel family and capacity, provide both.
***
## Vessel type selection with `vehicle`
Use `vehicle` when you know the vessel type.
Supported values are:
| Vessel value | Typical use |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| CONTAINER | Standardized shipping containers. Default for `GENERAL` and `MANUFACTURED_PRODUCTS` cargo. |
| BULKER | Unpackaged dry bulk goods. Default for `BUILDING_MATERIALS`, `CEREALS`, `COAL_AND_STEEL`, and `SOLID_CHEMICALS` cargo. |
| GENERAL\_CARGO | Packaged, breakbulk, or mixed non-container cargo. Also used as a retry fallback when a defaulted vessel type cannot be matched to suitable harbors. |
| LIQUEFIED\_GAS\_TANKER | LNG, LPG, and other liquefied gases. Default for `LIQUEFIED_GAS` cargo. |
| OIL\_TANKER | Crude oil and refined petroleum products. Default for `OIL` cargo. |
| CHEMICAL\_TANKER | Liquid chemicals in segregated tanks. Default for `LIQUID_CHEMICALS` cargo. |
| OTHER\_LIQUIDS\_TANKER | Other liquid cargo such as wine or fruit juice. Set directly when this vessel type is appropriate. |
| REFRIGERATED\_BULKER | Refrigerated bulk cargo. Default for `REFRIGERATED_BULK` cargo. |
| AUTOMOBILE\_CARRIER | Roll-on/roll-off vessel for finished vehicles and other wheeled cargo. Default for `AUTOMOBILES` cargo. |
```json theme={null}
{
"cargo": {
"category": "OIL",
"weight": {
"value": 40000,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "HARBOR",
"unLoCode": "NOMON"
},
"destination": {
"type": "HARBOR",
"unLoCode": "LTBOT"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "OIL_TANKER"
}
]
}
```
When `vehicle` is set, TerraTwin uses that vessel type for vessel selection.
`cargo.category` may still affect other parts of the calculation, such as hub defaults, connector road vehicle selection, and climate-control assumptions.
If `vehicle` is omitted, `cargo.category` defaults to `GENERAL`, which means the water operation will usually be treated as containerized general freight unless you provide a more specific cargo category or vessel type.
***
## Cargo category vessel defaults
When the vessel is not known, provide `cargo.category` so TerraTwin can choose a suitable default vessel type.
| `cargo.category` | Default vessel type | Notes |
| ----------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| AUTOMOBILES | AUTOMOBILE\_CARRIER | Finished vehicles carried on roll-on/roll-off automobile carriers. |
| BUILDING\_MATERIALS | BULKER | Bulk or heavy construction materials such as cement, sand, gravel, stone, and lumber. |
| CEREALS | BULKER | Grain crops and similar agricultural bulk goods. |
| COAL\_AND\_STEEL | BULKER | Heavy dry bulk commodities such as coal, ore, and steel-related products. |
| GENERAL | CONTAINER | General freight is treated as containerized unless a more specific vessel input is provided. |
| LIQUEFIED\_GAS | LIQUEFIED\_GAS\_TANKER | LNG, LPG, and similar liquefied gases. |
| LIQUID\_CHEMICALS | CHEMICAL\_TANKER | Liquid chemicals carried in segregated tanks. |
| MANUFACTURED\_PRODUCTS | CONTAINER | Consumer or industrial manufactured goods, normally modeled as containerized. |
| OIL | OIL\_TANKER | Crude oil and refined petroleum products. |
| REFRIGERATED\_BULK | REFRIGERATED\_BULKER | Bulk goods requiring refrigerated transport. |
| SOLID\_CHEMICALS | BULKER | Solid chemical products carried as bulk cargo. |
Cargo category can also change which harbors are selected.
For example, manufactured products default to container shipping, so TerraTwin looks for harbors compatible with container vessels.
Building materials default to bulker shipping, so different harbors may be eligible for the same origin and destination.
If no suitable harbor can be found and the vessel type was defaulted from cargo category, TerraTwin retries harbor selection using `GENERAL_CARGO`. This allows service to places where specialized vessel classes are not supported.
***
## Capacity and size
Use `capacity` when you know the vessel's numeric carrying capacity.
It requires a `value` and a `unit`:
```json theme={null}
{
"type": "WATER",
"vehicle": "BULKER",
"capacity": {
"value": 75000,
"unit": "DEAD_WEIGHT_TONNE"
}
}
```
Supported capacity units are:
| Unit | Meaning | Native use |
| ------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `DEAD_WEIGHT_TONNE` | Total weight a vessel can safely carry, including cargo, fuel, provisions, and crew. | Native for `BULKER`, `GENERAL_CARGO`, `OIL_TANKER`, `CHEMICAL_TANKER`, `OTHER_LIQUIDS_TANKER`, and `REFRIGERATED_BULKER`. |
| `GROSS_TONNE` | Measure of the vessel's total internal volume. | Native for `AUTOMOBILE_CARRIER`. |
| `CONTAINER` | Number of standard twenty-foot containers, commonly treated as TEU. | Native for `CONTAINER` vessels. |
| `CUBIC_METER` | Volume capacity available for liquid or bulk cargo. | Native for `LIQUEFIED_GAS_TANKER`. |
If the supplied unit is not the native capacity unit for the vessel type, TerraTwin converts it to the vessel type's native unit before assigning a capacity band.
For example, a `GENERAL_CARGO` vessel capacity supplied in `GROSS_TONNE` is converted to an estimated `DEAD_WEIGHT_TONNE` value before capacity banding.
Use `size` when you know the commercial vessel size class but not the exact capacity:
```json theme={null}
{
"type": "WATER",
"vehicle": "CONTAINER",
"size": "NEO_PANAMAX"
}
```
Common size classes include:
| Vessel family | Size classes |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| Dry bulk | `MINI_BULKER`, `SMALL_HANDY`, `HANDY`, `HANDYMAX`, `SUPRAMAX`, `ULTRAMAX`, `CAPESIZE`, `CHINAMAX`, `VALEMAX` |
| Tanker | `GENERAL_PURPOSE`, `MEDIUM_RANGE`, `LR1`, `LR2`, `AFRAMAX`, `SUEZMAX`, `VLCC`, `ULCC` |
| LNG carrier | `Q_FLEX`, `Q_MAX` |
| Container vessel | `SMALL_FEEDER`, `FEEDER`, `FEEDERMAX`, `PANAMAX`, `POST_PANAMAX`, `NEO_PANAMAX`, `ULTRA_LARGE` |
A size class is converted into a capacity band for the selected vessel type.
Some size classes are strongly associated with a vessel family, but TerraTwin can still convert across families using fleet-derived capacity relationships.
For example, if `VLCC` is used with `BULKER`, TerraTwin still converts the class to a deadweight-tonne capacity band.
Size can also affect routing.
Some waterways are only available to vessels below a certain size, draft, or capacity band.
When a vessel is too large for a waterway, TerraTwin routes around it instead of using it.
For example, consider a container movement from London Gateway \[`GBSHV`] to the Port of Gdańsk \[`PLGDN`].
With a `PANAMAX` container vessel, TerraTwin routes around the Jutland peninsula because the vessel is too large to use the Kiel Canal.
```json theme={null}
{
"type": "WATER",
"vehicle": "CONTAINER",
"size": "PANAMAX"
}
```
With a smaller `FEEDER` container vessel, TerraTwin can route the same movement through the Kiel Canal.
```json theme={null}
{
"type": "WATER",
"vehicle": "CONTAINER",
"size": "FEEDER"
}
```
Only the vessel size changes in this example. The route, distance, and emissions change as a result.
Prefer `capacity` over `size` when both are known. `capacity` is more specific and is evaluated before `size`.
***
## Container vessels and container type codes
For container vessel movements, use `containerTypeCode` when the ISO 6346 size/type code is known.
See the [BIC guide to ISO 6346 container size/type codes](https://www.bic-code.org/size-type-code/) for examples of common codes.
TerraTwin maps the code to one of three container categories, each with different container-vessel emissions intensities:
| Container category | Example codes | Meaning |
| ------------------ | -------------- | ------------------------------------------------------------------------------------ |
| 20-foot container | `22G1`, `22G` | Standard 20-foot dry container category. |
| 40-foot container | `42G1`, `42R1` | Standard 40-foot container category, including refrigerated variants where relevant. |
| ISO tank | `22T1` | Tank container category. |
```json theme={null}
{
"type": "WATER",
"vehicle": "CONTAINER",
"containerTypeCode": "22T1"
}
```
`containerTypeCode` is most useful when the cargo is known to be containerized and the actual container equipment type is available from shipment records.
For temperature controlled container cargo, set `cargo.climateControl` to `REQUIRED`.
Where relevant, TerraTwin models reefer container energy use and increases emissions intensity accordingly.
***
## Harbor selection
Water transport runs between harbors.
You can identify harbors directly using `type: "HARBOR"` and a UN/LOCODE.
For the full set of supported location types and identifiers, see the [locations guide](/content/guides/locations).
```json theme={null}
{
"origin": {
"type": "HARBOR",
"unLoCode": "GBSOU"
},
"destination": {
"type": "HARBOR",
"unLoCode": "DEHAM"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
When the start or end location is already a known harbor, TerraTwin uses that harbor as provided.
This is true even if TerraTwin would not have selected that harbor automatically because its master data indicates that the harbor does not meet the compatibility constraints for the chosen vessel type or capacity band.
When the start or end location is not a harbor, TerraTwin selects a suitable harbor automatically.
Automatic harbor selection considers:
* **Vessel compatibility** - whether the harbor supports the selected vessel type and, when known, the selected capacity band.
* **Distance from the supplied location** - closer harbors are generally preferred.
* **Customs-border crossings** - harbors that require an unnecessary customs-border crossing are heavily penalized.
Harbor selection can change when the vessel type or capacity changes.
For example, this request models grain moving from Chicago to Barcelona:
```json theme={null}
{
"cargo": {
"category": "CEREALS",
"weight": {
"value": 100,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "PLACE",
"city": "Chicago",
"countryCode": "US"
},
"destination": {
"type": "PLACE",
"city": "Barcelona",
"countryCode": "ES"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
Here, `CEREALS` defaults to a `BULKER` vessel.
For a Great Lakes to Europe movement, this is typically represented as a Seawaymax bulker: an ocean-going bulk vessel sized to transit the St. Lawrence Seaway.
TerraTwin selects the Port of Chicago which accommodates such bulker traffic and routes the voyage from there, through the Great Lakes and the St. Lawrence Seaway, and out to the Atlantic before crossing to Europe.
Changing only the cargo category changes the default vessel type:
```json theme={null}
{
"cargo": {
"category": "GENERAL",
"weight": {
"value": 100,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "PLACE",
"city": "Chicago",
"countryCode": "US"
},
"destination": {
"type": "PLACE",
"city": "Barcelona",
"countryCode": "ES"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
Here, `GENERAL` defaults to a `CONTAINER` vessel.
TerraTwin therefore looks for harbors compatible with container traffic.
Because the Great Lakes ports do not meet the container vessel compatibility constraints in TerraTwin's master data, TerraTwin first moves the freight by road to the Port of Baltimore, then transported by container vessel to Barcelona.
Use explicit harbors deliberately. They are useful when the actual port is known, but they can override TerraTwin's automatic vessel compatibility checks during harbor selection.
***
## Navigation constraints
Use `navigationConstraints` to specify canals and passages that must not be used when routing the voyage.
Routes through any listed waterway are excluded from the route search.
Supported constraints are:
| Constraint | Effect |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| AVOID\_SUEZ\_CANAL | Do not use the Suez Canal. |
| AVOID\_PANAMA\_CANAL | Do not use the Panama Canal. |
| AVOID\_KIEL\_CANAL | Do not use the Kiel Canal. |
| AVOID\_CORINTH\_CANAL | Do not use the Corinth Canal. |
| AVOID\_NORTHEAST\_PASSAGE | Do not route through the Arctic Ocean along the northern coast of Russia between Europe and Asia. |
| AVOID\_NORTHWEST\_PASSAGE | Do not route through the Arctic Ocean along the northern coasts of Canada and Alaska between the Pacific and Atlantic. |
By default, TerraTwin avoids the Northeast and Northwest passages:
```json theme={null}
{
"type": "WATER"
}
```
This behaves as though the following constraints were supplied:
```json theme={null}
{
"type": "WATER",
"navigationConstraints": [
"AVOID_NORTHEAST_PASSAGE",
"AVOID_NORTHWEST_PASSAGE"
]
}
```
When `navigationConstraints` is not provided, TerraTwin uses its default routing assumptions.
For Asia-to-Europe container traffic, this typically allows the Suez Canal while avoiding Arctic passages.
For example, this request routes a container vessel from Shanghai to Rotterdam:
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 20,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "HARBOR",
"unLoCode": "CNSHG"
},
"destination": {
"type": "HARBOR",
"unLoCode": "NLRTM"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "CONTAINER"
}
]
}
```
With no custom navigation constraints, TerraTwin routes the voyage through the Suez Canal.
To model a route that avoids the Suez Canal while still avoiding Arctic passages, provide all three constraints:
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 20,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "HARBOR",
"unLoCode": "CNSHG"
},
"destination": {
"type": "HARBOR",
"unLoCode": "NLRTM"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "CONTAINER",
"navigationConstraints": [
"AVOID_SUEZ_CANAL",
"AVOID_NORTHEAST_PASSAGE",
"AVOID_NORTHWEST_PASSAGE"
]
}
]
}
```
This is the typical way to model a route that goes around the Cape of Good Hope instead of using the Suez Canal.
If you provide only `AVOID_SUEZ_CANAL`, the Arctic passage constraints are no longer included in the custom list:
```json theme={null}
{
"cargo": {
"category": "MANUFACTURED_PRODUCTS",
"weight": {
"value": 20,
"unit": "METRIC_TONNE"
}
},
"origin": {
"type": "HARBOR",
"unLoCode": "CNSHG"
},
"destination": {
"type": "HARBOR",
"unLoCode": "NLRTM"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "CONTAINER",
"navigationConstraints": [
"AVOID_SUEZ_CANAL"
]
}
]
}
```
In this example, TerraTwin avoids the Suez Canal but is allowed to use Arctic passages, resulting in a route through the Northeast Passage, which is probably not the expected result.
When you provide `navigationConstraints`, include every passage that should be avoided. For example, if you avoid the Suez Canal but still want Arctic passages excluded, include both `AVOID_NORTHEAST_PASSAGE` and `AVOID_NORTHWEST_PASSAGE` in the same list.
Navigation constraints are not the only routing limits.
Physical restrictions still apply even when a waterway is not listed in `navigationConstraints`.
For example, a vessel that is too large or has too deep a draft may be unable to use a canal even when that canal is not explicitly avoided.
Use `navigationConstraints` for deliberate routing assumptions, scenario analysis, sanctions or operational restrictions, and cases where shipment records indicate that a canal or passage was not used.
***
## Energy type
`energyType` specifies the marine fuel used for vessel propulsion.
Water transport supports three values:
| Energy type | What it represents |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `HFO` | Heavy fuel oil. Used as the default fuel oil for ocean-going vessels on trade lanes where low-sulfur fuel rules are not assumed to apply. |
| `VLSFO` | Very low sulfur fuel oil. Used by TerraTwin for vessels that would otherwise use fuel oil on European, Mediterranean, and North American trade lanes. |
| `MDO` | Marine diesel oil. Commonly used by smaller commercial vessels, ferries, offshore ships, inland waterway vessels, and other vessels where distillate marine fuel is more representative than fuel oil. |
```json theme={null}
{
"type": "WATER",
"vehicle": "CONTAINER",
"energyType": "VLSFO"
}
```
If `energyType` is omitted, TerraTwin defaults it based on:
* the vessel type;
* the vessel capacity;
* the voyage region, because sulfur-emission limits can restrict which marine fuels may be used.
For vessels expected to use fuel oil, TerraTwin defaults to `VLSFO` on European, Mediterranean, and North American trade lanes, and `HFO` elsewhere.
***
## Automatic first and last mile
When a water leg starts or ends anywhere apart from a harbor, TerraTwin automatically connects the location to a selected harbor by road.
```json theme={null}
{
"cargo": {
"weight": {
"value": 5,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"address": "Real Casa de Correos, 28013 Madrid",
"countryCode": "ES"
},
"destination": {
"type": "PLACE",
"address": "Cara Dušana 10, Beograd 11000",
"countryCode": "RS"
},
"transportChain": [
{
"type": "WATER",
"vehicle": "CONTAINER"
}
]
}
```
This request starts and ends at street addresses, so TerraTwin adds road connections on both sides of the water leg.
For this example, TerraTwin selects Valencia \[`ESVLC`] as the departure harbor and Ploče \[`HRPLE`] as the arrival harbor.
Ploče is a smaller harbor, but it has a container terminal and can accommodate feeder-size container vessels.
Cargo moves by road from Real Casa de Correos in Madrid to the selected departure harbor at Valencia \[`ESVLC`].
TerraTwin inserts a maritime terminal hub by default to model transfer from road to water at Valencia.
Cargo moves by container vessel from Valencia \[`ESVLC`] to Ploče \[`HRPLE`].
TerraTwin inserts a maritime terminal by default to model transfer from water to road at Ploče.
Cargo moves by road from the selected arrival harbor at Ploče \[`HRPLE`] to Cara Dušana 10 in Belgrade.
These hubs are inserted while `options.hubInsertion` is set to its default automatic behavior.
Their types can be changed using `options.defaultHubTypes`.
For example, liquid cargo defaults to a `LIQUID_BULK_TERMINAL` for applicable road-to-water and water-to-road transfers rather than a `MARITIME_TERMINAL`. See [Automatic hub insertion](/content/guides/hubs#automatic-hub-insertion), and [How a hub type is selected](/content/guides/hubs#how-a-hub-type-is-selected) for hub type selection and insertion rules.
If `firstMile` or `lastMile` is not provided, TerraTwin selects an appropriate road vehicle based on the country, cargo category, trip distance, and cargo weight.
When the road vehicle is known, provide `firstMile` and/or `lastMile` using the same road vehicle configuration fields used by road transport.
```json theme={null}
{
"transportChain": [
{
"type": "WATER",
"firstMile": {
"structure": "ARTICULATED",
"grossWeight": {
"value": 40,
"unit": "METRIC_TONNE"
},
"energyType": "DIESEL"
},
"lastMile": {
"vehicle": "LCV_BELOW_3500_KG",
"energyType": "GASOLINE"
}
}
]
}
```
For more detail on these road vehicle fields, see the [road transport guide](/content/guides/road-transport).
If the origin is already a `HARBOR`, no first-mile road connection is needed. If the destination is already a `HARBOR`, no last-mile road connection is needed.
***
## 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": "WATER",
"vehicle": "CONTAINER",
"departureDateTime": "2025-03-28T09:00",
"arrivalDateTime": "2025-04-20T14:30"
}
```
Local date-times are interpreted using the time zone of the relevant water operation location:
* `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 water 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": 100,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"postcode": "131-0045",
"countryCode": "JP"
},
"destination": {
"type": "PLACE",
"postcode": "60306",
"countryCode": "DE"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
When enabled, the `WATER` result includes a `route` property containing the full route between the selected harbors. The route is encoded using the Google Encoded Polyline Algorithm Format.
The water polyline represents the vessel movement between the departure and arrival harbors. 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.
`includeRoutePolylines` defaults to `false`. When it is omitted or set to `false`, `route` properties are not included in the response.
***
## Routing failure and mode fallback
Water routing can fail when TerraTwin cannot build a feasible maritime operation for the requested leg.
This can happen when no compatible harbors can be reached from the start or end location, or when no connecting water route can be found between the selected harbors.
Use `options.fallbackTransportModes` to let TerraTwin switch to another transport mode when the requested water operation cannot be realized.
Fallback modes are tried in the order you provide, excluding the mode that failed.
```json theme={null}
{
"options": {
"fallbackTransportModes": ["ROAD", "RAIL", "WATER", "AIR"]
},
"cargo": {
"weight": {
"value": 100,
"unit": "KILOGRAM"
}
},
"origin": {
"type": "PLACE",
"city": "Santiago",
"countryCode": "CL"
},
"destination": {
"type": "PLACE",
"city": "Hanga Roa",
"countryCode": "CL"
},
"transportChain": [
{
"type": "WATER"
}
]
}
```
In this request, TerraTwin first attempts to calculate the leg as water transport.
Because Hanga Roa on Easter Island has no cargo harbor, the water operation cannot be built.
TerraTwin then tries the fallback modes in order.
`ROAD` and `RAIL` cannot complete the island connection, and `WATER` has already failed for this leg.
The request succeeds when TerraTwin reaches `AIR`, using Mataveri International Airport \[IATA:`IPC`] on Easter Island.
If every fallback attempt fails, the API returns the error from the final fallback mode attempted.
If a water operation fails and TerraTwin uses a fallback mode instead, any `context` provided on the failed water operation is preserved and returned with the replacement operation's result.
***
## Recommendations
Use `type: "WATER"` in the transport operation when the leg is known to move by maritime vessel.
Set `vehicle` to the vessel type when it is known. This avoids relying on cargo category defaults.
Use `cargo.category` so TerraTwin can default to an appropriate vessel family, such as container, bulker, tanker, refrigerated bulker, or automobile carrier.
Prefer `capacity` when the numeric capacity is known. Use `size` when only the commercial size class is known.
Set locations to `type: "HARBOR"` with `unLoCode` when the actual departure or arrival port is known. Use places when you want TerraTwin to select suitable harbors and add road connectors.
Use `firstMile` and `lastMile` when the origin or destination is not a harbor and you know the road vehicle details. Otherwise, let TerraTwin choose appropriate road defaults.
Use `navigationConstraints` to avoid canals or passages. Include the default Arctic passage constraints as well when you provide a custom list and still want those routes excluded.
Set `options.includeRoutePolylines` to `true` when you need the calculated vessel 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.
Add `options.fallbackTransportModes` when a requested water route may not be feasible and another mode should be attempted automatically.