Flight itineraries and fares
Journeys and segments for one-way, return and multi-city trips, and the money and expiry fields on an offer.
To find flights you request offers. An offers request describes the passengers and where and when they want to travel, as a list of journeys: one for a one-way, two for a return, three or more for multi-city.
Each offer is one fare for the whole trip, at one price, from one supplier. It carries the itinerary it flies as journeys, in travel order. Each journey is one directional part of the trip and carries its segments, the individual flights, in order. A journey with two or more segments contains a connection.
Two conventions do most of the work:
stopsis counted per journey,segments.length - 1, never summed across the trip. It is the same unit as themax_stopsfilter:max_stops: 1means at most one stop each way, and the journeys read backstops: 0orstops: 1.direction(OUTBOUNDorINBOUND) is returned only for a one-way or return trip. Its omission identifies a multi-city itinerary.
The sections below show what each shape looks like in a response.
One-way direct trip
A one-way trip with no connection has one journey containing one segment. Here the traveller flies London Heathrow to Paris Charles de Gaulle on 10 November on AF1681, departing 07:15 and arriving 09:35 local time.
The response has one entry in journeys. That journey has direction: "OUTBOUND", stops: 0 and a single entry in segments.
One-way indirect trip
A one-way trip with a connection is still one journey; the connection is inside it. Here the traveller flies Heathrow to Rome Fiumicino via Amsterdam on 10 November: KL1000 to Amsterdam, then KL1597 on to Rome after a 1 h 40 m connection.
The journey has stops: 1 and two entries in segments. Its duration_minutes includes the time on the ground in Amsterdam. Do not read two segments as two journeys: the airports chain straight through, and only the nesting tells you where a journey ends.
Return direct trip
A return trip is one offer with two journeys, in travel order. Here the traveller flies Heathrow to Paris on 10 November on AF1681, and Paris back to Heathrow on 14 November on AF1680.
The first journey has direction: "OUTBOUND", the second direction: "INBOUND". Each has stops: 0 and one segment. total_amount on the offer covers both journeys for the whole party. A return is never two offers.
Return indirect trip
A connection on either half of a return stays inside its journey. Here the outbound is a direct AF1681 to Paris on 10 November, and the return on 14 November goes via Amsterdam: KL1234 to Amsterdam, then KL1027 to Heathrow after 1 h 25 m.
The second journey therefore has stops: 1 and two segments while the first has stops: 0 and one. max_stops: 1 allows this fare; max_stops: 0 does not.
Multi-city trip
A multi-city trip is one offer with three or more journeys, each to the next city. Here the traveller flies Heathrow to Paris on 10 November, Paris to Rome on 13 November, and Rome back to Heathrow on 17 November.
Every journey has stops: 0 and one segment. direction is omitted because there is no single outbound or return to name; that omission identifies a multi-city itinerary rather than missing data. To request this shape, send three entries in journeys.
Money and expiry
total_amount is the whole party's price for the whole trip, in major units of its currency. A booking also reports fare_amount and services_amount, the flights' and the extras' shares of that total.
expires_at is when the offer stops being accepted. Prebook before it; after it the reference answers 422 offer_expired and you request offers again.
fare_family and refundable appear when the airline publishes them. fare_conditions states whether the fare allows a refund and a change before departure, each with a flat penalty when the airline states an amount. An omitted condition or penalty means the airline published none, not that it is refused or free, so show it as unknown.
Terms can change between search and prebook, so read them again on the booking: it carries the prebook terms as fare_conditions, and its refund terms also as cancellation_policy.
Each segment names its marketing_carrier, the airline that sold the seat, and an operating_carrier only when a different airline flies it. Times are the airport's local time without an offset.