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 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.
Mode
Use type: "WATER" in a transportChain transport element.TerraTwin treats that element as a requested water leg between the surrounding transport chain locations.
Vessel
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.
Harbors
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.
Connectors
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.
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.
First mile
Voyage
Last mile
〒211-0063 Kawasaki to Port of Tokyo [JPTYO]
Port of Tokyo [JPTYO] to Port of Antwerp [BEANR]
Port of Antwerp [BEANR] to 60306 Frankfurt
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:
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.
Port of Long Beach [USLGB] to Port of Civitavecchia [ITCVV]
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.
The mode is selected with the type property on a transport operation:
{ "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.
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 for selecting the hub location and hubType.
Bordeaux to Sofia via the ports of Marseille [FRMRS] and Burgas [BGBOJ]
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.
Mongstad Refinery [NOMON] to Butinge Marine Terminal [LTBOT]
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.
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.
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:
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.
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 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.
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.
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.
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:
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.
Port of Chicago [USCAY] to Barcelona [ESBCN] via the St. Lawrence Seaway
Changing only the cargo category changes the default vessel type:
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.
Port of Chicago [USCAY] to Barcelona [ESBCN] via the Port of Baltimore
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.
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:
{ "type": "WATER"}
This behaves as though the following constraints were supplied:
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:
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.
Shanghai [CNSHG] to Rotterdam [NLRTM] via the Northeast Passage
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.
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.
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.
1
First mile road
Cargo moves by road from Real Casa de Correos in Madrid to the selected departure harbor at Valencia [ESVLC].
First mile road from Madrid to Valencia [ESVLC]
2
Departure harbor hub
TerraTwin inserts a maritime terminal hub by default to model transfer from road to water at Valencia.
Departure harbor hub at Valencia [ESVLC]
3
Water transport
Cargo moves by container vessel from Valencia [ESVLC] to Ploče [HRPLE].
Water transport from Valencia [ESVLC] to Ploče [HRPLE]
4
Arrival harbor hub
TerraTwin inserts a maritime terminal by default to model transfer from water to road at Ploče.
Arrival harbor hub at Ploče [HRPLE]
5
Last mile road
Cargo moves by road from the selected arrival harbor at Ploče [HRPLE] to Cara Dušana 10 in Belgrade.
Last mile road from Ploče [HRPLE] to 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, and 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.
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.
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.
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:
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.
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.
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.
Santiago to Easter Island falls back to AIR transport
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.
Use type: "WATER" in the transport operation when the leg is known to move by maritime vessel.
2
Provide the vessel when known
Set vehicle to the vessel type when it is known. This avoids relying on cargo category defaults.
3
Provide cargo category when the vessel is unknown
Use cargo.category so TerraTwin can default to an appropriate vessel family, such as container, bulker, tanker, refrigerated bulker, or automobile carrier.
4
Add capacity or size when available
Prefer capacity when the numeric capacity is known. Use size when only the commercial size class is known.
5
Use harbors directly when the ports are 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.
6
Configure first and last mile when known
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.
7
State routing assumptions with navigation constraints
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.
8
Include route geometry when needed
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.
9
Use fallback modes for uncertain routability
Add options.fallbackTransportModes when a requested water route may not be feasible and another mode should be attempted automatically.
