Air Shopping Guide

Use the Travelport JSON Search APIs to shop for flights: 

• Search
• Next Leg Search
• Flight Specific Search
• Air Availability

This guide details the terms and concepts for using these APIs and their workflow. For technical references, see the API references for each API, linked next.

Related Content: JSON APIs Guide, Search API Reference, Next Leg Search API Reference, Flight Specific Search Reference Payload API Reference, Flight Specific Search Full Payload API Reference

In this guide:

• Basic Concepts
  • Journey-based and Leg-based Searches
  • Branded Fares and Upsells
• Search Workflows
• Search API
  • Journey/Leg-Based Searches and Caching (SearchRepresentation, offersPerPage)
  • NDC and GDS Content (contentSourceList)
  • Upsell Fares (maxNumberOfUpsellsToReturn)
  • Search Modifiers
  • Split Ticketing
• Next Leg Search API
• Flight Specific Search API
• Search Responses (all Search APIs)
  • Combinability Code and Best Combinable Price
  • Consolidated Product, Flight, Brand, and Terms (ReferenceList)
  • Brand Attributes
  • Merged GDS and NDC Offers (Content Curation Layer)
• Search Request and Response Layout Diagrams
  • Search Request Diagram
  • Next Leg Search Request Diagram
  • Flight Specific Search Request Diagram
  • All Search Responses Diagram
• Air Availability API

Basic Concepts

In addition to the travel terms and corresponding JSON code details in the JSON APIs Guide , this section covers terms specific to the Search APIs.

The JSON APIs provide three APIs for searching for flights:

• Search API: Search for flights for either the entire itinerary or only the first leg. Supports one-way, round-trip, and open-jaw itineraries.

• Next Leg Search API: Return flights on the subsequent leg after a search for only the first leg.

• Flight Specific Search API: Return additional upsells for a flight/s, up to a maximum of 99 upsells. (Search and Next Leg Search return a maximum of 4 upsells for an offer.)

Journey-based and Leg-based Searches

You can use the Search API alone for all air shopping, or combine it with the Next Leg Search and/or Flight Specific Search APIs.

You can set Search to return flight results for either the entire itinerary or leg by leg:

• Journey-based searches: Returns offers for all legs on the itinerary. A journey-based request is a standalone search - no additional search requests are required.
• Leg-based searches: Returns offers for only the first leg of the itinerary. You must then send a Next Leg Search request that selects the offering for the first leg and returns offerings to combine with that leg. A multi-city itinerary requires a second Next Leg Search for the third leg.

For multi-city itineraries, GDS supports searching for up to six O&D pairs (legs of the itinerary) while three are supported for NDC.

Branded Fares and Upsells

A key Search feature is its return of detailed brand information and upsells. The Search APIs return branded fares by default when available. You can request the return of upsells with maxNumberOfUpsellsToReturn.

An upsell is a fare presented along with the base fare as a higher level of service, and is usually a branded fare. The Search and Next Leg Search APIs allow you to set whether to return upsell fares and if so how many:

• Itineraries with one or two O&D pairs (one-way and round-trip) can return up to four upsells.
• Itineraries with three O&D pairs can return up to two upsells.
• Itineraries with four to six &D pairs are limited to one upsell.

A branded fare is an airfare that is bundled with certain features included in the price. For example:

• The base fare (usually b0) may include simply the ticket, and customers must purchase ancillaries such as a paid seat and baggage separately.
• Brand 1 (e.g., b1) could include seat selection and a free carry-on in the fare.
• Brand 2 (e.g., b2) could include those features plus in-flight wifi and a free checked bag.

Brand details are consolidated in ReferenceList/ReferenceListBrand. The branded fare details returned are the brand name, tier, id (the internal reference number matching to a BrandRef in an offer), the airline brand identifier, and brand attributes.

Brand Attributes

The Search APIs return brand attributes that describe what is included in the brand. The BrandAttribute object is an array of the classification and inclusion key value pairs. Classification tells you what the feature is, and inclusion tells you whether that feature is available:

• classification:
  • CarryOn
  • Refund
  • Meals
  • Rebooking
  • CheckedBag
  • SeatAssignment
  • WiFi
  • PremiumSeat
  • LieFlatSeat
  • PersonalItem

• inclusion:
  • Included: Attribute included at no additional charge.
  • Chargeable: Attribute can be purchased at an additional cost.
  • NotOffered: Attribute is not available for a flight.

In addition to the standard brand attributes above, the following additional brand attributes are returned in Brand/AdditionalBrandAttribute for any brand that has them:

• ChauffeurTransfer
• ExtraLegroom
• InFlightEntertainment
• LoungeAccess
• PriorityBaggage
• PriorityBoarding
• PriorityCheckIn
• PrioritySecurity
• PriorityServices
• MileageAccrual
• Upgrades
• USB

The Search API provides modifiers that affect how brands are returned:

• ProductInclusionPreference: Limits the offerings returned to only fares that include the specified brand attributes. The response also returns information about other brand attributes, which may be included, chargeable, or not offered.
• BrandAttributeInclusion: Returns information about only the specified brand attributes and does not return any other brand attributes for those fares. The specified brand attributes returned may be included, chargeable, or not offered.
• AdditionalClassification: Filters out specified additional brand attributes from the response.

Merged GDS and NDC Offers (Content Curation Layer)

If the response includes offers for the same itinerary at the same price from GDS and NDC sources, Search combines those offers into a single merged offer to avoid duplication. CCL merges offers by comparing flights based on the following:

1. Carrier/airline

2. Flight number/s

3. Fare brand/s

4. Total price including taxes, fees, and surcharges where known

A merged offer returns a CatalogProductOffering/id value that combines the standard GDS and NDC id numbers. For example, if a GDS offer that has id 03 is merged with an NDC offer that has id UA_CPO0, the merged id is 03-UA_CPO0.

Customers must request both GDS and NDC content with CatalogProductOfferingsRequest/contentSourceList in the request to receive merged offers. Search continues to provide content unique to NDC or GDS as it currently does.

Future releases will expand on the above list to include more detailed assessment of attributes and additional business rules to determine what offers should be returned and under what conditions.

Search Workflows

The following diagrams illustrate possible workflow combinations for the Search, Next Leg Search, and Flight Specific Search APIs.

Search API

Search sends details about the number and type of passengers, the location and date for departure and arrival for each leg of the itinerary, and optional search and pricing modifiers.

The responses for Search, Next Leg Search, and Flight Specific Search share the same structure, diagrammed and described in Search Responses.

Journey/Leg-Based Searches and Caching (SearchRepresentation and offersPerPage)

The Search request sends the O&D pairs (departure and arrival locations) for all legs of the itinerary. You can set whether the response should include offers for all legs (journey-based search) or only the first leg (leg-based search). Use SearchRepresentation to specify either a journey- or leg-based search. If SearchRepresentation is not sent, the default is a journey-based response. You must specify all O&D pairs for all legs of the itinerary, even for a leg-based search.

This setting does not affect one-way itineraries.

NDC and GDS Content (contentSourceList)

Request NDC and GDS content with the optional contentSourceList indicator as follows:

• GDS to return only GDS content

• NDC to return only NDC content

• both GDS and NDC to return both

If contentSourceList is not sent, only GDS content is returned. For more about NDC, and basic differences between GDS and NDC in the JSON APIs, see the NDC Guide.

Upsell Fares (maxNumberOfUpsellsToReturn)

To return upsell fares, send maxNumberOfUpsellsToReturn with a value from 1-4 inclusive. Sending maxNumberOfUpsellsToReturn also returns upsells in any subsequent Next Leg Search request.

Although maxNumberOfUpsellsToReturn accepts values from 0-99, Search and Next Leg Search return a maximum of four upsells. You can use Flight Specific Search to return all upsells filed by the carrier, up to 99.

Search Modifiers

The Search API supports optional journey and pricing modifiers that allow you to set conditions on the itineraries to search for. You can send multiple modifiers in the same request. See the Search API Reference for details and supported values and formats.

Pricing modifiers refine the basic search based on fare and ticketing options and are sent in the PricingModifiersAir object:

