Air transport - TerraTwin API Documentation

Air transport operations model cargo moved by aircraft between airports. Set the transport operation type to AIR within a transport chain 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.

Mode

Use type: "AIR" in a transportChain transport element.TerraTwin treats that element as a requested air leg between the surrounding transport chain locations.

Aircraft

Use vehicle when you know the aircraft.Aircraft can be supplied by IATA equipment code, ICAO aircraft type designator, or TerraTwin system identifier.

Airports

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.

Connectors

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.

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.

Basic shape

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

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

First mile
Flight
Last mile

The Crucible, Sheffield to Manchester Airport [IATA:`MAN`]

Manchester Airport [IATA:`MAN`] to Berlin Brandenburg Airport [IATA:`BER`] flight

Berlin Brandenburg Airport [IATA:`BER`] to Museum Barberini, Potsdam

When the aircraft is known, provide it with vehicle:

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

Portland International Airport [IATA:`PDX`] to Madrid–Barajas Airport [IATA:`MAD`] with a stopover in Newfoundland

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:

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

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

Broken Hill to New Plymouth through Sydney [IATA:`SYD`] and Auckland [IATA:`AKL`] airports

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.

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	`BOEING_737_800BCF_FREIGHTER`	Most specific. The identifier names the exact supported aircraft model and whether it is a belly freight or freighter variant.
IATA equipment code	`7F8`	Commercial equipment code. Can distinguish some passenger, combi, and freighter variants.
ICAO aircraft type designator	`B738`	Operational aircraft type code. May not distinguish passenger and freighter variants.

{
  "type": "AIR",
  "vehicle": "BOEING_737_800BCF_FREIGHTER"
}

{
  "type": "AIR",
  "vehicle": "7F8"
}

{
  "type": "AIR",
  "vehicle": "B738"
}

A complete list of supported aircraft is available in the API reference. 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.

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.

Passenger belly freight and freighters

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

Passenger

Use aircraftType: "PASSENGER" when the cargo is carried in the belly hold of a passenger aircraft.This is often called belly freight.

Freighter

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.

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:

{
  "type": "AIR",
  "vehicle": "A320",
  "aircraftType": "PASSENGER"
}

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

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.

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.

{
  "type": "AIR",
  "aircraftType": "PASSENGER"
}

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

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.

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.

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

Karara [IATA:`KQR`] to Lake Evella [IATA:`LEL`]

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.

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.

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.

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

Florence Airport [IATA:`FLR`] selected for Airbus A319 narrow body aircraft

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.

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

Piza International Airport selected for a Boeing 777-300 wide body aircraft

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.

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

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.

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.

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

Hamburg to Moscow diverts through Belgrade Nikola Tesla Airport [IATA:`BEG`]

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.

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

Rome to Hong Kong by 767-300F requires 2 stopovers

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

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

{
  "options": {
    "defaultHubTypes": {
      "airToAir": "NONE"
    }
  }
}

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.

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.

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

First mile road

Cargo moves from Catedral Metropolitana de San José to Juan Santamaría International Airport [IATA:SJO].

Air transport

Cargo flies from Juan Santamaría International Airport [IATA:SJO] to Tocumen International Airport [IATA:PTY].

Last mile road

Cargo moves from Tocumen International Airport [IATA:PTY] to the destination port of Balboa [PABLB].

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.

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

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.

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.

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

{ "departureDateTime": "2026-04-12T08:30:00Z" }

Local time

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

{ "departureDateTime": "2026-04-12T08:30:00+02:00" }

Date only

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

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

Grand Turk to Miami falls back to `WATER`

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

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.

Recommendations

Set the air mode explicitly

Use type: "AIR" in the transport operation when the leg is known to be flown.

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.

Disambiguate passenger and freighter operations

Provide aircraftType whenever you know whether the cargo moved as belly freight or on a freighter.

Provide dates when available

Add departureDateTime or arrivalDateTime when known. Dates improve defaults and support period-based certificates, analytics, audits, and reporting.

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.

Mode

Aircraft

Airports

Connectors

​Basic shape

​Properties

​Selecting air as the mode

​Aircraft selection

​Passenger belly freight and freighters

Passenger

Freighter

​Unknown aircraft

​Aircraft performance affects airport selection

​Explicit airports act as an override

​Sky rules and route restrictions

​Automatic stopovers

​Automatic first and last mile

​Dates and time zones

​Routing failure and mode fallback

​Recommendations

Basic shape

Properties

Selecting air as the mode

Aircraft selection

Passenger belly freight and freighters

Unknown aircraft

Aircraft performance affects airport selection

Explicit airports act as an override

Sky rules and route restrictions

Automatic stopovers

Automatic first and last mile

Dates and time zones

Routing failure and mode fallback

Recommendations