Air Availability

The Air Availability Search returns scheduled flights between a given city pair on a given day, and indicates whether seats are available on those flights.

Note that the Air Availability Search returns availability, but does not include any pricing information. To obtain pricing, a follow-up Air Pricing transaction must be made.

Schema

Located in Air.xsd:

Request

  1. Enter the minimum required data in AvailabilitySearchReq, an extension of AirSearchReq that is used to return a set of available itineraries (an Air Itinerary Solution) according to the search criteria.

    2. Minimum required data includes information in the child elements of SearchAirLeg or SearchSpecificAirSegment.

    Note: Search by specific flights is mutually exclusive from normal origin and destination availability (general or carrier-specific).

    SearchAirLeg identifies the departure and arrival dates, times, and locations for each leg of the trip. Each instance of SearchAirLeg node represents a request for a discrete leg of an air trip.

    • Search Origin and SearchDestination city and/or airport codes. A maximum of six origins and destinations, respectively, can be included in the request using typeLocation. 

      • Note: The CoordinateLocation child is not currently supported. 

    • A departure or arrival date. No default date is assumed; a departure or arrival date must be entered.
    • A departure or arrival time.
    • @MaxJourneyTime: This attribute restricts results to those segments that are less than the maximum journey time (in hours). To restrict the journey time of the entire journey, use AirSearchModifiers @MaxJourneyTime. This filter applies to 1G, 1V, 1P only.

    Important! If multiple SearchAirLeg elements are specified in the request, Universal API returns an AirItinerarySolution with Connection indicators in the response for each search leg specified. See Air Segment Connection Logic.

    SearchSpecificAirSegment allows a search of specific flight segments, including origin/destination, carrier (supplier) code, flight number, departure date, and connection indicator. The number of passengers can be also be specified. The response includes the specific flight segments. Other modifiers are not supported, and a warning is sent in the response.

  2. Send optional data in the request.

    3. When AvailabilitySearchReq @ReturnBrandedFares="true", the response identifies air segments where the provider supports Rich Content and Branding with AirSegmentList/AirSegment @BrandIndicator="B".

    AirSearchModifiers contains flight-related criteria that can be used to narrow a search response, such as preferred suppliers and connecting cities, flight types, and flexible times. See Air Availability Modifiers for more details.

    Note: Because Air Availability returns only availability responses, but no pricing information, pricing modifiers do not apply to Air Availability requests.

    • @ExcludeOpenJawAirport: This attribute is available at the Itinerary level for Worldspan only in the Low Fare Shopping request.
    • MaxLayoverDuration: This element is available at the Itinerary level for Worldspan only in the Low Fare Shopping request.
    • @MaxJourneyTime: This attribute restricts results to itineraries that are less than the maximum journey time (in hours). To restrict the journey time of segment legs, use SearchAirLeg/AirLegModifiers@MaxJourneyTime. This filter applies to 1G, 1V, 1P only.

    JourneyData should be submitted for each air segment that is "added to the cart" in a User Interface. Although these segments are not sold when they are added to the cart in a UI, there is a reduction in Production system inventory. Including JourneyData for each segment in a cart ensures that only flights that are combinable are included in subsequent availability calls, which prevents segment sell failures.

    For example, after performing an Air Availability search from DEN to LHR and selecting a flight, the data for the selected flight should be included in JourneyData in the second Air Availability search for return flights from LHR to DEN.

    JourneyData is optional, but if submitted, all required elements and attributes in AirSegment must also be submitted.

    Important! Air Segments must be included in JourneyData/AirSegment in the order in which they are added to the cart in the UI, and based on Departure Date, Origin, and Destination.

    /AirSegment

    When JourneyData/AirSegment is sent in the request, these attributes are required:

    • @Origin
    • @Destination
    • @Group: The Origin Destination Grouping of this segment.

    SearchPassenger allows a search by the number of passengers and/or passenger type. The count of the number of Search passengers in a request can be used to filter out classes in the response that do not have the requested number of seats.

    PointOfSale includes Pseudo City Code (PCC) and branch data for the transaction. If PointOfSale is not specified on the request, the credentials in the HTTP header of the request are used to determine point of sale information. If PointOfSale data is specified, it overrides the default data in the credentials. 

    The PointOfCommencement element allows users to send in a city/airport code, date, and time as the point of commencement to apply to all flight segments. The POC is applied only on flight-specific and general availability, not for direct access availability. If PointOfCommencement is used, the attributes @CityOrAirportCode and @Time are mandatory. Note that @Time must include a date; including a time along with the date is optional. Examples of all supported formats are as follows:

    • <common:PointOfCommencement CityOrAirportCode="LHR" Time="2016-06-11"/>
    • <common:PointOfCommencement CityOrAirportCode="LHR" Time="2016-06-11T13:30:00.000"/>
    • <common:PointOfCommencement CityOrAirportCode="LHR" Time="2016-06-11T13:30:00"/>
    • <common:PointOfCommencement CityOrAirportCode="LHR" Time="2016-06-11T13:30"/>

    If the mandatory attributes are not included, Universal API does not process the request and returns the error message "Missing required attribute "CityOrAirportCode"," or "Missing required attribute "Time"."

    For customers using the Search Control Console (SCC), SCC attributes were added to AvailabilitySearchReq in release 17.1 for Galileo (1G) and Apollo (1V) as follows:

    SCC and COA is used by agency administrators to create business rules for filtering certain air shopping results. Two optional attributes allow SCC / COA users to either activate or override these filters:

    • ChannelID, which activates an SCC / COA filter for a portion of travelers served by the agency PCC, such as a specific corporation or group.
    • NSCC, which is used to bypass or override a specific SCC / COA rule.

    These attributes were added to AirFareDisplayReq and to the AirPricingModifiers element in LowFareSearchReq, LowFareSearchAsynchReq, and AirPriceReq for Galileo (1G), Apollo (1V), and Worldspan (1P). They were also added to AirCreateReservationReq and AvailabilitySearchReq in release 17.1 for 1G and 1V.

    Only one attribute can be used in a single request, either ChannelID or NSCC. If both are used together, or if an SCC / COA rule is violated, Universal API does not send the transaction response and returns an error.

    Note the following:

    • ChannelID: Four-character alphanumeric string. Values should be uppercase for 1G and 1V; lowercase values for 1P (if supported for that transaction) may or may not be processed so uppercase is recommended. If an invalid user ID and a valid attribute value are sent, the message AGENT NOT AUTHORISED is returned. In the case of an invalid ID format, the following messages are returned:
      • 1G: INVALID MODIFIER
      • 1V: INVALID INPUT
      • 1P: The attribute is ignored and a successful response is returned.
    • NSCC: Valid values for the rule type identifer number to be sent are 000 to 999. If an invalid user ID and a valid attribute value are sent, the message AGENT NOT AUTHORISED is returned. In the case of an invalid ID format, the following messages are returned:
      • 1G: INVALID MODIFIER
      • 1V: INVALID INPUT
      • 1P: ERR10 INVALID

      Note: If your client application does not use SCC or COA, do not use these attributes. Please contact your Travelport representative if you would like additional information.

      SCC and COA is not applicable to Airline Content Hub (ACH).