• Fare type: Request specific fare types including private fares (negotiated), public fares (published), or net fares (consolidator fares, or any negotiated wholesale price that is further marked up for sale to customers).
• Fare restrictions: Include or exclude fares that require an advance purchase, min/max stay, or that are non-refundable.
• Account codes: Send your account code/corporate ID for each airline to return negotiated fares for those airlines.
• Currency override: Change the default currency of results, which is set in your PCC provided upon provisioning with Travelport.
• Sale and ticketing location: Return fares based on the sell and/or ticket location.

Journey modifiers refine the search based on elements of the air travel itself, such as carriers, cabin classes, and/or connection times. Journey modifiers are sent in the SearchModifiersAir object:

• Carrier preferences: Permit only, prohibit, or prefer (weight towards) one or more airlines.
• Cabin Preferences: Permit only, prohibit, or prefer (weight towards) a cabin class.
• Flight type: Preferences around connections and stops.
• Class of service: Preferences around class of service to return.
• Exclude ground transportation: Do not return ground transportation options.
• Max connection duration: Do not return options that exceed a specified length of time between flights on the same leg.
• Max overnight duration: Limit duration of any overnight connection.
• Prohibit change of airport: Do not return options that change airport.
• Return only fares with specified brand key value pairs Limit the fares returned to only fares that include the specified brand attributes in the price.
• Configure brand attributes returned: Return only information about the specified brand attributes and not return any other brand attributes for those fares.
• Exclude CAT16 penalties: Whether to return CAT16 change and cancel penalties.

Split Ticketing

Search's Split Ticketing feature returns one-way outbound and one-way inbound fares in addition to round-trip options. This may result in lower fares than the same or similar round-trip itinerary. Note that the Split Ticketing Search response may return only the one-way outbound and one-way inbound fares, or only the round-trip fares. This can happen when there is no flight availability or available fares for one-ways or round trips.

To request split ticketing, send PricingModifiersAir/includeSplitPaymentInd set to true . By default, Search divides the response into 34% round-trip offerings and the remainder as outbound and inbound one-way fares. To change this percentage, also send PricingModifiersAir/SplitPaymentOfferings with the requested percentage.

The Search response returns offers in the following order:

• Outbound one-way offers

• Inbound one-way offers

• Round trip offers

The response identifies the one-way outbound and inbound offers with CombinabilityCode j0. The round-trip offers are identified with CombinabilityCode values starting with j1 and incremented by one.

The following are in scope for split ticketing:

• Search requests

• GDS content

• Round trip journey-based offerings (isJourney header is not sent or sent with value true, or CustomResponseModifiersAir/SearchRepresentation is not sent or is sent with value Journey)

• Upsells

The following are not supported for split ticketing:

• Next Leg Search and Flight Specific Search

• One way, circle trip, open jaw, and multiple origin/destination search

• Round trip leg-based offerings

• Virtual interlining

• NDC content

For any search requests for the above scenarios that also send includeSplitPaymentInd set to true, Search ignores the split ticketing indicator, returns a normal Search response, and returns in the Result object the warning message Split Ticketing is not supported and has been ignored.

Next Leg Search API

If you request a leg-based search, the Search response returns offers for only the outbound leg of the itinerary. You must then use Next Leg Search to return offers for the next leg of the trip.

Next Leg Search Request

The Next Leg Search request sends a payload with several identifiers from the preceding Search response: an identifier for the search response as a whole, plus identifiers for the offer and product you want to select from that search result for the first leg of the trip. Next Leg Search uses the itinerary details and any modifiers sent in the initial Search request to return offers for the next leg of the itinerary.

Multi-city Itineraries

For a multi-city itinerary, send a Search request for the first leg, a Next Leg Search for the second leg, and another Next Leg Search request for the third leg. In this case, for the second Next Leg Search request, send identifiers from the preceding Next Leg Search request instead of the Search request.

GDS supports searching for up to six O&D pairs (legs of the itinerary) while three are supported for NDC.

For example, a search for an itinerary from DEN > LAX, LAX > ATL, and ATL > DEN would use this workflow:

