Air Shopping Guide

Use the following 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.

See the JSON APIs Guide for the basic travel terms you need to know to develop your applications, how the JSON APIs represent those terms in code, and a workflow summary.

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

In this guide:

Basic Concepts

Be sure to see the detailed discussion of Offers in the JSON APIs to understand the structure of the Search APIs.

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:

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 your initial search request to return flight results for either the entire itinerary. or leg by leg:

See Journey/Leg-Based Searches and Caching (SearchRepresentation and offersPerPage) below for details and the settings to use.

For multi-city itineraries, you can search for up to six O&DClosed Origin and destination (O&D) pair, or one leg of an itinerary. In the JSON APIs, product is the term for the flight/s on one leg. pairs (legs of the itinerary) for GDSClosed Global Distribution System. A GDS aggregates and distributes air, hotel, and car rental content such as schedules, fares, and upsells. In the JSON APIs, GDS content is distributed from Travelport., and up to three for NDCClosed New Distribution Capability, an XML standard for exchanging data that supports airlines in distributing their content directly to online travel agencies. See the NDC Guide..

If your workflow subsequently references a journey-based search result, the Search request must send offersPerPage set to any positive number. This setting invokes caching to allow subsequent requests to refer to these search results. (A journey-based search returns all legs of the itinerary, while a leg-based search returns one leg at a time and is cached by default.) If a journey-based Search request does not send offersPerPage, any reference payloadClosed In the JSON APIs, an API call that sends identifers referring to a previous response for the itinerary to be shopped, priced, added, etc. instead of full itinerary details. requests for Flight Specific Search, AirPrice, and Add Offer will fail.
In addition, if sent with a non-zero number, offersPerPage determines the number of offers returned in the response. If not sent, or sent with 0, Search returns all offers. Note that if offersPerPage is sent with 1, Search returns one offer for only one leg. This defect will be addressed in an upcoming release to ensure that the single offer returned includes all legs in the Search criteria.

Branded Fares and Upsells

A key search feature is support for detailed brandClosed An upgrade from the base fare that includes certain features in the price, such as wifi or seat selection. Features included in a brand are specified in the brand attributes (BrandAttributes object). information and upsells.

A branded fareClosed Airfare with certain features included in the price; for example, a seat assignment and wifi at no extra charge. 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. ReferenceListBrand also returns brand attributes that describe what is included in the brand. See Brand Attributes below for a full list.

All Search APIs return branded fares by default when available.

An upsell is a fare presented along with the base fare as a higher level of service, and is usually a branded fare. To return upsells in the Search and Next Leg Search APIs, you must request them by sending maxNumberOfUpsellsToReturn and specify 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 O&D pairs are limited to one upsell.

To see more upsell options, you can send a Flight Specific Search request for any flight returned by the Search or Next Leg Search API. Flight Specific Search can return up to 99 upsells, or the maximum available for the flight if less than 99.

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)

Among other criteria, the Search request must send the O&D pair (departure and arrival location) for each leg 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). To specify, send SearchRepresentation (see the Search API Reference) with either Journey or Leg. If SearchRepresentation is not sent, the response defaults to journey-based and returns offers for all legs.

Every Search request 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.

With any search request, especially a journey-based search, you may also need to send offersPerPage (see the Search API Reference) with any positive number. offersPerPage has two functions:.

  • Caching: Sets whether to invoke caching so that journey-based search results can be referenced by subsequent reference payload requests. To invoke caching, send with any number equal to or greater than 1. No maximum value.

  • Maximum offers returned: Also sets the maximum number of offers returned. If sent with 0 or not sent, Search returns all offers. If the response is not returning an adequate selection of offers, try increasing the value in offersPerPage.

If your workflow subsequently references a journey-based search result, the Search request must send offersPerPage set to any positive number. This setting invokes caching to allow subsequent requests to refer to these search results. (A journey-based search returns all legs of the itinerary, while a leg-based search returns one leg at a time and is cached by default.) If a journey-based Search request does not send offersPerPage, any reference payload requests for Flight Specific Search, AirPrice, and Add Offer will fail.
In addition, if sent with a non-zero number, offersPerPage determines the number of offers returned in the response. If not sent, or sent with 0, Search returns all offers. Note that if offersPerPage is sent with 1, Search returns one offer for only one leg. This defect will be addressed in an upcoming release to ensure that the single offer returned includes all legs in the Search criteria.

NDC and GDS Content (contentSourceList)

Request the return of both 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. You must be provisioned for NDC with both the NDC carrierClosed An airline./s and Travelport to receive NDC content. 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.

Note the following differences between NDC and GDS for maxNumberOfUpsellsToReturn:

  • For GDS, if maxNumberOfUpsellsToReturn is either not provided or is sent as 0, the lowest priced offer is returned (i.e., the base fare).
  • For NDC:
    • If maxNumberOfUpsellsToReturn is not sent, the response returns the lowest priced offer of each available brand or cabin.
    • If maxNumberOfUpsellsToReturn is sent as 0, the response returns the lowest priced offer (i.e., the base fare).

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:

Journey modifiers refine the search based on elements of the air travel itself, such as carriers, cabin classes, and/or connectionClosed A change to a different airplane on the way to the destination. 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 cancelClosed Cancel a ticket outside the void period without rebooking on another itinerary. Depending on the airline ticket policy, canceling a ticket may result in a full, partial, or no refund. penalties.

Split Ticketing

GDS only; not supported for NDC.
Split ticketing is available only for customers specifically provisioned for split ticketing. Split ticketing returns one-way outbound and one-way inbound fares in addition to round-trip offers. Split ticket offers are identified with a CombinabilityCode of j0. If your account is not configured for split ticketing, sending includeSplitPaymentInd in the Search response returns a response without split ticket offers and the warning message User is not authorized for Split Ticketing Shop. Please contact support. GDS only, not supported for NDC.

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, 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 the Next Leg Search API to return offers for the next leg of the trip.

Note that any applicable modifiers or indicators sent in the Search request carry over to the Next Leg Search request and are not re-sent.

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 for DEN > LAX.
  2. Next Leg Search request for LAX > ATL that sends identifiers for the response, selected offer, and selected product from the Search response from step 1.
  3. Next Leg Search request for ATL > DEN that sends identifiers for the response, selected offer, and selected product 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 and sent in the Next Leg Search request.

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

In the Next Leg Search response, the first instance of CatalogProductOffering is the offer and product sent in the Next Leg Search request. This is the selected offer and product for the first leg. This first instance of CatalogProductOffering does not return upsells, as the leg and fare have already been selected.

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 should be ignored. The selected offer and product for the first leg is combinable with each instance of CatalogProductOffering with ids o2 and higher.

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

GDS only, not supported for NDC.

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.

CombinabilityCode and BestCombinablePrice

To assist in combining products for round-trip and multi-city itineraries (a product is one leg of the itinerary), the Search response returns for each product a CombinabilityCode that identifies which products combine for the lowest price available. This lowest price is returned in BestCombinablePrice.

For example, on a round-trip search, if product p6 on the outbound leg and product p24 on the inbound leg both have a CombinabilityCode value of j2, you can select these two products for the price returned in BestCombinablePrice, which lists the base fare, taxes, and total price for the combined itinerary. If more than two products have the same CombinabilityCode value, then any outbound/inbound combination of those products are available at the same price.

Per Multi-city Offers with Stopovers below, CombinabilityCode formats starting with the letter j (jc1, jc2, and so on) identify multi-city offers with a stopover. All other offers use the format j1, j2, and so on.

One-way responses return CombinabilityCode for consistency but this data has no use and should be ignored. The price in BestCombinablePrice applies to the one-way itinerary.

In this example excerpt, product p5 can be combined with any other product that has a CombinabilityCode of j2 for the lowest available price of 1344 HKD. 


                  "Brand": {
                    "@type": "Brand",
                    "BrandRef": "b0"
                  },
                  "Product": [
                    {
                      "@type": "Product",
                      "productRef": "p5"
                    }
                  ],
                  "TermsAndConditions": {
                    "@type": "TermsAndConditionsAir",
                    "termsAndConditionsRef": "T3"
                  },
                  "CombinabilityCode": [
                    "j2"
                  ],
                  "BestCombinablePrice": {
                    "@type": "BestCombinablePriceDetail",
                    "CurrencyCode": {
                      "decimalPlace": 0,
                      "value": "HKD"
                    },
                    "Base": 1040,
                    "TotalTaxes": 304,
                    "TotalPrice": 1344,
                    "PriceBreakdown": [
                      {
                        "@type": "PriceBreakdownAir",
                        "quantity": 1,
                        "requestedPassengerType": "ADT",
                        "Amount": {
                          "CurrencyCode": {
                            "decimalPlace": 0,
                            "value": "HKD"
                          },
                          "Base": 1040,
                          "Taxes": {
                            "@type": "TaxesDetail",
                            "TotalTaxes": 304,
                            "Tax": [
                              {
                                "taxCode": "AY",
                                "value": 88
                              },
                              {
                                "taxCode": "US",
                                "value": 78
                              },
                              {
                                "taxCode": "XF",
                                "value": 70
                              },
                              {
                                "taxCode": "ZP",
                                "value": 68
                              }
                            ]
                          },
                          "Total": 1344
                        }
                      }
                    ]
                  }
                }
              ]
 ...

Multi-city Offers with Stopovers (price details in BestCombinablePrice only)

For GDS content in all search responses, ProductBrandOffering no longer returns the Price object. All customers must update their code to validate pricing in BestCombinablePrice, not Price, for all GDS content.
You can opt out of this change by contacting your Travelport representative. If so, multi-city offers with stopovers will not be returned for your PCC, and all offers will continue to return both Price and BestCombinablePrice.

With Air Offer 25.11.51.3 and later, when available, all search responses support returning multi-city offers with stopovers when available. This enables the return of lower fares and additional itinerary options. Such multi-city offers are identified by CombinabilityCode values using the new format jc instead of j, as in jc1, jc2, and so on.

For example, if a traveler wants to fly from BRU > NYC > SFO > BRU, the request has three legs: BRU > NYC, followed by NYC > SFO, and ending with SFO > BRU. An example multi-city with a stopover would be a round trip fare BRU > SFO > BRU with a stopover in NYC.

As part of this change, all GDS offers in all search responses no longer return price details in both ProductBrandOffering/Price and ProductBrandOffering/BestCombinablePrice. Instead, ProductBrandOffering returns pricing only in BestCombinablePrice, and no longer returns the Price object. This applies to all GDS content in all Search, Next Leg Search, and Flight Specific Search responses. Although multi-city offers are not returned for split ticketing, ProductBrandOffering/Price has also been removed from split ticketing offers.

Multi-city offers with stopovers are not supported for NDC, and there are no code changes for NDC offers at this time. A future deployment will remove ProductBrandOffering/Price from NDC offers.

To summarize, for all GDS offers in all search responses:

  • The Price object is no longer returned (ProductBrandOffering/Price).

  • The BestCombinablePrice object continues to return pricing in the PriceBreakdown object (ProductBrandOffering/BestCombinablePrice/PriceBreakdown). The structure of BestCombinablePrice is unchanged.

  • BestCombinablePrice returns the Surcharges and Commission objects when applicable. For multi-city offers with stopovers, the surcharges and commission amounts are for the entire journey. For all other offers, the surcharges and commission amounts are for each leg (origin and destination pair) of the journey.

  • A multi-city offer can be identified by the jc in its CombinabilityCode: jc1, jc2, and so on. The CombinabilityCode for other offers starts with only j, as in j1, j2, and so on.

  • If both NDC and GDS content is requested, in the response, NDC offers include ProductBrandOffering/Price while GDS offers do not.

