openapi: 3.0.0
info:
  title: Kayak Flights API
  description: |
    Search flights on Kayak, one way or round trip, with cabin, passengers, stops, airline filters, sorting and pages.
    Each itinerary returns its legs, its flights and the booking options Kayak lists for it, with each option's price for all passengers.

    **Cross-linking**: For Google Flights or Skyscanner prices on the same route, use the Google Flights API or the Skyscanner Flights API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Kayak Flights Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine used to retrieve the results.
          schema:
            type: string
            enum: ["kayak_flights"]
        - name: departure_id
          in: query
          required: true
          description: IATA code of the departure airport or city, for example JFK or NYC.
          schema:
            type: string
            pattern: '^\s*[A-Za-z]{3}\s*$'
        - name: arrival_id
          in: query
          required: true
          description: IATA code of the arrival airport or city, for example LAX or LON, different from departure_id.
          schema:
            type: string
            pattern: '^\s*[A-Za-z]{3}\s*$'
        - name: outbound_date
          in: query
          required: true
          description: 'Departure date, from today up to 365 days ahead. Format: YYYY-MM-DD'
          schema:
            type: string
            format: date
        - name: return_date
          in: query
          required: false
          description: 'Return date of a round trip, on or after outbound_date and up to 365 days ahead. Format: YYYY-MM-DD'
          schema:
            type: string
            format: date
        - name: flight_type
          in: query
          required: false
          description: Type of trip, where a round trip needs return_date.
          schema:
            type: string
            enum: ["round_trip", "one_way"]
            default: "round_trip"
        - name: travel_class
          in: query
          required: false
          description: Cabin to search.
          schema:
            type: string
            enum: ["economy", "premium_economy", "business", "first_class"]
            default: "economy"
        - name: adults
          in: query
          required: false
          description: Number of adult passengers.
          schema:
            type: integer
            minimum: 1
            maximum: 9
            default: 1
        - name: children_ages
          in: query
          required: false
          description: Comma-separated ages of child passengers from 0 to 17, where ages 0 and 1 travel on an adult's lap.
          schema:
            type: string
            pattern: '^\s*\d{1,2}\s*(,\s*\d{1,2}\s*)*$'
        - name: sort_by
          in: query
          required: false
          description: Order of the itineraries.
          schema:
            type: string
            enum: ["best", "price", "duration", "departure_time", "arrival_time"]
            default: "best"
        - name: stops
          in: query
          required: false
          description: Most stops per leg.
          schema:
            type: string
            enum: ["any", "nonstop", "one_stop_or_fewer"]
            default: "any"
        - name: included_airlines
          in: query
          required: false
          description: Comma-separated two-character airline codes whose itineraries are kept, not combined with excluded_airlines.
          schema:
            type: string
            pattern: '^\s*[A-Za-z0-9]{2}\s*(,\s*[A-Za-z0-9]{2}\s*)*$'
        - name: excluded_airlines
          in: query
          required: false
          description: Comma-separated two-character airline codes whose itineraries are dropped, not combined with included_airlines.
          schema:
            type: string
            pattern: '^\s*[A-Za-z0-9]{2}\s*(,\s*[A-Za-z0-9]{2}\s*)*$'
        - name: page
          in: query
          required: false
          description: Page of results, with 50 itineraries per page.
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 1
      responses:
        '200':
          description: Successful response. A search Kayak answers without flights carries an error.
          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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        itineraries:
          type: array
          description: Itineraries on the requested page, in Kayak's order.
          items:
            $ref: '#/components/schemas/Itinerary'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search has no itineraries.
    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: "Kayak URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      required: [engine, departure_id, arrival_id, outbound_date]
      properties:
        engine:
          type: string
          description: Engine used for the search.
        departure_id:
          type: string
          description: Departure airport or city code.
        arrival_id:
          type: string
          description: Arrival airport or city code.
        outbound_date:
          type: string
          description: Departure date.
        return_date:
          type: string
          description: Return date of a round trip.
        flight_type:
          type: string
          description: Type of trip.
        travel_class:
          type: string
          description: Cabin searched.
        adults:
          type: integer
          description: Number of adult passengers.
        children_ages:
          type: string
          description: Ages of child passengers.
        sort_by:
          type: string
          description: Order of the itineraries.
        stops:
          type: string
          description: Most stops per leg.
        included_airlines:
          type: string
          description: Airline codes whose itineraries are kept.
        excluded_airlines:
          type: string
          description: Airline codes whose itineraries are dropped.
        page:
          type: integer
          description: Page of results.
    Itinerary:
      type: object
      required: [id, price, is_best, is_cheapest, legs, booking_options]
      properties:
        id:
          type: string
          description: Kayak's identifier for the itinerary.
        price:
          type: number
          description: Lowest booking option price for all passengers.
        is_best:
          type: boolean
          description: Whether Kayak marks the itinerary as the best one.
        is_cheapest:
          type: boolean
          description: Whether Kayak marks the itinerary as the cheapest one.
        legs:
          type: array
          description: Legs of the trip, one per direction.
          items:
            $ref: '#/components/schemas/Leg'
        booking_options:
          type: array
          description: Sites selling the itinerary with their prices.
          items:
            $ref: '#/components/schemas/BookingOption'
    Leg:
      type: object
      required: [departure_airport, arrival_airport, total_duration, stops, flights]
      properties:
        departure_airport:
          $ref: '#/components/schemas/Airport'
        arrival_airport:
          $ref: '#/components/schemas/Airport'
        total_duration:
          type: integer
          description: Duration of the leg in minutes, including layovers.
        stops:
          type: integer
          description: Number of stops on the leg.
        flights:
          type: array
          description: Flights of the leg in order.
          items:
            $ref: '#/components/schemas/Flight'
    Flight:
      type: object
      required: [departure_airport, arrival_airport, duration, airline, airline_code, flight_number]
      properties:
        departure_airport:
          $ref: '#/components/schemas/Airport'
        arrival_airport:
          $ref: '#/components/schemas/Airport'
        duration:
          type: integer
          description: Duration of the flight in minutes.
        airline:
          type: string
          description: Name of the marketing airline.
        airline_code:
          type: string
          description: Two-character code of the marketing airline.
        airline_logo:
          type: string
          description: URL of the airline's logo.
        flight_number:
          type: string
          description: Airline code and flight number.
        operating_airline:
          type: string
          description: Airline operating the flight for the marketing airline.
        aircraft:
          type: string
          description: Aircraft type.
    Airport:
      type: object
      required: [id, date, time]
      properties:
        id:
          type: string
          description: IATA code of the airport.
        name:
          type: string
          description: Name of the airport.
        city:
          type: string
          description: City the airport serves.
        date:
          type: string
          description: 'Local date. Format: YYYY-MM-DD'
        time:
          type: string
          description: 'Local time. Format: HH:MM'
    BookingOption:
      type: object
      required: [book_with, price, currency, tracking_link, is_free_cancellation]
      properties:
        book_with:
          type: string
          description: Site selling the itinerary.
        price:
          type: number
          description: Price for all passengers.
        currency:
          type: string
          description: Currency of the price.
        tracking_link:
          type: string
          description: Kayak link that sends the traveller on to book the itinerary with this site.
        is_free_cancellation:
          type: boolean
          description: Whether the fare can be cancelled for free.
        checked_bag:
          type: string
          description: Checked bag allowance or fee as Kayak shows it.
        carry_on_bag:
          type: string
          description: Carry-on bag allowance as Kayak shows it.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page.
        total_pages:
          type: integer
          description: Number of pages of results.
        next:
          type: integer
          description: Next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong