openapi: 3.2.0
info:
  title: NSKCC Availability Search API
  description: Flight availability search API with pricing information
  version: 0.1.73
servers:
- url: https://prod.api.tui/flight/newskies/availability/v2
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Search
paths:
  /search:
    get:
      tags:
      - Search
      summary: Search for availability
      operationId: SearchAvailability
      parameters:
      - name: carrierCodes
        in: query
        description: Comma-separated list of airline carrier codes to filter flights (e.g., TB,OR,X3)
        schema:
          type: array
          items:
            type: string
          example: TB,OR,X3
        example: TB,OR,X3
      - name: departureStationCodes
        in: query
        description: Comma-separated list of departure airport codes to filter flights (e.g., BRU,LHR,MAN)
        schema:
          type: array
          items:
            type: string
          example: BRU,LHR,MAN
        example: BRU,LHR,MAN
      - name: arrivalStationCodes
        in: query
        description: Comma-separated list of arrival airport codes to filter flights (e.g., ACE,LPA,PMI)
        schema:
          type: array
          items:
            type: string
          example: ACE,LPA,PMI
        example: ACE,LPA,PMI
      - name: departureCountries
        in: query
        description: Comma-separated list of departure country codes to filter flights (e.g., GB,DE,BE)
        schema:
          type: array
          items:
            type: string
          example: GB,DE,BE
        example: GB,DE,BE
      - name: arrivalCountries
        in: query
        description: Comma-separated list of arrival country codes to filter flights (e.g., ES,FR,IT)
        schema:
          type: array
          items:
            type: string
          example: ES,FR,IT
        example: ES,FR,IT
      - name: outboundStartDate
        in: query
        description: 'Start date of the search range for outbound flights. Use this with OutboundEndDate to search flights within a date range. Format: yyyy-MM-dd (e.g., 2024-06-01)'
        schema:
          type: string
          format: date
          example: '2024-06-01'
        example: '2024-06-01'
      - name: outboundEndDate
        in: query
        description: 'End date of the search range for outbound flights. Use this with OutboundStartDate to search flights within a date range. Format: yyyy-MM-dd (e.g., 2024-12-31)'
        schema:
          type: string
          format: date
          example: '2024-12-31'
        example: '2024-12-31'
      - name: inboundStartDate
        in: query
        description: 'Start date of the search range for inbound/return flights. Use this with InboundEndDate to search return flights within a date range. Format: yyyy-MM-dd (e.g., 2024-06-15)'
        schema:
          type: string
          format: date
          example: '2024-06-15'
        example: '2024-06-15'
      - name: inboundEndDate
        in: query
        description: 'End date of the search range for inbound/return flights. Use this with InboundStartDate to search return flights within a date range. Format: yyyy-MM-dd (e.g., 2024-07-31)'
        schema:
          type: string
          format: date
          example: '2024-07-31'
        example: '2024-07-31'
      - name: PassengerCount
        in: query
        description: 'Number of passengers for availability check (default: 1)'
        schema:
          type: integer
          format: int32
          default: 1
          example: 1
        example: 1
      - name: LimitGroups
        in: query
        description: Maximum number of flight groups to return in the response
        schema:
          type: integer
          format: int32
          example: 10
        example: 10
      - name: LimitFlights
        in: query
        description: Maximum number of flights to return per group in the response
        schema:
          type: integer
          format: int32
          example: 5
        example: 5
      - name: AgentName
        in: header
        description: Agent name for role-based access control and pricing
        schema:
          type: string
          example: AgentName
        example: AgentName
      - name: GroupBy
        in: query
        description: 'Grouping strategy for results: 0 = OriginDestination, 1 = Date'
        schema:
          $ref: '#/components/schemas/GroupBy'
        example: 0
      - name: tripType
        in: query
        description: 'Trip type: Oneway or RoundTrip'
        schema:
          $ref: '#/components/schemas/TripType'
        example: Oneway
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TripType:
      enum:
      - 0
      - 1
      type: integer
      format: int32
    StopOverFlight:
      type: object
      properties:
        stationCode:
          type:
          - string
          - 'null'
          description: Stopover airport code (e.g., MAD, CDG, AMS)
        carrierCode:
          type:
          - string
          - 'null'
          description: Marketing carrier code for the stopover leg
        operatingCarrierCode:
          type:
          - string
          - 'null'
          description: Operating carrier code if different from marketing carrier
        flightNumber:
          type:
          - string
          - 'null'
          description: Flight number for the stopover leg
        sta:
          type: string
          description: Scheduled time of arrival at stopover station
          format: date-time
        std:
          type: string
          description: Scheduled time of departure from stopover station
          format: date-time
      additionalProperties: false
      description: Stopover flight information for multi-leg journeys
    Fare:
      type: object
      properties:
        fareBasisCode:
          type:
          - string
          - 'null'
          description: Fare basis code identifying the fare type
        ruleNumber:
          type:
          - string
          - 'null'
          description: Fare rule number
        productClass:
          type:
          - string
          - 'null'
          description: Product class code (e.g., Y, C, F)
        classOfService:
          type:
          - string
          - 'null'
          description: Class of service code
        fareKey:
          type:
          - string
          - 'null'
          description: Unique fare identifier
        encryptedFareKey:
          type:
          - string
          - 'null'
          description: Encrypted fare identifier for secure operations
        currencyCode:
          type:
          - string
          - 'null'
          description: Currency code (e.g., EUR, GBP, USD)
        priceGrossAdt:
          type: number
          description: Gross price for adult passenger
          format: double
        priceGrossChd:
          type: number
          description: Gross price for child passenger
          format: double
        priceGrossInf:
          type: number
          description: Gross price for infant passenger
          format: double
        priceNetAdt:
          type: number
          description: Net price for adult passenger
          format: double
        priceNetChd:
          type: number
          description: Net price for child passenger
          format: double
        taxes:
          type: number
          description: Total taxes amount
          format: double
        fees:
          type: number
          description: Total fees amount
          format: double
        surcharges:
          type: number
          description: Total surcharges amount
          format: double
      additionalProperties: false
      description: Fare pricing and class information
    FlightGroup:
      required:
      - flights
      - name
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Group identifier (e.g., 'BRU-ACE' for origin-destination or '2024-07-15' for date grouping)
        flights:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Flight'
          description: List of flights within this group
      additionalProperties: false
      description: Group of flights organized by origin-destination or date
    Flight:
      type: object
      properties:
        arrivalDateTime:
          type: string
          description: Flight arrival date and time
          format: date-time
        availability:
          type: integer
          description: Number of available seats for the requested passenger count
          format: int32
        carrierCode:
          type:
          - string
          - 'null'
          description: Airline carrier code (e.g., TB, OR, X3)
        departureDateTime:
          type: string
          description: Flight departure date and time
          format: date-time
        flightNumber:
          type:
          - string
          - 'null'
          description: Flight number
        journeyKey:
          type:
          - string
          - 'null'
          description: Unique journey identifier
        encryptedJourneyKey:
          type:
          - string
          - 'null'
          description: Encrypted journey identifier for secure operations
        flightDuration:
          type: integer
          description: Flight duration in minutes
          format: int32
        departureStationCode:
          type:
          - string
          - 'null'
          description: Departure airport code (e.g., BRU, LHR, MAN)
        arrivalStationCode:
          type:
          - string
          - 'null'
          description: Arrival airport code (e.g., ACE, LPA, PMI)
        departureCountryCode:
          type:
          - string
          - 'null'
          description: Departure country code (e.g., GB, DE, BE)
        arrivalCountryCode:
          type:
          - string
          - 'null'
          description: Arrival country code (e.g., ES, FR, IT)
        operatingCarrierCode:
          type:
          - string
          - 'null'
          description: Operating carrier code if different from marketing carrier
        stopOverFlights:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/StopOverFlight'
          description: List of stopover flights for multi-leg journeys (maximum 2 stopovers)
        fares:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Fare'
          description: List of available fares with pricing details
      additionalProperties: false
      description: Flight availability and pricing information
    SearchResponse:
      type: object
      properties:
        groups:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FlightGroup'
          description: Collection of flight groups organized by the specified grouping strategy
      additionalProperties: false
      description: Search response containing grouped flight results
    Error:
      type: object
      properties:
        ErrorMessage:
          type:
          - string
          - 'null'
        StackTrace:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Error response object for the Api.
    GroupBy:
      enum:
      - 0
      - 1
      type: integer
      format: int32
    UnauthorizedError:
      type: object
      properties:
        ErrorMessage:
          type:
          - string
          - 'null'
        StackTrace:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Unauthorized error response object for the Api.