Flight: Routing (multi-leg)

Send a multi-leg itinerary as one flight item with a hyphen-separated airport chain, and get carbon and distance calculated per leg and totalled on the item.

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

Parsing rulesCopy Anchor Link

SQUAKE parses the routing string as follows:

• It splits on -, then trims each segment and converts it to uppercase.
• There must be at least two non-empty segments.
• Consecutive segments must not be identical (for example, BER-BER is invalid).

An 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 parametersCopy Anchor Link

Some attributes can vary per leg. The validated attributes are:

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

How values are appliedCopy Anchor Link

• Single value: repeated for every leg.
• Pipe-separated (|): must have exactly as many parts as legs. The leg count is the number of consecutive airport pairs in the routing (BER-FRA-JFK has two legs).
• Hyphen-separated: if the number of hyphen-separated segments equals the leg count, values map leg by leg. If the count doesn't match and the string isn't a single segment, validation fails with an ambiguous multi-segment string.

A count mismatch returns invalid_params with a 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 with routingCopy Anchor Link

When routing is present, distance_in_km isn't used in place of the computed distance. Routing drives the per-leg distance, and the parent item's distance aggregates those legs. Sending distance_in_km doesn't define the total for routed items.

Response and expandCopy Anchor Link

• Include "legs" in the request's expand array (together with "items" when you need per-item totals) to get 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. The parent carbon_quantity and distance aggregate the legs (for example, the parent distance matches the sum of the leg distances).
• If expand includes only items and leaves out legs, the item 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 requestsCopy Anchor Link

A multi-leg DEFRA flight with items and legs expanded:

{
  "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, with a different booking class on each of the two legs:

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