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

# Air transport

> Use AIR transport operations to calculate emissions for cargo moved by aircraft.

Air transport operations model cargo moved by aircraft between airports.
Set the transport operation `type` to `AIR` within a [transport chain](/content/guides/transport-chains) when a shipment leg is flown.

TerraTwin can calculate air emissions from a very small amount of information, but air transport is especially sensitive to the aircraft and the airports used.
The selected aircraft affects the emissions intensity, the compatible departure and arrival airports, and whether stopovers are needed.

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

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

  <Card title="Aircraft" icon="plane">
    Use `vehicle` when you know the aircraft.

    Aircraft can be supplied by IATA equipment code, ICAO aircraft type designator, or TerraTwin system identifier.
  </Card>

  <Card title="Airports" icon="tower-control">
    If the leg does not start or ends at an `AIRPORT`, TerraTwin will instead select suitable airports automatically.

    Airport selection can take account of the selected aircraft's runway requirements.
  </Card>

  <Card title="Connectors" icon="truck">
    If the origin or destination is not already an airport, 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>
  One requested `AIR` transport element may be realized as several operations in the response: first-mile road, departure airport hub, one or more flights, stopover hubs, arrival airport hub, and last-mile road.
</Note>

***

## Basic shape

A minimal air operation only needs `type: "AIR"` in the transport chain:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "address": "55 Norfolk Street, Sheffield, S1 1DA",
    "countryCode": "GB"
  },
  "destination": {
    "type": "PLACE",
    "address": "Humboldtstraße 5-6, 14467 Potsdam",
    "countryCode": "DE"
  },
  "transportChain": [
    {
      "type": "AIR"
    }
  ]
}
```

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 airports, TerraTwin selects compatible airports and adds road connector movements where needed.

<Tabs defaultTabIndex={1}>
  <Tab title="First mile">
    <Frame caption="The Crucible, Sheffield to Manchester Airport [IATA:`MAN`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/sheffield-to-manchester-airport-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=a8c48fe75a735ea3dd7efc64029e5eba" width="1374" height="450" data-path="images/air-transport/sheffield-to-manchester-airport-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/sheffield-to-manchester-airport-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=f95dd64f0091c70ccc90be91a48c4e28" width="1374" height="450" data-path="images/air-transport/sheffield-to-manchester-airport-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Flight">
    <Frame caption="Manchester Airport [IATA:`MAN`] to Berlin Brandenburg Airport [IATA:`BER`] flight">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/sheffield-to-potsdam-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=2fe38cce0902f660a4475a1c587fd8c9" width="927" height="321" data-path="images/air-transport/sheffield-to-potsdam-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/sheffield-to-potsdam-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=074dd82ec37ee3a0ed01294fdaa3712f" width="927" height="321" data-path="images/air-transport/sheffield-to-potsdam-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Last mile">
    <Frame caption="Berlin Brandenburg Airport [IATA:`BER`] to Museum Barberini, Potsdam">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/berlin-brandenburg-to-potsdam-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=06584ef7d3ef3e846ad30207692e9581" width="810" height="281" data-path="images/air-transport/berlin-brandenburg-to-potsdam-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/berlin-brandenburg-to-potsdam-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=c8354e00628e695ba7e257ac4f80bcc1" width="810" height="281" data-path="images/air-transport/berlin-brandenburg-to-potsdam-dark.png" />
    </Frame>
  </Tab>
</Tabs>

***

When the aircraft is known, provide it with `vehicle`:

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "AIRPORT",
    "iataCode": "PDX"
  },
  "destination": {
    "type": "AIRPORT",
    "iataCode": "MAD"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "BOEING_747_8F_FREIGHTER"
    }
  ]
}
```

This asks TerraTwin to model cargo carried on a Boeing 747-8F dedicated freighter, using TerraTwin’s system identifier.