1. Leg-based Search request with one instance of SearchCriteriaFlight each for DEN > LAX, LAX > ATL, and ATL > DEN.
2. Next Leg Search request for LAX > ATL, sending the response, offer, and product identifiers from the Search response from step 1.
3. Next Leg Search request for ATL > DEN, sending response, offer, and product identifiers from the Next Leg Search response from step 2.

Next Leg Search Response

The Next Leg Search response returns offers that can be combined with the offer and product selected for the preceding leg of the itinerary.

The responses for Search, Next Leg Search, and Flight Specific Search share the same structure per Search Responses below.

Each instance of CatalogProductOffering with ids o2 and higher may return multiple brands, if upsells were requested in the Search request. Usually the first instance is the lowest fare and additional instances are the available upsell fares.

The Next Leg Search response includes combinability codes, which match with the combinability code for the selected product on the first leg to indicate the lowest possible fare when the two products are combined.

After all instances of CatalogProductOffering, a ReferenceList object consolidates details across all itineraries using the same structure as in the Search response.

Flight Specific Search API

The Flight Specific Search API retrieves additional filed fares for any selected offer and product in a preceding Search or Next Leg Search response. (Search and Next Leg Search return a maximum of 4 upsells for an offer.)

Flight Specific Search Request

The Flight Specific Search request can be sent as either:

• a reference payload request that sends an identifier for a preceding response, plus identifiers for the offer and the product/s to return additional upsells for.
• a full payload request, which sends all itinerary details without a reference to a preceding search response.

In the request, set maximumNumberOfUpsellsToReturn up to the maximum allowable value of 99 (effectively, all upsells filed) to return additional filed fares for that product.

Flight Specific Search Response

The responses for Search, Next Leg Search, and Flight Specific Search share the same structure per Search Responses below.

Search Responses (all Search APIs)

The Search, Next Leg Search, and Flight Specific Search responses use the same structure and return the following primary objects:

• CatalogProductOfferings: Information about the offers available for each leg. Each offer includes a price, and reference numbers for the product, brand, and terms and conditions in that offer available at that price.
• ReferenceList: Details about the flights, products, brands, and terms and conditions that make up each offer.
• Result: Any error or warning messages (not represented in the diagram below).

Key points for all search API responses:

• Responses consolidate common details into the ReferenceList object to reduce response time:
  • Multiple offers are likely to include the same flights, products, terms and conditions, and brands in various combinations. Instead of repeating all details in every offer, the offer instead returns a price at which a specific product is available for a specific brand at a set of terms and conditions. A product is a flight or connecting flights and an associated service level.
  • Each offer returns cross references to the product, brand, and terms and conditions that make up that offer. Products return cross-reference to the flights included that product. These references match to the flights, products, terms and conditions, and brands in ReferenceList.
  • For more about offers and the Search response structure, see Offers in the JSON APIs in the JSON APIs Guide.
• Responses always return details about branded fares, if filed by the airline.
• Responses include combinability details for the product combinations create the lowest fare possible for that combination.
• Responses return upsells if requested with maxNumberOfUpsellsToReturn.
• NDC content is returned only if requested with contentSourceList.

Combinability Code and Best Combinable Price

The Search response matches inbound and outbound products and provides a combinability code that lets you know which products match for the lowest price available, and what that lowest available price is.

For example, if p6 on the outbound leg and p24 on the inbound leg both have a CombinabilityCode value of j2, both products will return the same details in BestCombinablePrice, which lists the base fare, taxes, and total price for the combined itinerary. If more than two products share a CombinabilityCode value, then any outbound/inbound combination of those products share the same price.

Consolidated Details for Products, Flights, Brands, and Terms (ReferenceList)

The ReferenceList object consolidates common information across the offers in CatalogProductOffering. ReferenceList is an array that returns one instance each of four types:

• ReferenceListFlight includes the Flight array. Each instance returns one flight with a unique internal ID (FlightRef, numbered as in s1 or QFs1) and the flight number, carrier, equipment, etc.

• ReferenceListProduct includes the Product array. Each instance returns one product:

  • A product is the flight/s that make up one leg of an itinerary.
  • Product does not include flight details but does list a FlightRef IDs for each flight in that product.
  • Each Product has a unique internal ID (ProductRef, e.g., p12 or QFp12).
  • For each PTC type requested, Product returns the class of service, cabin, fare basis code, and fare type information as well as the brand identifier if it is a branded fare.

• ReferenceListTermsAndConditions includes the TermsAndConditions array. Each instance returns one set of terms and conditions (T&C):

  • T&C include fare rules, baggage allowance, last date/time to book and ticket, etc.
  • Each has a unique internal ID (TermsAndConditionsRef, e.g., t8 or SQt8.
  • Each set of terms and conditions applies to one or more products.
  • Includes a list of ProductRef ids to which that set of T&C applies.

• ReferenceListBrand includes the Brand array. Each instance returns details for one brand:

  • Details include brand name, tier (tier not supported for NDC), and brand attributes (such as carry-on baggage, checked baggage, wifi) and whether each attribute is included in the fare.
  • Unique internal brand identifier (e.g., b44 or AAb44).

Search Request and Response Layout Diagrams

The following overview diagrams illustrates the basic structure of the requests and responses for the search APIs. These diagrams don't include every object that might be returned, and diagrams may not reflect minor updates.

Search Request Diagram

The following diagram shows the high-level objects in the Search request.

Next Leg Search Request Diagram

The following diagram shows the high-level objects in the Next Leg Search request.

Flight Specific Search Request Diagram

The following diagram shows the high-level objects in the Flight Specific Search request.

Search Response Diagram

The following overview diagrams illustrates the basic structure used in all search responses. Differences are noted above in the individual sections for each API.

Air Availability API

The JSON Air Availability API returns scheduled flights between a specified city pair on a specified day and time and indicates whether seats are available on those flights. This offers corporate accounts a single source of air availability data for GDS content and reduces sell failures at book. The response does not include pricing information.

An Air Availability request can be followed by either:

• An AirPrice full payload request to return pricing for a selected itinerary from the Air Availability response, followed by a booking session.

• A workbench session to book a selected itinerary from the Air Availability response. If pricing is desired as part of the workbench session, send a Standalone Price request. Note the booking session must use the Add Offer full payload request, as Air Availability results are not cached.

The Air Availability request at a minimum requires SearchCriteriaFlight. SearchCriteriaFlight specifies air availability details such as departure date and time or arrival date and time, and location of departure and arrival. Best practice when sending an arrival date is to also send the arrival time. Sending both departure date and arrival date is not supported; if an arrival date is sent, the departure date is ignored.

Air Availability supports the following optional search modifiers; no other search modifiers and no pricing modifiers are supported:

• Carrier preferences: Permit only one or more airlines. Preferred and prohibited carrier preferences are not supported.

• Connection preferences: Permit only or prohibit one or more cities or airports. Sending both permitted and prohibited connection preferences for one Origin and Destination is not supported. Preferred connection preference is not supported.

The Air Availability response includes the following information.

• CatalogProductOfferings: An array of the products available on each leg.

• ReferenceListFlight: An array of instances for each flight, which lists the arrival and departure times, flight number, duration, etc. When applicable, the OperationalStatus of the flight (Flight Cancelled, FlightDeparted, FlightPastScheduledDeparture, FlightBoarding, NotAvailableUseSearch) is also listed.

• ReferenceListProduct: An array of instances for each product. Each product includes ClassOfServiceAvailability, which defines the class of service, the number of seats available for the class of service, and the status of the class of service (E.g., Available). If there are no seats available for a class of service, the status can be Not Available, Request, Waitlist, Waitlist Closed.

Additional information:

• Not supported for NDC content.

• Not supported for low cost carriers such as 6E (IndiGo) and FR (Ryan Air).

• When air availability for a direct flight making one or more stops between the origin and destination is returned, the Air Availability response returns the “stops” attribute in FlightDetail with the number of stops. Air Availability does not return IntermediateStop as does Search.

• Caching is not supported. All subsequent requests sending itinerary details must be full payload requests.

• The response returns OperationalStatus with the value NotAvailableUseSearch when no classes of service are returned for a flight, or when the flight status is unknown.

• Sending departureTime or arrivalTime with "00:00:00" is not supported. An error is returned.