Flight: Routing (multi-leg)

Flight routing lets API clients send a single flight item with an ICAO-style hyphen-separated airport chain (for example BER-FRA-JFK) instead of origin and destination. The backend expands that string into consecutive legs (BER→FRA, FRA→JFK), runs the same methodology once per leg, and aggregates carbon and distance on the parent item.

---

Mutual exclusion with origin / destination

routing cannot be combined with origin or destination. Supplying both yields invalid_params with a detail such as:

'routing' cannot be used together with 'origin' or 'destination'.

---

Parsing rules

The routing string is parsed as follows:

• Split on -, segments are converted to uppercase and trimmed.

• There must be at least two non-empty segments.

• Consecutive segments must not be identical (for example BER-BER is invalid).

Invalid or empty routing fails validation with a clear error, for example:

'routing' must be a hyphen-separated list of at least two distinct airport codes (e.g. BER-FRA-JFK).

---

Per-leg parameters (pipe lists and defaults)

Certain attributes can vary per leg. Validated attributes include:

booking_class, fare_class, airline, aircraft_type, aircraft_size, plane_type, biofuel, flight_number, departure_date.

How values are applied

• Single value — repeated for every leg.

• Pipe-separated (|) — must have exactly as many parts as legs. Leg count is the number of consecutive airport pairs in the routing (for BER-FRA-JFK there are two legs).

• Hyphen split — if the number of hyphen-separated segments equals the leg count, values map leg-by-leg. If that count does not match and the string is not a single segment, validation fails with an ambiguous multi-segment string.

• departure_date is pipe-only — it is never hyphen-split, because ISO dates contain hyphens. Use a single value (broadcast to all legs) or a pipe list with one entry per leg.

A count mismatch returns invalid_params with detail like:

'booking_class' list has 2 value(s) but routing has 1 leg(s).

Validation failures and leg-count mismatches also emit internal metrics for monitoring.

---

distance_in_km when routing is present

distance_in_km is not used as a substitute for computed distance when routing is present: routing drives per-leg distance, and the parent item’s distance aggregates those legs. Submitting distance_in_km does not define the total for routed items.

---

Response and expand

• Include "legs" in the request expand array (together with "items" when you need per-item totals) to receive a per-leg breakdown on the flight item.

• When legs is expanded, the item typically includes routing (echoing the submitted chain) and a legs array. Parent carbon_quantity and distance aggregate the legs (for example, parent distance matches the sum of leg distances).

• If expand includes only items (and omits legs), the item payload may omit routing and legs even when the request used routing.

With audit mode enabled, per-leg objects can include audit and emission_factors when legs is expanded.

---

Example request

Multi-leg DEFRA flight with expanded items and legs:

{
  "expand": ["items", "legs"],
  "carbon_unit": "tonne",
  "distance_unit": "kilometer",
  "items": [
    {
      "type": "flight",
      "methodology": "DEFRA",
      "routing": "BER-FRA-JFK",
      "booking_class": "economy",
      "number_of_travelers": 1,
      "radiative_forcing_index": true,
      "external_reference": "multi_leg_1"
    }
  ]
}

Per-leg attributes example (two legs, different booking classes):

{
  "routing": "BER-FRA-JFK",
  "booking_class": "economy|business"
}