<Frame caption="Portland International Airport [IATA:`PDX`] to Madrid–Barajas Airport [IATA:`MAD`] with a stopover in Newfoundland">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/portland-to-madrid-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=6b52c3e96b3039b8e1fec153d9301f50" width="1001" height="340" data-path="images/air-transport/portland-to-madrid-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/portland-to-madrid-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=d33062d70c9df3f50627302fa640e556" width="1001" height="340" data-path="images/air-transport/portland-to-madrid-dark.png" />
</Frame>

***

## Properties

| Property            | Required | What it does                                                                                                                                                                                           |
| ------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`              |      Yes | Selects air transport. Use `AIR`.                                                                                                                                                                      |
| `vehicle`           |       No | Identifies the aircraft by TerraTwin system identifier, ICAO code, or IATA code.                                                                                                                       |
| `aircraftType`      |       No | Distinguishes passenger belly freight from dedicated or converted freighter aircraft. Use with IATA or ICAO codes when known.                                                                          |
| `departureDateTime` |       No | The departure date and time. It can also help TerraTwin select the correct year for IATA weighting when the aircraft code is ambiguous.                                                                |
| `arrivalDateTime`   |       No | The arrival date and time. Used when departure time is not provided for date-sensitive defaults.                                                                                                       |
| `firstMile`         |       No | Road vehicle configuration for the automatic road movement from a non-airport origin to the departure airport.                                                                                         |
| `lastMile`          |       No | Road vehicle configuration for the automatic road movement from the arrival airport to a non-airport 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.                                                                                                                               |

***

## Selecting air as the mode

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

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

The air 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": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Broken Hill",
    "countryCode": "AU"
  },
  "destination": {
    "type": "PLACE",
    "city": "New Plymouth",
    "countryCode": "NZ"
  },
  "transportChain": [
    {
      "type": "ROAD"
    }, {
      "type": "HUB",
      "location": {
        "type": "AIRPORT",
        "iataCode": "SYD"
      }
    }, {
      "type": "AIR",
      "vehicle": "A320",
      "aircraftType": "PASSENGER"
    }, {
      "type": "HUB",
      "location": {
        "type": "AIRPORT",
        "iataCode": "AKL"
      }
    }, {
      "type": "ROAD"
    }
  ]
}
```

In this example, the `AIR` operation is anchored between the two airport hubs.
For more detail on chain boundaries, see the [transport chains guide](/content/guides/transport-chains).

<Frame caption="Broken Hill to New Plymouth through Sydney [IATA:`SYD`] and Auckland [IATA:`AKL`] airports">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/broken-hill-to-new-plymouth-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=83a6aa33ff526b7156f430f5a046de3f" width="983" height="400" data-path="images/air-transport/broken-hill-to-new-plymouth-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/broken-hill-to-new-plymouth-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=13333cae4b97bbd0c12de25aa76bff4e" width="983" height="400" data-path="images/air-transport/broken-hill-to-new-plymouth-dark.png" />
</Frame>

