openapi: 3.0.0
info:
  title: Skyscanner Flights API
  description: |
    Search Skyscanner flights between two airports or cities, one-way or round trip.

    Each itinerary carries its price for all passengers, its legs with their flights, and the sellers that offer it with their prices and booking links. An option sold as two tickets, one for each direction, has `is_split_booking`, with each ticket under `departure` and `arrival`. Itineraries come in Skyscanner's order, and a search returns every itinerary Skyscanner finds. Prices are in US dollars.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Skyscanner Flights Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `skyscanner_flights`'
          schema:
            type: string
            enum: ["skyscanner_flights"]
        - name: departure_id
          in: query
          required: true
          description: IATA code of the departure airport, such as `JFK`, or of a city, such as `NYC` for every New York airport. A code that a city shares with one of its airports, such as `HOU`, means that airport. A code Skyscanner does not know returns an error.
          schema:
            type: string
            pattern: '^[A-Za-z]{3}$'
        - name: arrival_id
          in: query
          required: true
          description: IATA code of the arrival airport, such as `LAX`, or of a city, such as `LON` for every London airport. A code that a city shares with one of its airports, such as `HOU`, means that airport. A code Skyscanner does not know returns an error. Must differ from `departure_id`. Two places in the same city, such as `NYC` and `JFK` or `JFK` and `LGA`, return an error.
          schema:
            type: string
            pattern: '^[A-Za-z]{3}$'
        - name: outbound_date
          in: query
          required: true
          description: Departure date in YYYY-MM-DD format, from today up to 13 months ahead. Today means today at the departure airport, so a date already past there returns an error.
          schema:
            type: string
            format: date
        - name: return_date
          in: query
          required: false
          description: Return date in YYYY-MM-DD format, on or after `outbound_date` and up to 13 months ahead. Required when `flight_type` is `round_trip`, and not accepted for `one_way`.
          schema:
            type: string
            format: date
        - name: flight_type
          in: query
          required: false
          description: Type of trip.
          schema:
            type: string
            enum: ["one_way", "round_trip"]
            default: "round_trip"
        - name: adults
          in: query
          required: false
          description: Number of adult passengers, from 1 to 8. A search without it is for one adult.
          schema:
            type: integer
            minimum: 1
            maximum: 8
      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'
        itineraries:
          type: array
          items:
            $ref: '#/components/schemas/Itinerary'
          description: "Itineraries for the search, in Skyscanner's order"
        error:
          type: string
          description: "Error message describing what went wrong"
    SearchMetadata:
      type: object
      required: [id, 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 results page for this search"
        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"
        departure_id:
          type: string
          description: "Departure airport or city code searched"
        arrival_id:
          type: string
          description: "Arrival airport or city code searched"
        outbound_date:
          type: string
          description: "Departure date searched"
        return_date:
          type: string
          description: "Return date searched"
        flight_type:
          type: string
          description: "Type of trip searched"
        adults:
          type: string
          description: "Number of adult passengers searched"
    Itinerary:
      type: object
      required: [id]
      properties:
        id:
          type: string
          description: "Skyscanner itinerary id"
        price:
          type: number
          description: "Lowest price for the itinerary, the total for all passengers in US dollars"
        legs:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
          description: "Legs of the trip, the outbound leg first"
        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"
        airline_logo:
          type: string
          description: "Logo of the airline that sells the flight"
        flight_number:
          type: string
          description: "Flight number with the airline code, such as AA 33"
        operating_airline:
          type: string
          description: "Airline that operates the flight"
    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 US dollars"
        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 direction, each booked with its own seller"
        departure:
          $ref: '#/components/schemas/BookingOption'
          description: "Ticket for the outbound leg, with its seller, price and booking link"
        arrival:
          $ref: '#/components/schemas/BookingOption'
          description: "Ticket for the return leg, with its seller, price and booking link"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong