Flight Availability Search API

Overview

The Flight Availability Search API provides real-time flight availability and pricing information. Search for available flights based on origin, destination, travel dates, and passenger requirements.

This API is the first step in the booking process to search for available flights and prices.

Authentication

This API uses OAuth 2.0 authentication. You must include a valid access token in your requests:

Authorization: Bearer <your_access_token>

Each API key is linked to a specific agent profile. The agent profile determines which flights and fares are visible based on role permissions in the NewSkies system.

Requesting Access

When creating your application in the developer portal:

1. Create your app with a descriptive name and obtain your API key
2. Important: Contact us at yoda@tui.de with the following information:
   • Your app name (as shown in the developer portal)
   • The AgentName you need to be mapped to (this will be provided to you by the API team)

Without this mapping, your API requests will fail with a 401 Unauthorized error.

Base URLs

Quick Example

Search for one-way flights from Brussels to Alicante:

curl -X GET "https://test.api.tui/flight/newskies/availability/v2/search?outboundStartDate=2024-06-01&outboundEndDate=2024-06-30&departureStationCodes=BRU&arrivalStationCodes=ALC&tripType=0&PassengerCount=2" \
  -H "Authorization: Bearer <your_access_token>"

API Endpoint

Search for Flight Availability

Endpoint: GET /search

Description: Search for available flights based on origin, destination, dates, and passenger criteria.

Required Parameters

• Travel dates (outboundStartDate and outboundEndDate)
• Either departure/arrival stations OR departure/arrival countries
• Trip type (tripType)

Query Parameters

* Required when tripType=1 (RoundTrip)
** Must provide either station codes OR country codes (or both)

Response Codes

Use Cases

One-Way Flight Search

Search for one-way flights from Brussels to Alicante:

GET /search?outboundStartDate=2024-06-01&outboundEndDate=2024-06-30&departureStationCodes=BRU&arrivalStationCodes=ALC&tripType=0&PassengerCount=1

Round-Trip Flight Search

Search for round-trip flights from London to Palma de Mallorca:

GET /search?outboundStartDate=2024-07-01&outboundEndDate=2024-07-15&inboundStartDate=2024-07-15&inboundEndDate=2024-07-31&departureStationCodes=LHR&arrivalStationCodes=PMI&tripType=1&PassengerCount=2

Multi-Airport Search

Search flights from multiple UK airports to Spanish destinations:

GET /search?outboundStartDate=2024-08-01&outboundEndDate=2024-08-31&departureStationCodes=LHR,MAN,BHX&arrivalStationCodes=ACE,LPA,TFS&tripType=0

Carrier-Specific Search

Search only TUI flights:

GET /search?outboundStartDate=2024-06-01&outboundEndDate=2024-06-30&departureStationCodes=BRU&arrivalStationCodes=ALC&carrierCodes=TB&tripType=0

Limited Results with Grouping

Get top 5 groups with 3 flights each, grouped by date:

GET /search?outboundStartDate=2024-06-01&outboundEndDate=2024-06-30&departureStationCodes=BRU&arrivalStationCodes=ALC&tripType=0&GroupBy=1&LimitGroups=5&LimitFlights=3

Response Structure

Success Response (200 OK)

{
  "groups": [
    {
      "name": "BRU-ALC",
      "flights": [
        {
          "departureDateTime": "2024-06-15T10:30:00Z",
          "arrivalDateTime": "2024-06-15T13:15:00Z",
          "carrierCode": "TB",
          "flightNumber": "1234",
          "departureStationCode": "BRU",
          "arrivalStationCode": "ALC",
          "departureCountryCode": "BE",
          "arrivalCountryCode": "ES",
          "availability": 9,
          "flightDuration": 165,
          "journeyKey": "TB~1234~20240615~BRU~ALC",
          "encryptedJourneyKey": "encrypted_key_here",
          "operatingCarrierCode": "TB",
          "stopOverFlights": [],
          "fares": [
            {
              "fareBasisCode": "YOWRT",
              "productClass": "Y",
              "classOfService": "Y",
              "fareKey": "fare_key_123",
              "encryptedFareKey": "encrypted_fare_key",
              "currencyCode": "EUR",
              "priceGrossAdt": 150.00,
              "priceGrossChd": 120.00,
              "priceGrossInf": 25.00,
              "priceNetAdt": 130.00,
              "priceNetChd": 100.00,
              "taxes": 15.00,
              "fees": 5.00,
              "surcharges": 0.00
            }
          ]
        }
      ]
    }
  ]
}

Error Response (400 Bad Request)

{
  "ErrorMessage": "OutboundStartDate is required",
  "StackTrace": null
}

Unauthorized Response (401 Unauthorized)

{
  "ErrorMessage": "Unauthorized",
  "StackTrace": null
}

Data Models

Flight Object

• Schedule: Departure/arrival times and duration
• Route: Origin/destination airports and countries
• Carrier: Marketing and operating carrier codes
• Availability: Number of available seats
• Identifiers: Journey keys (plain and encrypted)
• Stopovers: Multi-leg journey information (up to 2 stopovers)
• Fares: Available fare options with pricing

Fare Object

• Fare Details: Basis code, product class, class of service
• Pricing: Gross/net prices for adults, children, and infants
• Additional Costs: Taxes, fees, and surcharges
• Currency: Price currency code
• Keys: Fare identifiers (plain and encrypted)

FlightGroup Object

• Name: Group identifier (route or date)
• Flights: Array of flight objects

Additional Resources

• API Specification: See the API Details tab for complete endpoint reference
• Code Examples: See the Examples tab for integration code samples
• Release Notes: Check the Release Notes tab for version history