<Note>
  The hubs in this example omit `hubType`. With automatic hub insertion enabled, TerraTwin selects their hub types from the surrounding `ROAD` to `AIR` and `AIR` to `ROAD` transitions. With `options.hubInsertion: "MANUAL"`, they remain location boundaries but do not contribute hub emissions. See [How a hub type is selected](/content/guides/hubs#how-a-hub-type-is-selected).
</Note>

***

## Aircraft selection

Use `vehicle` when you know the type of aircraft.
The aircraft can be identified in any of three ways:

| Identifier type               | Example                                                                   | Notes                                                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| TerraTwin system identifier   | <code className="whitespace-nowrap">BOEING\_737\_800BCF\_FREIGHTER</code> | Most specific. The identifier names the exact supported aircraft model and whether it is a belly freight or freighter variant. |
| IATA equipment code           | <code className="whitespace-nowrap">7F8</code>                            | Commercial equipment code. Can distinguish some passenger, combi, and freighter variants.                                      |
| ICAO aircraft type designator | <code className="whitespace-nowrap">B738</code>                           | Operational aircraft type code. May not distinguish passenger and freighter variants.                                          |

```json theme={null}
{
  "type": "AIR",
  "vehicle": "BOEING_737_800BCF_FREIGHTER"
}
```

```json theme={null}
{
  "type": "AIR",
  "vehicle": "7F8"
}
```

```json theme={null}
{
  "type": "AIR",
  "vehicle": "B738"
}
```

A complete list of supported aircraft is available in the [API reference](/api-reference/calculate-transport-emissions).
TerraTwin currently lists 315 supported aircraft variants, including 182 passenger belly freight variants and 133 freighter variants across wide-body aircraft, narrow-body aircraft, regional jets, turboprops, and specialist cargo aircraft.
Examples include `AIRBUS_A320_BELLY_FREIGHT`, `AIRBUS_A330_200F_FREIGHTER`, `BOEING_777_300_BELLY_FREIGHT`, `BOEING_747_8F_FREIGHTER`, `ATR_72_FREIGHTER`, and `EMBRAER_E195_AR_BELLY_FREIGHT`.

<Note>
  Prefer the TerraTwin system identifier when you know the exact supported aircraft variant. It is the least ambiguous option because it already distinguishes belly freight and freighter variants.
</Note>

***

## Passenger belly freight and freighters

Air cargo can be carried in two very different operating contexts:

<Columns cols={2}>
  <Card title="Passenger" icon="user-group">
    Use `aircraftType: "PASSENGER"` when the cargo is carried in the belly hold of a passenger aircraft.

    This is often called **belly freight**.
  </Card>

  <Card title="Freighter" icon="boxes-stacked">
    Use `aircraftType: "FREIGHTER"` when the aircraft is a dedicated or converted cargo aircraft.

    This includes aircraft built for freight and passenger aircraft converted to freighters.
  </Card>
</Columns>

`aircraftType` is useful whenever the exact aircraft variant is not known.

It is important when `vehicle` is an IATA or ICAO code, because those codes may not
identify whether the cargo is carried as belly freight on a passenger aircraft or
on a dedicated freighter.

It is also useful when `vehicle` is not provided at all. In that case, TerraTwin
selects a default aircraft category, but the emissions intensity depends
significantly on whether the cargo is modeled as passenger belly freight or as
dedicated air freight.

When you know the operating type, provide it explicitly:

```json theme={null}
{
  "type": "AIR",
  "vehicle": "A320",
  "aircraftType": "PASSENGER"
}
```

```json theme={null}
{
  "type": "AIR",
  "vehicle": "A320",
  "aircraftType": "FREIGHTER"
}
```

If an IATA or ICAO code maps to both passenger and freighter aircraft, and
`aircraftType` is omitted, TerraTwin calculates emissions for both operating
types. Where several supported aircraft variants match either type, TerraTwin
uses the most common matching passenger variant and the most common matching
freighter variant.

The two results are then weighted using IATA economic reporting shares for
international available cargo tonne-kilometres by cargo business type. The
weighting year comes from `departureDateTime`, then `arrivalDateTime`, or
otherwise the latest year for which TerraTwin has IATA figures.

<Note>
  If the response contains multiple flight entries for one air operation, it will be because an IATA or ICAO code matched both passenger and freighter variants and TerraTwin returned the weighted combined result.
</Note>

***

## Unknown aircraft

If `vehicle` is omitted, TerraTwin uses a generic aircraft emissions factor.
You can still provide `aircraftType` to control whether the generic aircraft represents belly freight or freighter cargo.

```json theme={null}
{
  "type": "AIR",
  "aircraftType": "PASSENGER"
}
```

```json theme={null}
{
  "type": "AIR",
  "aircraftType": "FREIGHTER"
}
```

If both `vehicle` and `aircraftType` are omitted, TerraTwin uses a composite generic aircraft assumption.

Unknown aircraft are not treated as one fixed aircraft for routing.
TerraTwin uses generic aircraft classes so that airport selection and stopover decisions still reflect runway capabilities and aircraft range.

| Generic class                    | Typical role                      | Runway implications                                                                         | Range implications |
| -------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------- | ------------------ |
| Wide-body long-haul aircraft     | Long-haul intercontinental flying | Requires long concrete or asphalt/bitumen runways                                           | Longest range      |
| Narrow-body medium-haul aircraft | Common single-aisle jet flying    | Requires medium-length concrete or asphalt/bitumen runways                                  | Medium range       |
| Regional short-haul aircraft     | Regional jets and turboprops      | Requires shorter paved runways                                                              | Shorter range      |
| All-terrain STOL aircraft        | Short-field turboprop operations  | Can use short runways on more varied surfaces, including gravel, dirt, clay, sand, or grass | Limited range      |
| All-terrain VSTOL aircraft       | Very short-field operations       | Can use extremely short runways on varied surfaces                                          | Very limited range |

When the aircraft is unknown and the origin or destination is not already an
airport, TerraTwin first selects compatible airports, then classifies the
generic aircraft from the runway lengths and surfaces available at those
airports.

For each flight segment, TerraTwin uses the largest compatible generic aircraft
class. This affects both emissions and routing: smaller aircraft can use smaller
airports, but usually have shorter range, which may require additional
stopovers.

<Note>
  The generic aircraft class can change during the journey. After reaching a
  larger stopover airport, TerraTwin can use a larger aircraft class with longer
  range for the next segment.
</Note>

This example shows how small airport constraints can create stopovers even over
a relatively short distance. Because both the origin and destination airports
can only support smaller aircraft, TerraTwin uses a short-range generic aircraft
class and inserts the stopovers needed to complete the route.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "AIRPORT",
    "iataCode": "KQR"
  },
  "destination": {
    "type": "AIRPORT",
    "iataCode": "LEL"
  },
  "transportChain": [
    {
      "type": "AIR"
    }
  ]
}
```

<Frame caption="Karara [IATA:`KQR`] to Lake Evella [IATA:`LEL`]">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/karara-to-lake-evella-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=d34dcc8defb3c04eb689f6ffb648a1ad" width="613" height="572" data-path="images/air-transport/karara-to-lake-evella-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/karara-to-lake-evella-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=921b93f28aca5cec953a84fcb9b6e12a" width="613" height="572" data-path="images/air-transport/karara-to-lake-evella-dark.png" />
</Frame>

***

## Aircraft performance affects airport selection

Aircraft selection is not only an emissions intensity input.
It also affects the operational route that TerraTwin can model.

When `vehicle` identifies a specific aircraft, TerraTwin considers that aircraft's performance characteristics during automatic airport selection.
This includes the aircraft's runway compatibility and its range with revenue payload.

**Range with revenue payload** means the distance an aircraft can fly while carrying commercial payload, such as cargo or passengers.
It is not the same as a ferry range or maximum theoretical range with little or no payload.
For freight emissions modelling, this is the relevant range because the aircraft must be capable of carrying the shipment on the modeled flight segment.

When TerraTwin needs to choose an airport, it considers:

* **Aircraft compatibility** - whether the airport can support the selected aircraft.
* **Distance from the supplied location** - closer airports are generally preferred.
* **Customs-border crossings** - airports requiring an unnecessary border crossing are heavily penalized.
* **Airport size and runway length** - larger airports with longer runways are preferred when other factors are comparable.

<Note>
  Facility selection is contextual. The closest airport to a city is not always the selected airport if the selected aircraft cannot reasonably operate from it.
</Note>

For example, if the destination is the city of Florence, TerraTwin may select Florence Airport \[IATA:`FLR`] for an unknown aircraft or for a narrow-body medium-haul aircraft such as an Airbus A319, because the airport is close to the city and can support that kind of aircraft.

```json theme={null}
{
  "origin": {
    "type": "PLACE",
    "city": "Madrid",
    "countryCode": "ES"
  },
  "destination": {
    "type": "PLACE",
    "city": "Florence",
    "countryCode": "IT"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "A319",
      "aircraftType": "PASSENGER"
    }
  ]
}
```

<Frame caption="Florence Airport [IATA:`FLR`] selected for Airbus A319 narrow body aircraft">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/florence-airport-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=36ea54cd7e83c6acd9bf2ab94cf15f9b" width="993" height="406" data-path="images/air-transport/florence-airport-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/florence-airport-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=3e419c6f84a3eda919fed2a930b41321" width="993" height="406" data-path="images/air-transport/florence-airport-dark.png" />
</Frame>

If a larger aircraft is specified, such as a Boeing 777-300, TerraTwin may select a larger compatible airport in the region, such as  \[IATA:`PSA`], instead of the closest airport to Florence.

```json theme={null}
{
  "origin": {
    "type": "PLACE",
    "city": "Madrid",
    "countryCode": "ES"
  },
  "destination": {
    "type": "PLACE",
    "city": "Florence",
    "countryCode": "IT"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "B773",
      "aircraftType": "PASSENGER"
    }
  ]
}
```

<Frame caption="Piza International Airport selected for a Boeing 777-300 wide body aircraft">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/piza-airport-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=5a99cefc20237984caed5db3270a9dda" width="606" height="221" data-path="images/air-transport/piza-airport-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/piza-airport-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=7f8db26349089dea9dfe92e3e8ad1095" width="606" height="221" data-path="images/air-transport/piza-airport-dark.png" />
</Frame>

***

## Explicit airports act as an override

If an airport is explicitly supplied as a location, TerraTwin uses that airport.
This is true even when the chosen aircraft would not have caused TerraTwin to select that airport automatically.

In this request, Florence Airport is used because it was explicitly supplied as
the destination airport. Explicit airport inputs act as an override, so TerraTwin
does not replace the airport even if the selected aircraft, such as an Airbus
A321, would normally struggle to operate there.

```json theme={null}
{
  "origin": {
    "type": "AIRPORT",
    "iataCode": "MAD"
  },
  "destination": {
    "type": "AIRPORT",
    "iataCode": "FLR"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "A321",
      "aircraftType": "PASSENGER"
    }
  ]
}
```

<Warning>
  Use explicit airports deliberately. They are useful when the actual airport is known, but they can override TerraTwin's automatic aircraft-compatibility checks during airport selection.
</Warning>

***

## Sky rules and route restrictions

TerraTwin includes a sky rules database for route restrictions, long term airspace closures, and sanctions.
These rules affect whether a direct route can be used and can force a detour even when the aircraft has enough range for the great circle distance.

For example, restrictions introduced after the 2022 conflict in Ukraine can prevent direct flight routing between Western Europe and Russia.
When this applies, TerraTwin routes around the affected airspace and may use an eligible detour corridor or stopover region, such as through Serbia, rather than modelling an unavailable direct path.

Sky rules are applied together with aircraft performance and airport compatibility.
A route must be possible for the selected aircraft and compliant with the applicable route restrictions.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 100,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Hamburg",
    "countryCode": "DE"
  },
  "destination": {
    "type": "PLACE",
    "city": "Moscow",
    "countryCode": "RU"
  },
  "transportChain": [
    {
      "type": "AIR"
    }
  ]
}
```

