openapi: 3.0.3
servers:
  - url: "https://aviation-edge.com/v2/public/"
tags:
  - name: Flight Schedules API

paths:
  /timetable:
    get:
      tags:
        - Flight Schedules API
      description: "Flight Schedules Data"
      operationId: getFlightSchedules
      parameters:
        - $ref: "#/components/parameters/iataCodeParam"
        - $ref: "#/components/parameters/typeParam"
        - $ref: "#/components/parameters/statusParam"
        - $ref: "#/components/parameters/dep_terminalParam"
        - $ref: "#/components/parameters/dep_delayParam"
        - $ref: "#/components/parameters/dep_schTimeParam"
        - $ref: "#/components/parameters/dep_estTimeParam"
        - $ref: "#/components/parameters/dep_actTimeParam"
        - $ref: "#/components/parameters/dep_estRunwayParam"
        - $ref: "#/components/parameters/dep_actRunwayParam"
        - $ref: "#/components/parameters/arr_terminalParam"
        - $ref: "#/components/parameters/arr_delayParam"
        - $ref: "#/components/parameters/arr_schTimeParam"
        - $ref: "#/components/parameters/arr_estTimeParam"
        - $ref: "#/components/parameters/arr_actTimeParam"
        - $ref: "#/components/parameters/arr_estRunwayParam"
        - $ref: "#/components/parameters/arr_actRunwayParam"
        - $ref: "#/components/parameters/airline_nameParam"
        - $ref: "#/components/parameters/airline_iataParam"
        - $ref: "#/components/parameters/airline_icaoParam"
        - $ref: "#/components/parameters/flight_numParam"
        - $ref: "#/components/parameters/flight_iataParam"
        - $ref: "#/components/parameters/flight_icaoParam"
        - $ref: "#/components/parameters/langParam"

      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleResponse"

      security:
        - api_key: []

components:
  parameters:
    iataCodeParam:
      name: iataCode
      description: "The IATA code of the airport you'd like to request data from. <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&<b><font color=#eb9532>iataCode</b></font>=JFK&type=departure"
      in: query
      schema:
        type: string

    typeParam:
      name: type
      description: "Airport schedule type: departure or arrival <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=DXB&<b><font color=#eb9532>type</b></font>=arrival"
      required: true
      in: query
      schema:
        type: string

    statusParam:
      name: status
      description: "The status of the flight: landed, scheduled, cancelled, active, incident, diverted, redirected, unknown <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=DXB&type=arrival&<b><font color=#eb9532>status</b></font>=landed"
      in: query
      schema:
        type: string

    dep_iataCodeParam:
      name: dep_iataCode
      description: "The IATA code of the departure airport (JFK, AMS, CDG, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&type=arrival&<b><font color=#eb9532>dep_iataCode</b></font>=CDG"
      in: query
      schema:
        type: string

    dep_icaoCodeParam:
      name: dep_icaoCode
      description: "The ICAO code of the departure airport (KJFK, EHAM, LFPG, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&type=arrival&<b><font color=#eb9532>dep_icaoCode</b></font>=EHAM"
      in: query
      schema:
        type: string

    dep_terminalParam:
      name: dep_terminal
      description: "The terminal at the departure airport (1, 2, 3, 4, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&type=arrival&<b><font color=#eb9532>dep_terminal</b></font>=4"
      in: query
      schema:
        type: string

    dep_delayParam:
      name: dep_delay
      description: "The delay in minutes at departure (10, 20, 45, etc) it is not possible to set a delay range <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_delay</b></font>=7&type=arrival"
      in: query
      schema:
        type: string

    dep_schTimeParam:
      name: dep_schTime
      description: "The scheduled flight's departure in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_schTime</b></font>=2023-06-07T05:00:00.000&type=arrival"
      in: query
      schema:
        type: string

    dep_estTimeParam:
      name: dep_estTime
      description: "The estimated departure time in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_estTime</b></font>=2023-05-15T10:00:00.000&type=arrival"
      in: query
      schema:
        type: string

    dep_actTimeParam:
      name: dep_actTime
      description: "The actual flight departure time in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_actTime</b></font>=2023-05-15T10:00:00.000&type=arrival"
      in: query
      schema:
        type: string

    dep_estRunwayParam:
      name: dep_estRunway
      description: "The estimated departure time at runway in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_estRunway</b></font>=2023-05-15T10:00:00.000&type=arrival"
      in: query
      schema:
        type: string

    dep_actRunwayParam:
      name: dep_actRunway
      description: "The actual departure time at runway in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>dep_actRunway</b></font>=2023-05-15T10:00:00.000&type=arrival"
      in: query
      schema:
        type: string

    arr_iataCodeParam:
      name: arr_iataCode
      description: " The IATA code of the arrival airport (JFK, AMS, CDG, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=JFK&type=departure&<b><font color=#eb9532>arr_iataCode</b></font>=AMS"
      in: query
      schema:
        type: string

    arr_icaoCodeParam:
      name: arr_icaoCode
      description: "The ICAO code of the arrival airport (KJFK, EHAM, LFPG, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>arr_icaoCode</b></font>=LATI&type=departure"
      in: query
      schema:
        type: string

    arr_terminalParam:
      name: arr_terminal
      description: "The terminal at the arrival airport (1, 2, 3, 4, etc) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>arr_terminal</b></font>=1&type=arrival"
      in: query
      schema:
        type: string

    arr_delayParam:
      name: arr_delay
      description: "The delay in minutes at arrival (10, 20, 45, etc) it is not possible to set a delay range <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&type=departure&<b><font color=#eb9532>arr_delay</b></font>=4"
      in: query
      schema:
        type: string

    arr_schTimeParam:
      name: arr_schTime
      description: "The scheduled flight's arrival in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&type=departure&<b><font color=#eb9532>arr_schTime</b></font>=2023-06-13T10:00:00.000"
      in: query
      schema:
        type: string

    arr_estTimeParam:
      name: arr_estTime
      description: "The estimated arrival time in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=BCN&type=departure&<b><font color=#eb9532>arr_estTime</b></font>=2023-06-13T17:34:00.000"
      in: query
      schema:
        type: string

    arr_actTimeParam:
      name: arr_actTime
      description: "The actual flight arrival time in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>arr_actTime</b></font>=2023-05-15T10:00:00.000&type=departure"
      in: query
      schema:
        type: string

    arr_estRunwayParam:
      name: arr_estRunway
      description: "The estimated arrival time at runway in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&<b><font color=#eb9532>arr_estRunway</b></font>=2023-05-15T14:53:00.000&type=departure"
      in: query
      schema:
        type: string

    arr_actRunwayParam:
      name: arr_actRunway
      description: "The actual arrival time at runway in the following format: YYYY-MM-DDT00:00:00.000 For example: 2023-06-07T05:00:00.000 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=CDG&type=departure&<b><font color=#eb9532>arr_actRunway</b></font>=2023-06-15T10:10:00.000"
      in: query
      schema:
        type: string

    airline_nameParam:
      name: airline_name
      description: "The name of the airline (Air France, American Airlines, Delta Air Lines, etc) (may need air%20france, american%20airlines, delta%20air%20lines) <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&<b><font color=#eb9532>airline_name</b></font>=american%20airlines&type=arrival"
      in: query
      schema:
        type: string

    airline_iataParam:
      name: airline_iata
      description: "IATA code of an airline <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&<b><font color=#eb9532>airline_iata</b></font>=GB&type=arrival"
      in: query
      schema:
        type: string

    airline_icaoParam:
      name: airline_icao
      description: "ICAO code of an airline <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&<b><font color=#eb9532>airline_icao</b></font>=EIN&type=departure "
      in: query
      schema:
        type: string

    flight_numParam:
      name: flight_num
      description: "The flight number based on 1 to 4 digits, for example: 171 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&<b><font color=#eb9532>flight_num</b></font>=171&type=departure"
      in: query
      schema:
        type: string

    flight_iataParam:
      name: flight_iata
      description: "The flight iata number consisting of digits and letters, usually of the airline iata code. For example: AA171 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&<b><font color=#eb9532>flight_iata</b></font>=AA171&type=arrival"
      in: query
      schema:
        type: string

    flight_icaoParam:
      name: flight_icao
      description: "The flight icao number consisting of digits and letters, usually the airline icao code. For example: AAL171 <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&<b><font color=#eb9532>flight_icao</b></font>=AAL171&type=departure"
      in: query
      schema:
        type: string

    codesharedParam:
      name: codeshared
      description: "If the flight is codeshared, this data will be included. If you don't want codeshared flights, you can input null <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&<b><font color=#eb9532>codeshared</b></font>=nulls&type=arrival"
      in: query
      schema:
        type: string

    langParam:
      name: lang
      description: "Translations are available of the airport names, city names and country names to 43 different languages. See details below. <p> <i>Example:</i> https://aviation-edge.com/v2/public/timetable?key=[API_KEY]&iataCode=LHR&type=arrival&<b><font color=#eb9532>lang</b></font>=fr"
      in: query
      schema:
        type: string

  schemas:
    ScheduleResponse:
      type: object
      properties:
        airline:
          type: object
          properties:
            iataCode:
              type: string
              example: "NZ"
            icaoCode:
              type: string
              example: "ANZ"
            name:
              type: string
              example: "Air New Zealand"
        arrival:
          type: object
          properties:
            actualRunway:
              type: string
              example: "2024-06-14T23:02:00.000"
            actualTime:
              type: string
              example: "2024-06-14T23:02:00.000"
            baggage:
              type: string
              example: "C12"
            delay:
              type: string
              example: "48"
            estimatedRunway:
              type: string
              example: "2024-06-14T23:02:00.000"
            estimatedTime:
              type: string
              example: "2024-06-14T23:02:00.000"
            gate:
              type: string
              example: "35"
            iataCode:
              type: string
              example: "IAH"
            icaoCode:
              type: string
              example: "KIAH"
            scheduledTime:
              type: string
              example: "2024-06-14T22:14:00.000"
            terminal:
              type: string
              example: "C"
        codeshared:
          type: object
          properties:
            airline:
              type: object
              properties:
                iataCode:
                  type: string
                  example: "ua"
                icaoCode:
                  type: string
                  example: "ual"
                name:
                  type: string
                  example: "united airlines"
            flight:
              type: object
              properties:
                iataNumber:
                  type: string
                  example: "ua1610"
                icaoNumber:
                  type: string
                  example: "ual1610"
                number:
                  type: string
                  example: "1610"
        departure:
          type: object
          properties:
            actualRunway:
              type: string
              example: "2024-06-14T21:03:00.000"
            actualTime:
              type: string
              example: "2024-06-14T21:03:00.000"
            baggage:
              type: string
              example: "6"
            delay:
              type: string
              example: "95"
            estimatedRunway:
              type: string
              example: "2024-06-14T21:03:00.000"
            estimatedTime:
              type: string
              example: "2024-06-14T19:29:00.000"
            gate:
              type: string
              example: "27"
            iataCode:
              type: string
              example: "EWR"
            icaoCode:
              type: string
              example: "KEWR"
            scheduledTime:
              type: string
              example: "2024-06-14T19:29:00.000"
            terminal:
              type: string
              example: "A"
        flight:
          type: object
          properties:
            iataNumber:
              type: string
              example: "NZ6603"
            icaoNumber:
              type: string
              example: "ANZ6603"
            number:
              type: string
              example: "6603"
        status:
          type: string
          example: "landed"
        type:
          type: string
          example: "arrival"


  securitySchemes:
    api_key:
      type: apiKey
      name: key
      in: query
