AirSearch API

This topic provides details and examples specific to the AirSearch API in addition to the general information in Air Shopping Basics.

In this topic:

AirSearch Requests

Key points about the AirSearch request:

  • By default AirSearch returns a summary view. You can request a detailed view per below.
  • To return branded fares in AirSearch, you must request them.
  • AirSearch supports certain search modifiers at the leg level per below.
  • AirSearch does not have any follow-on search requests.

For the GET request for subsequent pagination requests, see Pagination.

Detailed and Summary Views

By default AirSearch returns a summary response for all requests. To request the detailed view instead, add ?view=detail to your POST request per the AirSearch API Reference.

The following differences apply in the detailed response:

  • PriceBreakdown: The Price object is returned with a type of PriceDetail and includes a PriceBreakdown object that provides a breakdown of price per PTC, in addition to the total price for all passengers returned in Price.
  • ReferenceListBrand: When branded fares are requested:
    • In the summary response, brand details are returned in the offer itself in CatalogOffering/PassengerFlight/Brand.
    • In the detailed response, brand details are consolidated in the ReferenceListBrand object. CatalogOffering/PassengerFlight/Brand returns only a brand identifier.
  • ReferenceListFlight: Includes terminal in Flight/Departure and Flight/Arrival.
  • TicketingAgency: TicketingAgency is returned in TermsAndConditionsAir when the ticketing agency PCC is different from the requesting agency PCC. (See Dual PCC Search.)

  • AvailabilitySourceCode: The AvailabilitySourceCode is returned in FlightDetail.

Leg and Itinerary Level Preferences

AirSearch supports requesting all preferences at the itinerary level (the same preference applies to all segments of travel). You can also request carrier, cabin, and class of service preferences at the leg level (i.e., you can apply a different preference to each leg of travel).

When requesting any preference at the leg level, you set a sequence number for each leg in the itinerary in SearchCriteriaFlight/legSequence. You also add legSequence in the SearchModifiersAir preference object to specify the leg to which the preference applies.

The legSequence of the first leg should start with value 1 and each subsequent legSequence value should be incremented by 1. Do not send legSequence values out of order. If legSequence is not sent correctly, AirSearch ignores the preference and returns the message "The legSequence at SearchCriteriaFlight and type of preference do not match. Type of preference has not been applied." For example, the error message for carrier preference is "The legSequence at SearchCriteriaFlight and CarrierPreference do not match. Carrier preference has not been applied."

When requesting a carrier preference at the itinerary level, add the appropriate preference in SearchModifiersAir. No legSequence values are necessary.

Branded Fare Details in AirSearch Request

AirSearch does not return branded fare attributes by default; you must request their return. In addition, brand information returned varies between the summary and detailed AirSearch responses.