<Frame caption="Hamburg to Moscow diverts through Belgrade Nikola Tesla Airport [IATA:`BEG`]">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/hamburg-to-moscow-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=2f139c7020f22f16a58662c3f42839c8" width="770" height="530" data-path="images/air-transport/hamburg-to-moscow-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/hamburg-to-moscow-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=47cfc9028e7471c548e1fcde9bfcfd2e" width="770" height="530" data-path="images/air-transport/hamburg-to-moscow-dark.png" />
</Frame>

***

## Automatic stopovers

TerraTwin inserts automatic stopovers when a requested air leg cannot be operated as one direct flight.

Stopovers can be triggered by either of these situations:

* The direct distance, including routing margin, exceeds the selected aircraft's range with revenue payload.
* Political, regulatory, sanctions, or airspace restrictions prevent direct travel between the departure and arrival airports.

When a stopover is required, TerraTwin selects a stopover airport that:

* is compatible with the selected aircraft or generic aircraft class;
* minimizes deviation from the shortest feasible route;
* allows the remaining route to be broken into feasible flight segments.

In a long distance request, an aircraft may not have enough range with revenue payload to fly the requested leg directly.
TerraTwin can insert one or more stopovers so each flight segment is feasible for the aircraft.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 10,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Rome",
    "countryCode": "IT"
  },
  "destination": {
    "type": "PLACE",
    "city": "Hong Kong",
    "countryCode": "CN"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "BOEING_767_300_FREIGHTER"
    }
  ]
}
```

<Frame caption="Rome to Hong Kong by 767-300F requires 2 stopovers">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/rome-to-hong-kong-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=7a4feed0b49bab7fa0a4f26629643791" width="822" height="342" data-path="images/air-transport/rome-to-hong-kong-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/rome-to-hong-kong-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=8ec7b42827a4d9911a9f9642d7236113" width="822" height="342" data-path="images/air-transport/rome-to-hong-kong-dark.png" />
</Frame>

By default, a transshipment hub is added at each automatic air stopover.
This represents the cargo transfer activity at the stopover and contributes hub emissions.
To disable automatic hub insertion, use `options.hubInsertion: "MANUAL"`.

```json theme={null}
{
  "options": {
    "hubInsertion": "MANUAL"
  }
}
```

To disable only air-to-air hub emissions, set `options.defaultHubTypes.airToAir` to `NONE`.
For the complete rules governing automatic insertion, manual insertion, and transition specific overrides, see the [logistics hubs guide](/content/guides/hubs#automatic-hub-insertion).

```json theme={null}
{
  "options": {
    "defaultHubTypes": {
      "airToAir": "NONE"
    }
  }
}
```

<Note>
  Automatic stopovers are part of the realization of one requested `AIR` operation. In the API credit model, an air transport operation is billed as a single credit even when TerraTwin inserts multiple automatic stopovers.
</Note>

***

## Automatic first and last mile

When an air leg starts or ends anywhere apart from an airport, TerraTwin automatically connects the place to a selected airport by road.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 500,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "address": "Catedral Metropolitana de San José",
    "countryCode": "CR"
  },
  "destination": {
    "type": "HARBOR",
    "unLoCode": "PABLB"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "BOEING_747_8F_FREIGHTER"
    }
  ]
}
```

