openapi: 3.0.0
info:
  title: Skyscanner Flights Itinerary API
  description: |
    Open one Skyscanner Flights itinerary, as Skyscanner's booking panel shows it.

    Pass the `itinerary_token` of an itinerary from a Skyscanner Flights search. The answer has the itinerary's legs and flights, with each flight's aircraft, seat layout, seat pitch and onboard services when Skyscanner lists them, and the sellers that offer the itinerary with their prices and booking links. Each option has its `fare_type`, its `baggage`, and its `changes` and `cancellation` when Skyscanner lists them, and a seller can offer several fares. The itinerary is priced for the passengers, travel class, country, currency and bags of the search that found it, and its `price` is its cheapest option. A fee on a bag that is `included` is already part of the option's `price`. An option sold as two tickets, one for each leg, has `is_split_booking`, with each ticket under `departure` and `arrival`. A token stops working once its flights have departed. When Skyscanner no longer has the itinerary, the response carries an `error` instead.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Skyscanner Flights Itinerary
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `skyscanner_flights_itinerary`'
          schema:
            type: string
            enum: ["skyscanner_flights_itinerary"]
        - name: itinerary_token
          in: query
          required: true
          description: Token of an itinerary from a Skyscanner Flights search, found in its `itinerary_token`.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        itinerary:
          $ref: '#/components/schemas/Itinerary'
        error:
          type: string
          description: "Error message describing what went wrong"
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Skyscanner booking panel for this itinerary"
        html_url:
          type: string
          description: "URL to view the raw results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        itinerary_token:
          type: string
          description: "Token of the itinerary opened"
    Itinerary:
      type: object
      required: [id]
      properties:
        id:
          type: string
          description: "Skyscanner itinerary id"
        price:
          type: number
          description: "Price of the cheapest booking option, the total for all passengers in the currency searched"
        legs:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
          description: "Legs of the trip, in the order travelled"
        booking_options:
          type: array
          items:
            $ref: '#/components/schemas/BookingOption'
          description: "Sellers that offer the itinerary, each with its price and booking link"
    Leg:
      type: object
      required: [total_duration, stops]
      properties:
        departure_airport:
          $ref: '#/components/schemas/Airport'
        arrival_airport:
          $ref: '#/components/schemas/Airport'
        total_duration:
          type: integer
          description: "Time from departure to arrival in minutes"
        stops:
          type: integer
          description: "Number of stops"
        flights:
          type: array
          items:
            $ref: '#/components/schemas/Flight'
          description: "Flights of the leg in order"
    Flight:
      type: object
      required: [duration, flight_number]
      properties:
        departure_airport:
          $ref: '#/components/schemas/Airport'
        arrival_airport:
          $ref: '#/components/schemas/Airport'
        duration:
          type: integer
          description: "Flight time in minutes"
        airline:
          type: string
          description: "Airline that sells the flight"
        airline_code:
          type: string
          description: "Code Skyscanner shows for the airline that sells the flight, usually its IATA code"
        flight_number:
          type: string
          description: "Flight number with the airline code, such as EK 3"
        operating_airline:
          type: string
          description: "Airline that operates the flight"
        aircraft:
          type: string
          description: "Aircraft type with its size, such as A380 (jumbo)"
        extensions:
          type: array
          items:
            type: string
          description: "Seat layout, seat pitch and onboard services, such as 3-4-3 seat layout or Power & USB outlets"
    Airport:
      type: object
      required: [id, name, country]
      properties:
        id:
          type: string
          description: "IATA code of the airport"
        name:
          type: string
          description: "Airport name"
        city:
          type: string
          description: "City the airport serves"
        country:
          type: string
          description: "Country of the airport"
        date:
          type: string
          format: date
          description: "Local date of departure or arrival, in YYYY-MM-DD format"
        time:
          type: string
          description: "Local time of departure or arrival, in 24-hour HH:MM format"
    BookingOption:
      type: object
      properties:
        book_with:
          type: string
          description: "Seller of the option, an airline or a travel agency, or the sellers of its two tickets"
        price:
          type: number
          description: "Price of the option, the total for all passengers in the currency searched"
        fare_type:
          type: string
          description: "Name of the fare, such as Light, Eco Flex or Business Class"
        baggage:
          $ref: '#/components/schemas/Baggage'
        changes:
          type: string
          enum: [included, for fee, not included]
          description: "Whether changes to the booking are included in the fare, available for a fee, or not included"
        cancellation:
          type: string
          enum: [included, for fee, not included]
          description: "Whether cancellation is included in the fare, available for a fee, or not included"
        tracking_link:
          type: string
          description: "Skyscanner link that sends the traveller on to book with the seller"
        is_airline:
          type: boolean
          description: "Whether the seller is the airline"
        rating:
          type: number
          description: "Skyscanner rating of the seller, out of 5"
        reviews:
          type: integer
          description: "Number of Skyscanner reviews behind the rating"
        is_split_booking:
          type: boolean
          description: "Whether the option is two tickets, one for each leg, each booked with its own seller"
        departure:
          allOf:
            - $ref: '#/components/schemas/BookingOption'
          description: "Ticket for the first leg, with its seller, price and booking link"
        arrival:
          allOf:
            - $ref: '#/components/schemas/BookingOption'
          description: "Ticket for the second leg, with its seller, price and booking link"
    Baggage:
      type: object
      description: "Carry-on and checked bags of the fare"
      properties:
        carry_on_bag:
          type: string
          enum: [included, for fee, not included]
          description: "Whether a carry-on bag is included in the price, available for a fee, or not included"
        carry_on_bags_per_passenger:
          type: integer
          description: "Number of carry-on bags the price includes for each passenger"
        carry_on_bag_fee:
          type: number
          description: "Price of the carry-on bag for one passenger, in the currency searched"
        checked_bag:
          type: string
          enum: [included, for fee, not included]
          description: "Whether a checked bag is included in the price, available for a fee, or not included"
        checked_bags_per_passenger:
          type: integer
          description: "Number of checked bags the price includes for each passenger"
        checked_bag_fee:
          type: number
          description: "Price of the checked bag for one passenger, in the currency searched"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