To return branded fares, set returnBrandedFaresInd to true per below. If not sent, the response does not return brand details.

  "CatalogOfferingsQueryRequest" : {
    "CatalogOfferingsRequest" : [ {
      "@type" : "CatalogOfferingsRequestAir",
      "offersPerPage" : 5,
      "returnBrandedFaresInd" : true,

ProductInclusionPreference, which allows you to request only brands that include certain attributes, can be applied only to the entire itinerary, not to an individual leg. You do not need to send LegSequence for ProductInclusionPreference; however, if you do include it, you must send the same Classification values in each LegSequence, per the example below. If different Classification values are sent, ProductInclusionPreference is ignored.

Meta Search

Meta Search offers these benefits:

  • Provides faster response times.
  • Targets lowest fare options and those itineraries that are most attractive to leisure travelers.
  • Returns a maximum of 50 flights.

To use Meta Search, add the query parameter view=turbo to the AirSearch POST request as detailed in the AirSearch API Reference.

Note that Meta Search does not support the detail view, brand information, or NDC content. The AirSearch request payload remains the same, and all search modifiers can be used with Meta Search.

AirSearch Responses

For both POST and GET requests, the AirSearch response structures information into two primary objects: CatalogOfferings and ReferenceList. Flight options and price points are returned in CatalogOfferings while details across those offerings are consolidated in ReferenceList.

Offers (CatalogOfferings)

Each CatalogOffering lists all flight options valid at one price point under the same terms and conditions. The number of CatalogOffering objects returned depend on availability and the pagination options you set.

Each instance of CatalogOffering includes the three following primary objects to detail the offer:

  • ProductOptions: Flight or flights for one leg of the itinerary. A one-way search returns one instance of ProductOptions; round-trip searches return two instances of ProductOptions. For round-trip and multi-city itineraries, each instance of ProductOptions includes a sequence identifier to note its order in the itinerary.
  • Price: The price point for that offer. All ProductOptions in this CatalogOffering are available at this price. Provides the base fare, total taxes, total fees, and total price inclusive of all passengers across all PTCs for that CatalogOffering. For a price breakdown per PTC, request a detailed response to return the PriceBreakdown object.
  • TermsAndConditions: Any terms and conditions provided by the carrier that apply to all options in that offering. This can include validating carrier, last day to ticket, and baggage allowance information.

Flight and Brand Details (ReferenceList)

After the CatalogOfferings object, a ReferenceList object consolidates common information across offers. ReferenceList objects can be of types ReferenceListFlight or ReferenceListBrand.

ReferenceListFlight objects consolidate flight details such as flight number, distance, duration, and arrival and departure locations, dates and times. Flight identifiers here match to the flight identifiers provided in CatalogOffering/ProductOptions/Product/FlightSegment/Flight.

Dual PCC 

Some faring agencies queue their bookings to another agency for ticket issuance. When the faring agency and the ticketing agency are different, in the detailed view, AirSearch automatically returns the TicketingAgency PCC to identify the ticketing agency.

AirSearch does not return the TicketingAgency PCC in summary view or for Meta Search, or when the faring agency is also the ticketing agency. No request for this feature is necessary except to request detailed view.

The following example excerpt shows the TermsAndConditions Air object with the TicketingAgency object.

"TicketingAgency": [
  {
    "Code": "79JP",
    "ProductRef": [
      "p0",
      "p1",
      "p2",
      "p3"
    ]
  }

Branded Fare Details in the Response

When branded fare details are requested, brand details are returned as follows:

  • In the detailed response: Branded fare details are consolidated in the ReferenceListBrand object. CatalogOffering/PassengerFlight/Brand returns only a brand identifier that matches to the reference list details.
  • In the summary response: Branded fare details are returned in the offer in CatalogOffering/PassengerFlight/Brand. Only basic brand details are returned: the brand name, tier (not returned for NDC), and the supplier identifier for that brand. Brand attributes identifying what the brand includes are not returned.

AirSearch to SOAP/XML APIs (Universal API)

This section discusses the hybrid workflow, which applies only if you follow your AirSearch request by switching to the Travelport SOAP/XML API (formerly called Universal API) to run an Air Pricing request. After pricing you can book the selected flights through the SOAP/XML APIs.

Below is the mapping from the AirSearch response to the SOAP/XML APIs API Air Pricing request, followed by examples of all requests and responses in the flow.

Note: To continue the Air workflow in the JSON APIs, use the JSON AirPrice API.

SOAP/XML Help Resources

See the following topics:

AirSearch to Air Pricing Mapping

Per below, in your SOAP/XML Air Price request you must include specific objects from the AirSearch response, plus additional data. Other AirSearch response data is optional.

All of the following data from the AirSearch response is required in the Air Pricing request:

  • From the ReferenceListFlight/Flight object for each segment:

    • carrier
    • flight number
    • equipment
    • departure location
    • departure date and time
    • arrival location
    • arrival date and time
  • From ProductOptions/ProductAir/PassengerFlight, the passenger type code (PTC).

The following data from the AirSearch response is optional in the Air Pricing request:

  • From ProductOptions/ProductAir/PassengerFlight/FlightProduct/Brand of the relevant CatalogOffering, the brand tier for each flight. Note: When the brand tier differs for each flight, a flight reference must be sent for each brand tier.
  • From the ProductOptions/ProductAir/PassengerFlight/FlightProduct of the relevant CatalogOffering, the class of service for each flight. Note: A flight reference must be sent for each class of service.

When ProductOptions/ProductAir returns multiple FlightSegment objects, the sequence defines the flights as connecting.

In addition to the information from the AirSearch response, all of the following is required in the SOAP/XML Air Pricing request (AirPriceReq):

  • The Billing Point of Sale Info Origin Application you use for Travelport SOAP/XML APIs.
  • All of the following for each segment:
    • A unique Key value.
    •  A group number. Notes:
      • When the flight is not connecting to another flight, the Group number of the air segment is unique.
      • When the flight is connecting to another flight., the Group number of the air segments is the same (AirSearch sequence "1" "2" "3" = uAPI Group "1" "1" "1").

    • When the flight is connecting to another flight, for Worldspan (1P) only, the Connection element.
    • The provider code you use for SOAP/XML APIs.
  • A unique Key value for each passenger.
  • The Air pricing command.

The table below maps the individual elements from the AirSearch response to their corresponding location in the SOAP/XML Air Pricing request.

JSON AirSearch Response Object... ... maps to SOAP/XML Air Pricing Request Element

ReferenceListFlight

AirItinerary

Flight/carrier

AirSegment @Carrier

Flight/number

AirSegment @FlightNumber

Flight/equipment

AirSegment @Equipment

Departure/location

AirSegment @Origin

Arrival/location

AirSegment @Destination

Departure/date + /time

AirSegment @DepartureTime

Arrival/date + /time

AirSegment @ArrivalTime

ProductOptions/ProductAir/FlightSegment/sequence

AirSegment @Group (see notes above on Group number)

AirSegment/Connection (see notes above on Group number)

ProductOptions/ProductAir/PassengerFlight/passengerTypeCode

SearchPassenger @Code

SearchPassenger @BookingTravelerRef

ProductOptions/ProductAir/PassengerFlight/ FlightProduct/Brand/tier

AirPricingCommand/AirSegmentPricingModifiers @BrandTier

ProductOptions/ProductAir/PassengerFlight/FlightProduct/classOfService

AirPricingCommand/AirSegmentPricingModifiers/PermittedBookingCodes/BookingCode @Code

AirPricingCommand/AirSegmentPricingModifiers @AirSegmentRef

AirSearch to Air Pricing Examples

Below are examples of the JSON AirSearch request and response and SOAP/XML Air Pricing request and response.

AirSearch Request

The example below shows the JSON payload of a request for a one-way search for flights from SFO to DSM.

AirSearch Response

The sample below is an excerpt of the AirSearch response to the above request.

For brevity the sample below shows only the CatalogOffering with id o0. For this example, we will send the required information to the SOAP/XML Air Pricing request from the first ProductOptions/ProductAir, which consists of flights s2 and s3. We will also send the necessary information from the ReferenceListFlight/Flight with id s2 and s3.

In the example below, the names of the objects containing the required information to pass to the Air Pricing request are highlighted in blue. The required data itself is highlighted in yellow. The optional data is highlighted in grey.

SOAP/XML Pricing Request

Below is an example request in the SOAP/XML AirPriceReq transaction.

  • All required data from the AirSearch Summary response above is highlighted below in yellow.
  • Additional data required in the API AirPriceReq is highlighted in green.

SOAP/XML Pricing Response

The following example shows the SOAP/XML Air Pricing response returned for the request above. For information on booking the priced flights, see Air Booking.

 

AirSearch v9 Examples

One-Way Search Request

The following example message payload shows a one-way search request for both NDC and GDS content with Singapore Airlines as the only permitted carrier. The POST request for this example was set to the detail view.

One-Way Search Response - NDC and GDS

The following example shows both NDC and GDS content. For brevity this example was edited to show only three offers and their corresponding ReferenceListFlight details: CatalogOffering ids o0.0 and o0.1 are GDS and CatalogOffering id SQ1 is an NDC offer.