This can be realized as:

<Steps>
  <Step title="First mile road">
    Cargo moves from Catedral Metropolitana de San José to Juan Santamaría International Airport \[IATA:`SJO`].

    <Frame caption="First mile road from San José to Juan Santamaría International Airport">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/catedral-metropolitana-to-juan-santamar%C3%ADa-international-airport-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=9ee46fa3edee877321977dfa92497f9f" width="1178" height="430" data-path="images/air-transport/catedral-metropolitana-to-juan-santamaría-international-airport-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/catedral-metropolitana-to-juan-santamar%C3%ADa-international-airport-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=e6792b6a12d9f43a7629583b951ac4fb" width="1178" height="430" data-path="images/air-transport/catedral-metropolitana-to-juan-santamaría-international-airport-dark.png" />
    </Frame>
  </Step>

  <Step title="Air transport">
    Cargo flies from Juan Santamaría International Airport \[IATA:`SJO`] to Tocumen International Airport \[IATA:`PTY`].

    <Frame caption="Air transport from Juan Santamaría International Airport to Tocumen International Airport">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/costa-rica-to-panama-city-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=462563548942153d37af07ee47ae70a2" width="1847" height="479" data-path="images/air-transport/costa-rica-to-panama-city-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/costa-rica-to-panama-city-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=f976292901f009a9a275d0a0a5b428e9" width="1847" height="479" data-path="images/air-transport/costa-rica-to-panama-city-dark.png" />
    </Frame>
  </Step>

  <Step title="Last mile road">
    Cargo moves from Tocumen International Airport \[IATA:`PTY`] to the destination port of Balboa \[`PABLB`].

    <Frame caption="Last mile road from Tocumen International Airport to Balboa">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/tocumen-international-airport-to-balboa-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=4c4d3b7309c60a04daa4fb755e529b00" width="1172" height="462" data-path="images/air-transport/tocumen-international-airport-to-balboa-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/tocumen-international-airport-to-balboa-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=671735c1d9d869ecc8bb99dcefee208f" width="1172" height="462" data-path="images/air-transport/tocumen-international-airport-to-balboa-dark.png" />
    </Frame>
  </Step>
</Steps>

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": "AIR",
      "firstMile": {
        "vehicle": "LCV_BELOW_3500_KG",
        "energyType": "DIESEL"
      },
      "lastMile": {
        "structure": "RIGID",
        "grossWeight": {
          "value": 18,
          "unit": "METRIC_TONNE"
        },
        "energyType": "DIESEL"
      }
    }
  ]
}
```

For more detail on these road vehicle fields, see the [road transport guide](/content/guides/road-transport).

<Note>
  If the origin is already an `AIRPORT`, no first-mile road connection is needed. If the destination is already an `AIRPORT`, no last-mile road connection is needed.
</Note>

***

## Dates and time zones

`departureDateTime` and `arrivalDateTime` are optional, but provide them when
they are known. They improve date-sensitive defaults, including the weighting
used when an aircraft code can refer to both passenger and freighter variants,
and make emissions certificates and analytics more useful by linking results to
the period in which the transport occurred.

```json theme={null}
{
  "type": "AIR",
  "vehicle": "A320",
  "departureDateTime": "2025-03-28T09:00",
  "arrivalDateTime": "2025-03-28T11:45",
  "aircraftType": "PASSENGER"
}
```

Local date-times are interpreted using the time zone of the relevant transport
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" }
```

***

## Routing failure and mode fallback

Air routing can fail when TerraTwin cannot build a feasible air operation for the requested leg.
This can happen when no suitable airport can be reached from the start or end location, or when the selected aircraft cannot reach the destination and no suitable stopover route can be found.

Use `options.fallbackTransportModes` to let TerraTwin switch to another transport mode when the requested air 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": "Cockburn Town, Grand Turk",
    "countryCode": "TC"
  },
  "destination": {
    "type": "PLACE",
    "city": "Miami",
    "countryCode": "US"
  },
  "transportChain": [
    {
      "type": "AIR",
      "vehicle": "A380"
    }
  ]
}
```

In this request, TerraTwin first attempts to calculate the leg as air transport.
The air route cannot be generated as the JAGS McCartney International Airport \[IATA:`GDT`] cannot accommodate an Airbus A380.

TerraTwin then tries the fallback modes in order: first `ROAD`, and then `WATER`.
`ROAD` cannot be used for this route, but `WATER` succeeds because the island has a usable sea port.
If `firstMile` or `lastMile` settings are configured on the leg, TerraTwin also applies them to fallback modes where they are relevant.
The first fallback mode that can be routed and calculated is returned.

<Frame caption="Grand Turk to Miami falls back to `WATER`">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/grand-turk-to-miami-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=d0f834e81ee4e1285e66e3cf174247cc" width="816" height="624" data-path="images/air-transport/grand-turk-to-miami-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/air-transport/grand-turk-to-miami-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=43ad2c5282c5038fc622590a50128b62" width="816" height="624" data-path="images/air-transport/grand-turk-to-miami-dark.png" />
</Frame>

If every fallback attempt fails, the API returns the error from the final fallback mode attempted.

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

## Recommendations

<Steps>
  <Step title="Set the air mode explicitly">
    Use `type: "AIR"` in the transport operation when the leg is known to be flown.
  </Step>

  <Step title="Provide the aircraft when known">
    Set `vehicle` using a TerraTwin system identifier, ICAO code, or IATA code. Prefer the TerraTwin system identifier when the exact aircraft variant is known.
  </Step>

  <Step title="Disambiguate passenger and freighter operations">
    Provide `aircraftType` whenever you know whether the cargo moved as belly freight or on a freighter.
  </Step>

  <Step title="Provide dates when available">
    Add `departureDateTime` or `arrivalDateTime` when known. Dates improve defaults and support period-based certificates, analytics, audits, and  reporting.
  </Step>

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