Response

AvailabilitySearchRsp is returned with a maximum of 48 flights are returned per request.

    • Departure and arrival airport codes
    • Departure date and time
    • Arrival date and time
    • Direct indicator
    • Marketing carrier
    • Marketing flight number
    • Operating flight number
    • Operating carrier
    • E-ticketable indicator
    • Cabin class
    • Class of service (RBD)
    • Available seats per class of service
    • Type of stop
    • Flight duration
    • Interline indicator
    • Participant level
    • Code share indicator for code share carrier (does not include flight number).
    • Carrier-specific (link) display and inside (polled) availability. See Air Availability by Carrier and Alliance.
    • Equipment type
    • On-time percentage
      Note: Required for US flights, optional for non-US flights.

    The following elements and attributes may be returned:

    A search response may contain a NextResultReference if the provider has additional response data that was not returned in that call. This reference token from the provider can be used in a subsequent request to obtain this additional data.

    FlightDetailsList may return flight details depending on the supplier and their participation level with the provider.

    AirItinerarySolution may return an individual AirSegmentRef multiple times if it is part of a unique journey solution. For example, Flight 1 can connect to Flight 2, or Flight 1 can connect to Flight 3. So Flight 1 appears in the Solution twice.

    If a Connection/SegmentIndex is returned in the response it indicates a connection between two or more air segments. The Connection indicator must be used when Pricing and Booking to ensure the flights are sold correctly and a sell failure does not occur. See Air Segment Connection Logic for more details.

    If sessioned (stateful) transactions were used by the provider or supplier, HostTokenList contains a list of all session tokens associated with the air or rail segments. ACH and RCS suppliers require the HostToken in the Low Fare Shopping response to be sent in the Air Pricing request.

    AirSegmentList returns multiple AirSegments.

    Status identifies the status of the booked air segment.

    Indicates whether the carrier has inside (polled) availability. Refer to Polled Availability Option for more information.

    Indicates the availability source and is used internally.

    If a blacklisted marketing carrier is returned in the response, an indicator displays in AirSegment/Blacklisted. Airlines that are deemed unsafe and thus blacklisted are taken from a list maintained by the European Union. These airlines are banned from servicing points to, from, and within the European Community.

    The operational status of the flight displays as part of the AirSegment/OperationalStatus. Available operational statuses are:

    • Flight Canceled
    • Flight Departed
    • Flight Past Scheduled Departure
    • No Classes Returned From Link
    • Flight Boarding
    • Flight Status Unknown

    If the flight operational status is as per scheduled departure, the operational status is not returned in the response.

    If the request contains AvailabilitySearchReq @ReturnBrandedFares="true", air segments where providers support Rich Content and Branding are identified in the response with AirSegmentList/AirSegment @BrandIndicator="B". A follow-on Air Merchandising Details request is used to retrieve the details of the Rich Content and Branding for an air segment.

 

Next Steps

An Air Availability response can be followed by an Air Pricing request to obtain fare information for selected flight segments.

Exceptions

  • Galileo's default departure time is 08:00 based on the airport locale.

  • Galileo does not return the operating flight number in the response.

  • The maximum number of flight items in the response for a Flight Specific Availability request is 99.

Worldspan supports SearchSpecificAirSegment.

  • If SearchSpecificAirSegment/SegmentIndex is provided. It is ignored by Worldspan, and a warning message is returned: "SegmentIndex is not supported by the requested Provider."
  • If the flight or flights in the request are not available. An error message is returned: "Specific flight not found.|XX123" where XX is the carrier code and 123 is the flight number.

Worldspan does not support the following request data:

  • PointOfSale: If any value is provided in this element in the request, it is ignored, and a warning is returned: "Separate PointOfSale not supported by provider".

Worldspan does not support the following response data:

  • Flight status: Worldspan only provides valid operational flights that are not past the scheduled departure.
  • Link Availability
  • Polled Availability Option/Inside Availability
  • Next Result Reference

For a more complete list of functionality available from various ACH carriers, see ACH Carriers Functionality. Because functionality for carriers may be subject to change, always confirm functionality directly with the ACH carrier before implementation.

  • ACH uses the LowFareSearchReq behind the scenes to populate the AirAvailabilityReq.

  • The number of available seats is not supported by all ACH suppliers. If the number of available seats is:

    • Returned by the supplier, Universal API returns the supplier's number (which may have three digits).

    • Not returned by the supplier, Universal API bases the number of available seats on the number of passengers specified in the request. Therefore, more seats may be available than are actually requested.

  • The HostToken in the response are required to move to a Pricing request.

  • ACH-specific Host tokens are returned in AirAvailInfo/HostTokenRef, not AirSegment/HostTokenRef. Tokens in AirSegment/HostTokenRef are for Carrier-Specific Display.

    Important: ACH has a session timeout limit of 1 hour. However, ACH carriers often have a lower session timeout limit. While API-connected carriers do not publish timeout values, a good rule of thumb is to expect a session timeout limit of 15-20 minutes for an ACH carrier.

  • ACH suppliers return FareTokenInfo elements to link the fares and host tokens (because the fare may be tied to a specific host token).
  • ACH does not support AirLegModifiers/ReturnFirstAvailableOnly. A warning is sent in the response.
  • ACH only provides valid operational flights that are not past the scheduled departure. Flight Status is not supported.
  • Aggregated availability with ACH and SearchSpecificAirSegment is not available.
  • MaxJourneyTime attribute (SearchAirLeg and AirSearchModifiers) is not valid.