All search responses return GDS offers in the following format with Air Offer 25.11.51.3 and later. 

{
 "@type": "ProductBrandOffering",
 "Brand": {
  "@type": "BrandID",
  "BrandRef": "b0"
 },
 "Product": [
  {
   "@type": "ProductID",
   "productRef": "p0"
  }
 ],
 "TermsAndConditions": {
  "@type": "TermsAndConditionsID",
  "termsAndConditionsRef": "T0"
 },
 "CombinabilityCode": [
  "jc1"
 ],
 "BestCombinablePrice": {
  "@type": "BestCombinablePriceDetail",
  "CurrencyCode": {
   "decimalPlace": 0,
   "value": "HKD"
  },
  "Base": 12920,
  "TotalTaxes": 720,
  "TotalFees": 0,
  "TotalPrice": 13640,
  "PriceBreakdown": [
   {
    "@type": "PriceBreakdownAir",
    "quantity": 1,
    "requestedPassengerType": "ADT",
    "Amount": {
     "@type": "Amount",
     "CurrencyCode": {
      "decimalPlace": 0,
      "value": "HKD"
     },
     "Base": 12920,
     "Taxes": {
      "@type": "TaxesDetail",
      "TotalTaxes": 720,
      "Tax": [
       {
        "taxCode": "JD",
        "value": 178
       },
       {
        "taxCode": "OG",
        "value": 6
       },
       {
        "taxCode": "QV",
        "value": 31
       },
       {
        "taxCode": "DY",
        "value": 117
       },
       {
        "taxCode": "HW",
        "value": 388
       }
      ]
     },
     "Fees": {
      "@type": "FeesDetail",
      "TotalFees": 0
     },
     "Total": 13640
    },
    "FareCalculation": "MAD LA LIM LA AQP M808.51LLEKM00R /-CUZ LA X/LIM LA MAD M808.51LLEKM00R NUC1617.02END ROE0.915261"
   }
  ]
 }
}

All search responses continue to return the highlighted Price object below for NDC offers only. This object has been removed from GDS offers.

{
 "@type": "ProductBrandOffering",
 "Price": {
  "@type": "PriceDetail",
  "CurrencyCode": {
   "decimalPlace": 2,
   "value": "AUD"
  },
  "Base": 270,
  "TotalTaxes": 43.2,
  "TotalFees": 0,
  "TotalPrice": 313.2,
  "PriceBreakdown": [
   {
    "@type": "PriceBreakdownAir",
    "quantity": 1,
    "requestedPassengerType": "ADT",
    "Amount": {
     "@type": "Amount",
     "CurrencyCode": {
      "decimalPlace": 2,
      "value": "AUD"
     },
     "Base": 270,
     "Taxes": {
      "@type": "TaxesDetail",
      "TotalTaxes": 43.2,
      "Tax": [
       {
        "taxCode": "AY",
        "value": 8.9
       },
       {
        "taxCode": "US",
        "value": 21
       },
       {
        "taxCode": "XF",
        "value": 7.1
       },
       {
        "taxCode": "ZP",
        "value": 7.6
       }
      ]
     },
     "Fees": {
      "@type": "FeesDetail",
      "TotalFees": 0
     },
     "Total": 313.2
    }
   }
  ]
 },
 "Brand": {
  "@type": "BrandID",
  "BrandRef": "b1"
 },
 "Product": [
  {
   "@type": "ProductID",
   "productRef": "p23"
  }
 ],
 "TermsAndConditions": {
  "@type": "TermsAndConditionsID",
  "termsAndConditionsRef": "T3"
 },
 "CombinabilityCode": [
  "j2"
 ],
 "BestCombinablePrice": {
  "@type": "BestCombinablePriceDetail",
  "CurrencyCode": {
   "decimalPlace": 2,
   "value": "AUD"
  },
  "Base": 541,
  "TotalTaxes": 87.8,
  "TotalPrice": 628.8,
  "PriceBreakdown": [
   {
    "@type": "PriceBreakdownAir",
    "quantity": 1,
    "requestedPassengerType": "ADT",
    "Amount": {
     "@type": "Amount",
     "CurrencyCode": {
      "decimalPlace": 2,
      "value": "AUD"
     },
     "Base": 541,
     "Taxes": {
      "@type": "TaxesDetail",
      "TotalTaxes": 87.8,
      "Tax": [
       {
        "taxCode": "AY",
        "value": 17.8
       },
       {
        "taxCode": "US",
        "value": 40.6
       },
       {
        "taxCode": "XF",
        "value": 14.2
       },
       {
        "taxCode": "ZP",
        "value": 15.2
       }
      ]
     },
     "Total": 628.8
    }
   }
  ]
 }
}

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:

  • 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).

Brand Attributes

The Search APIs return brand attributes that describe what is included in the brand. The BrandAttributeobject 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 this example excerpt for brand id b0, several features are included while rebooking and refunds are available at charge per the terms and conditions. 


        "Brand": [
          {
            "@type": "Brand",
            "name": "Red eDeal",
            "tier": 1,
            "shelfNumbers": [],
            "id": "b0",
            "Identifier": {
              "value": "1125969"
            },
            "BrandAttribute": [
              {
                "@type": "BrandAttribute",
                "classification": "CarryOn",
                "inclusion": "Included"
              },
              {
                "@type": "BrandAttribute",
                "classification": "Meals",
                "inclusion": "Included"
              },
              {
                "@type": "BrandAttribute",
                "classification": "LieFlatSeat",
                "inclusion": "Included"
              },
              {
                "@type": "BrandAttribute",
                "classification": "PremiumSeat",
                "inclusion": "Included"
              },
              {
                "@type": "BrandAttribute",
                "classification": "SeatAssignment",
                "inclusion": "Included"
              },
              {
                "@type": "BrandAttribute",
                "classification": "Rebooking",
                "inclusion": "Chargeable"
              },
              {
                "@type": "BrandAttribute",
                "classification": "Refund",
                "inclusion": "Chargeable"
              }
            ],

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.

The following SearchModifiersAir excerpt uses ProductInclusionPreference to request only fares that include a checked bag, seat assignment, and carry-on bag. The response still returns other brand attributes for that fare, which may be included, chargeable, or not offered. 


...
   "SearchModifiersAir": {
      "@type": "SearchModifiersAir",
      "ProductInclusionPreference": [
         {
            "Classification": [
               "CheckedBag",
               "SeatAssignment",
               "CarryOn"
            ]
         }
  ...

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.

All search responses for all customers merge duplicate GDS and NDC offers and remove the duplicated offers. If you would like to opt out of this duplication removal feature, in which case your Search responses may contain duplicate GDS and NDC content, contact your Travelport representative.

Search Workflows

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

Each box in the diagram represents one API call in the workflow.

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.

For additional examples and scenarios, download the developer toolkits and see Using Postman and Developer Toolkits.
For each leg, the search responses combine a flight or connecting flights into a product available at a specific price and terms and conditions - this is called an offer. Be sure to see the detailed discussion of Offers in the JSON APIs to understand the structure of the Search API responses.

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 pricing or bookingClosed A confirmed reservation with the carrier. A held booking is a reservation that has not yet been ticketed. The terms booking and reservation are interchangeable.:

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: One instance for each leg, including an array of the products available on that leg.

  • ReferenceListFlight: Details for each flight including arrival and departure times, flight number, duration, etc. When applicable, includes the OperationalStatus of the flight (Flight Cancelled, FlightDeparted, FlightPastScheduledDeparture, FlightBoarding, NotAvailableUseSearch).

  • ReferenceListProduct: Details for 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: