Air Shopping Basics

Use the AirSearch API to shop for scheduled flights between a given set of cities. This topic discusses concepts and basic information about air shopping.

In this guide:

• Basic Concepts
• Search Terms: Itinerary/Offer, Leg/Product
• Identifier Values, IDs, and Transaction IDs
• AirSearch API
• Search Request Basics
  • NDC Content
  • Search Modifiers
  • Pagination
• Search Response Basics
  • Branded Fares

Basic Concepts

The following terms are essential to understanding travel development.

You can search for any of the following types of itineraries:

• One way: Trip to a single destination; e.g., LHR > CDG.
• Round trip: Trip to a single destination and back to the original point of departure; e.g., LHR > CDG and CDG > LHR.
• Multi-city: Trip to multiple destinations; e.g., LHR > CDG > AMS > BCN.
• Open-jaw: Trip to one destination and a return from another city; e.g., LHR > CDG and AMS > LHR.

The airline industry categorizes travelers under various passenger type codes (PTCs). The most common PTCs are Adult (ADT), Child (CHD/CNN), and Infant (INF). You can request a maximum of nine passengers in one air search.

An airfare with certain features included in the price is a branded fare. For example, a branded fare may include a seat assignment choice and wifi at no extra charge. Upsell to a higher brand is an integral part of branding. Branded fares are discussed later as part of the search response.

Airlines offer different levels of service, grouping services into cabin classes. The following are standard cabin classes:

• Economy: Travelers receive standard services with no perks. Identified by cabin class code Y or the word COACH.
• Premium Economy: Travelers receive a better seating preference than Economy class. Identified by cabin class code W.
• Business: Travelers receive more service than economy but fewer than First. Identified by cabin class code C.
• First: Travelers receive upgraded service; the most expensive fares. Identified by cabin class code F.

Search Terms: Itinerary/Offer, Product/Leg

Next, it's important to understand the following terms for how the JSON APIs return itineraries and their components. Let's say you have a round-trip booking from LAX>MSP. The trip starts with a direct flight from LAX>MSP. On returning, there is a change connection in DEN, so MSP>DEN>LAX.

• Itinerary: The itinerary, sometimes called a journey, is the entire trip on the booking. In our example, this includes everything: LAX>MSP and the return MSP>DEN>LAX.
  • A complete itinerary is presented as an offer across the JSON APIs. Every offer returned by a search API has a unique offer identifier. You send the selected offer identifier in almost all subsequent APIs in the workflow, from pricing to booking and even refunds and exchanges.
• Leg: A leg is the flight or all flights that go from one origin to one destination. Our example has two legs: LAX>MSP is the first leg and MSP>DEN>LAX is the second leg.
  • Each leg of a journey is returned as a product. Product identifiers are important in the search APIs because you can combine products into an offer, but less important in most other APIs in the workflow because the offer has been selected.
• Segment: A segment is a flight under one flight number. A single segment can have multiple flights as long as the flight number remains the same, such as when a flight makes a stop without changing planes. In our example, the first leg has one segment (LAX>MSP). The return leg has two segments (MSP>DEN and DEN>LAX) because there is a change of plane.
  • Each flight number makes up a single segment.
  • Segments are identified by sequence numbers in the FlightSegment object.

Identifier Values, IDs, and Transaction IDs

The ODM model used for JSON APIs relies on many identifiers. It's critical to understand the differences between various identifiers:

• Many objects in the same response return an identifier value in Identifier/value. This is always a system-generated string, for example, 3cecf1be-0b21-4881-8f33-ae11c8d7b708. Such identifier values are unique within the same transaction and across all search transactions. These identifiers must frequently be sent in subsequent requests.
• An id is an internal reference number in the id object and is always a short, system-generated string. An id is unique within the response but not unique across multiple search responses. This id is often used to cross-reference offer details with reference information for products, brands, flights, etc.

Many objects will return both id and Identifier/value. In the example excerpt below, CatalogProductOfferings has only the identifier value while CatalogProductOffering has both an id (QF_CPO0) and an Identifier value (WDhCQUNCRkE5LTIxNDgtNERBQS1BNkJ8UUZfQ1BPMA==).

In this example, CatalogProductOfferings/Identifier/value identifies the transaction as a whole when passed in subsequent requests. The value in CatalogProductOffering/id identify the offer when passed in subsequent requests.

In addition, the response in some JSON APIs returns one and only one transactionId under the first top-level object, also shown below. Unlike either of the above, transactionId is a system-generated ID used not for itinerary details but to assist both Travelport and customers with troubleshooting if necessary. Optionally, and not shown below, customers can send a custom traceId in the header. For details see Transaction and Trace IDs.

Identifiers are not used as extensively in the v6 JSON APIs as in v9, but are used in some APIs.

JSON AirSearch API

The JSON APIs use AirSearch for shopping flights. AirSearch is available on v6 and v9 and will not be upgraded to v11. Eventually, Search v11 will provide all Travelport JSON air search capabilities and all customers will move to the Search API.

AirSearch returns a journey-based representation of available flights at the lowest fares, with each itinerary option at the same price point grouped into offers.

Key points:

• Individual legs, or products, cannot be selected separately and combined into offers.
• Branded fare details are not returned by default but can be requested.

Search Request Basics

AirSearch requires a minimum search request that includes the PassengerCriteria and SearchCriteriaFlight objects. PassengerCriteria sets the number and type of passengers. SearchCriteriaFlight specifies itinerary details such as date and location for departure and arrival. You can add search modifiers to this basic request as needed.

NDC Content

AirSearch supports requesting both NDC and GDS content, only NDC, or only GDS. Send the contentSourceList indicator with one or both of the following supported values.

• GDS: Returns only GDS content.
• NDC: Returns only NDC content.

If contentSourceList is not sent, only GDS content is returned.

Search Modifiers

AirSearch 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.

Pricing modifiers refine your 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 Code: Send your account code for each airline to return negotiated fares for those airlines.
• Currency Override: Change the default currency of results.

Journey modifiers allow you to refine your 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: Specify preferences around a specific airline or multiple airlines.
• Cabin Preferences: Specify cabin preferences.
• Class of Service Preferences (AirSearch API only): Fares based on the class of service.
  • Note that AirSearch supports applying the above preference to specific legs of the itinerary; see AirSearch API Reference.
• Flight Type: Connections and stops.
• Exclude Ground Transportation: Do not return ground transportation options.
• Max Connection Duration: Do not exceed a set 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 fares that change airport.
• Return Only Fares with Specified Brand Attributes: Limit the fares returned to only fares that include the specified brand attributes in the price.

Pagination

AirSearch supports the optional pagination feature. Pagination allows you to control the number of offers returned in the initial response, which can affect response time. All offers are cached on the server, but only the number in offersPerPage is returned in the initial response. For example, if offersPerPage is set to 5, only the first 5 offers, or price points, are returned in the initial response.

See Pagination for the GET request for second and subsequent pages.

Search Response Basics

The AirSearch response structures flight details into offers. An offering is one flight or set of connecting flights available on one leg of the itinerary, returned as a product at a set price with specific terms and conditions. A product is one flight or set of connecting flights and an associated service level, including the cabin class and any special fare codes that may apply. See the AirSearch topic for details.

Branded Fares

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

• The base fare may include simply the ticket, and customers must purchase ancillaries such as a paid seat and baggage separately.
• Brand 1 might include seat selection and a free carry-on.
• Brand 2 might include those features plus in-flight wifi and a free checked bag.

The offers in the response include only a brand reference number in BrandRef, such as b0, b1, etc. Brand details are consolidated in ReferenceList/ReferenceListBrand. Each BrandRef number matches to a value in ReferenceList/ReferenceListBrand @id. These are internal references used within the search response.

Fare Family Search returns branded fare details by default. AirSearch provides an option to request branded fare details.

The branded fare details returned are the brand name, tier, id (internal reference number matching to the BrandRef in the offer), the brand identifier returned from the airline, and brand attributes.

The brand attributes tell you what is included in the brand. BrandAttribute is an array of classification and inclusion:

• classification: Possible values are:
  • CarryOn
  • Refund
  • Meals
  • Rebooking
  • CheckedBag
  • SeatAssignment (note that for both AirSearch and Fare Family Search on model v6 only this value is Seats)
  • WiFi
• inclusion: Whether the attribute is included in the price of the fare or chargeable:
  • Included: The attribute is included in the fare for that brand at no additional charge.
  • Chargeable: The attribute can be purchased for that brand at an additional cost.
  • Not Offered: Search returns Not Offered to indicate the brand attribute is not available for a flight. AirSearch and Fare Family Search do not return a classification value for any brand feature not available.