openapi: 3.0.4
info:
  title: AeroDataBox API - Aviation and Flight Aircraft API Miscellaneous API API
  description: Affordable aviation & flight data API tailored for small and medium businesses, teams and individual developers.
  termsOfService: https://aerodatabox.com/terms/
  contact:
    url: https://aerodatabox.com/contact/
  version: 1.14.0.0
servers:
- url: https://prod.api.market/api/v1/aedbx/aerodatabox
security: {}
tags:
- name: Miscellaneous API
paths:
  /airports/{codeType}/{code}/time/local:
    parameters:
    - description: API.market API Key
      in: header
      name: x-api-market-key
      value: Please Login/Signup to get an API Key
      required: true
      schema:
        type: string
    get:
      tags:
      - Miscellaneous API
      summary: AeroDataBox Current Local Time at the Airport / TIER 1
      description: "**What is the current local time at the airport?**\r\n\r\nAt the moment airports having both ICAO and IATA code are present in database only.\r\n\r\n*Returns:* Local time at the airport, if airport is found."
      operationId: GetAirportLocalTime
      parameters:
      - name: codeType
        in: path
        description: Type of code to search airport by (`iata` or `icao`)
        schema:
          $ref: '#/components/schemas/AirportCodesByEnum'
      - name: code
        in: path
        description: "If `codeType` is:\r\n* `icao`, then this field must be a 4-character ICAO-code of the airport (e.g.: EHAM, KLAX, UUEE, etc.);\r\n* `iata`, then this field must be a 3-character IATA-code of the airport (e.g.: AMS, SFO, LAX, etc.).\r\n\r\nFull, stripped and any case formats are acceptable."
        required: true
        schema:
          maxLength: 4
          minLength: 3
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportLocalTimeContract'
              examples:
                GetAirportLocalTime200Example:
                  summary: Default GetAirportLocalTime 200 response
                  x-microcks-default: true
                  value:
                    time: example_value
                    timeZoneId: abc123
            application/xml:
              schema:
                $ref: '#/components/schemas/AirportLocalTimeContract'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportLocalTime400Example:
                  summary: Default GetAirportLocalTime 400 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportLocalTime401Example:
                  summary: Default GetAirportLocalTime 401 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportLocalTime451Example:
                  summary: Default GetAirportLocalTime 451 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportLocalTime500Example:
                  summary: Default GetAirportLocalTime 500 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '503':
          description: Service Unavailable
      x-badges:
      - name: TIER 1
        position: before
        color: '#beffe6'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /airports/{codeType}/{code}/time/solar:
    parameters:
    - description: API.market API Key
      in: header
      name: x-api-market-key
      value: Please Login/Signup to get an API Key
      required: true
      schema:
        type: string
    get:
      tags:
      - Miscellaneous API
      summary: AeroDataBox Solar and Day Time at the Airport / TIER 1
      description: "**What is the sun position in the sky now at a specific time at the airport?** or\r\n**When does the sun rise and set at the airport today or on the other day at the airport?** or\r\n**Is it dark now or is it day at the airport?**\r\n\r\nAt the moment airports having both ICAO and IATA code are present in database only.\r\n\r\n*Returns:* If airport is found, returns various solar-related information: sun position in the sky,\r\ndaytime (day, night, twilight: civil, nautical, astronomical, golden/blue hours), \r\nsunrise and sunset times, etc."
      operationId: GetAirportSolarTime_SolarTimeCurrent
      parameters:
      - name: codeType
        in: path
        description: Type of code to search airport by (`iata` or `icao`)
        schema:
          $ref: '#/components/schemas/AirportCodesByEnum'
      - name: code
        in: path
        description: "If `codeType` is:\r\n* `icao`, then this field must be a 4-character ICAO-code of the airport (e.g.: EHAM, KLAX, UUEE, etc.);\r\n* `iata`, then this field must be a 3-character IATA-code of the airport (e.g.: AMS, SFO, LAX, etc.).\r\n\r\nFull, stripped and any case formats are acceptable."
        required: true
        schema:
          maxLength: 4
          minLength: 3
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolarStateContract'
              examples:
                GetAirportSolarTime_SolarTimeCurrent200Example:
                  summary: Default GetAirportSolarTime_SolarTimeCurrent 200 response
                  x-microcks-default: true
                  value:
                    location: example_value
                    sunElevation: example_value
                    sunAzimuth: example_value
                    dayTime:
                    - example_value
                    dawnAstronomical: example_value
                    dawnNautical: example_value
                    dawnCivil: example_value
                    sunrise: example_value
                    noonTrue: example_value
                    sunset: example_value
                    duskCivil: example_value
                    duskNautical: example_value
                    duskAstronomical: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/SolarStateContract'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeCurrent400Example:
                  summary: Default GetAirportSolarTime_SolarTimeCurrent 400 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeCurrent401Example:
                  summary: Default GetAirportSolarTime_SolarTimeCurrent 401 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeCurrent451Example:
                  summary: Default GetAirportSolarTime_SolarTimeCurrent 451 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeCurrent500Example:
                  summary: Default GetAirportSolarTime_SolarTimeCurrent 500 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '503':
          description: Service Unavailable
      x-badges:
      - name: TIER 1
        position: before
        color: '#beffe6'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /airports/{codeType}/{code}/time/solar/{dateLocal}:
    parameters:
    - description: API.market API Key
      in: header
      name: x-api-market-key
      value: Please Login/Signup to get an API Key
      required: true
      schema:
        type: string
    get:
      tags:
      - Miscellaneous API
      summary: AeroDataBox Solar and Day Time at the Airport / TIER 1
      description: "**What is the sun position in the sky now at a specific time at the airport?** or\r\n**When does the sun rise and set at the airport today or on the other day at the airport?** or\r\n**Is it dark now or is it day at the airport?**\r\n\r\nAt the moment airports having both ICAO and IATA code are present in database only.\r\n\r\n*Returns:* If airport is found, returns various solar-related information: sun position in the sky,\r\ndaytime (day, night, twilight: civil, nautical, astronomical, golden/blue hours), \r\nsunrise and sunset times, etc."
      operationId: GetAirportSolarTime_SolarTimeSpecificDate
      parameters:
      - name: codeType
        in: path
        description: Type of code to search airport by (`iata` or `icao`)
        schema:
          $ref: '#/components/schemas/AirportCodesByEnum'
      - name: code
        in: path
        description: "If `codeType` is:\r\n* `icao`, then this field must be a 4-character ICAO-code of the airport (e.g.: EHAM, KLAX, UUEE, etc.);\r\n* `iata`, then this field must be a 3-character IATA-code of the airport (e.g.: AMS, SFO, LAX, etc.).\r\n\r\nFull, stripped and any case formats are acceptable."
        required: true
        schema:
          maxLength: 4
          minLength: 3
          type: string
      - name: dateLocal
        in: path
        description: "The moment of time which solar data is request for (local time, format: YYYY-MM-DDTHH:mm). \r\nDefault - current time."
        required: true
        schema:
          pattern: \d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?
          type: string
          format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolarStateContract'
              examples:
                GetAirportSolarTime_SolarTimeSpecificDate200Example:
                  summary: Default GetAirportSolarTime_SolarTimeSpecificDate 200 response
                  x-microcks-default: true
                  value:
                    location: example_value
                    sunElevation: example_value
                    sunAzimuth: example_value
                    dayTime:
                    - example_value
                    dawnAstronomical: example_value
                    dawnNautical: example_value
                    dawnCivil: example_value
                    sunrise: example_value
                    noonTrue: example_value
                    sunset: example_value
                    duskCivil: example_value
                    duskNautical: example_value
                    duskAstronomical: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/SolarStateContract'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeSpecificDate400Example:
                  summary: Default GetAirportSolarTime_SolarTimeSpecificDate 400 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeSpecificDate401Example:
                  summary: Default GetAirportSolarTime_SolarTimeSpecificDate 401 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeSpecificDate451Example:
                  summary: Default GetAirportSolarTime_SolarTimeSpecificDate 451 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportSolarTime_SolarTimeSpecificDate500Example:
                  summary: Default GetAirportSolarTime_SolarTimeSpecificDate 500 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '503':
          description: Service Unavailable
      x-badges:
      - name: TIER 1
        position: before
        color: '#beffe6'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /airports/{codeType}/{codeFrom}/distance-time/{codeTo}:
    parameters:
    - description: API.market API Key
      in: header
      name: x-api-market-key
      value: Please Login/Signup to get an API Key
      required: true
      schema:
        type: string
    get:
      tags:
      - Miscellaneous API
      summary: AeroDataBox Distance and Flight Time Between Airports / TIER 2
      description: "**What is the great circle distance between airports?** \r\n**What is approximate flight time between airports?**\r\n** What is the flight time between airports based on history of flights and/or aircraft type?** (machine-learning based)\r\n\r\nUse `flightTimeModel` = <a href=\"#model-ModelFlightTimeEnum\">ML01</a> to get more accurate results based on historical performance of flights on a specific route \r\nand aircraft type.\r\n\r\n*Returns:* Distance and approximate flight time between airports, if both airports found."
      operationId: GetAirportDistanceTime
      parameters:
      - name: codeType
        in: path
        description: Type of code to search airport by (`iata` or `icao`)
        schema:
          $ref: '#/components/schemas/AirportCodesByEnum'
      - name: codeFrom
        in: path
        description: "If `codeType` is:\r\n* `icao`, then this field must be a 4-character ICAO-code of the origin airport (e.g.: EHAM, KLAX, UUEE, etc.);\r\n* `iata`, then this field must be a 3-character IATA-code of the origin  airport (e.g.: AMS, SFO, LAX, etc.).\r\n\r\nFull, stripped and any case formats are acceptable."
        required: true
        schema:
          maxLength: 4
          minLength: 3
          type: string
      - name: codeTo
        in: path
        description: "If `codeType` is:\r\n* `icao`, then this field must be a 4-character ICAO-code of the destination airport (e.g.: EHAM, KLAX, UUEE, etc.);\r\n* `iata`, then this field must be a 3-character IATA-code of the destination  airport (e.g.: AMS, SFO, LAX, etc.);\r\n* `local`, then the format of this field is subject to specific standards of relevant national or local airport codification systems.\r\n\r\nFull, stripped and any case formats are acceptable."
        required: true
        schema:
          maxLength: 4
          minLength: 3
          type: string
      - name: aircraftName
        in: query
        description: "Aircraft type name (free text). \r\nIf specified, the aircraft type will be attempted to be taken into account to provide more accurate result."
        schema:
          type: string
      - name: flightTimeModel
        in: query
        description: "Model of calculation of the flight time. Default is <a href=\"#model-ModelFlightTimeEnum\"></a>\r\nMore advanced model(s) is available, including machine learning-based models.\r\nSee <a href=\"#model-ModelFlightTimeEnum\">ModelFlightTimeEnum</a> for details."
        schema:
          $ref: '#/components/schemas/ModelFlightTimeEnum'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDistanceTimeContract'
              examples:
                GetAirportDistanceTime200Example:
                  summary: Default GetAirportDistanceTime 200 response
                  x-microcks-default: true
                  value:
                    from: example_value
                    to: example_value
                    greatCircleDistance: example_value
                    approxFlightTime: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/AirportDistanceTimeContract'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportDistanceTime400Example:
                  summary: Default GetAirportDistanceTime 400 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportDistanceTime401Example:
                  summary: Default GetAirportDistanceTime 401 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportDistanceTime451Example:
                  summary: Default GetAirportDistanceTime 451 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorContract'
              examples:
                GetAirportDistanceTime500Example:
                  summary: Default GetAirportDistanceTime 500 response
                  x-microcks-default: true
                  value:
                    message: example_value
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorContract'
        '503':
          description: Service Unavailable
      x-badges:
      - name: TIER 2
        position: before
        color: '#aab6f8'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    DayTime:
      enum:
      - Night
      - TwilightAstronomical
      - TwilightNautical
      - TwilightCivil
      - Day
      - BlueHour
      - GoldenHour
      type: string
      description: "Daytime states<p>Possible values:</p>\r\n<ul>\r\n<li><b>0 - Night</b></li>\r\n<li><b>1 - TwilightAstronomical</b></li>\r\n<li><b>2 - TwilightNautical</b></li>\r\n<li><b>3 - TwilightCivil</b></li>\r\n<li><b>4 - Day</b></li>\r\n<li><b>5 - BlueHour</b></li>\r\n<li><b>6 - GoldenHour</b></li>\r\n</ul>\r\n"
    ErrorContract:
      required:
      - message
      type: object
      properties:
        message:
          minLength: 1
          type: string
          description: Error message
      additionalProperties: false
      description: Error response
    AirportCodesByEnum:
      enum:
      - Icao
      - Iata
      type: string
      description: "Search by airport code type<p>Possible values:</p>\r\n<ul>\r\n<li><b>0 - Icao</b>: ICAO-code</li>\r\n<li><b>1 - Iata</b>: IATA-code</li>\r\n</ul>\r\n"
    AirportLocalTimeContract:
      required:
      - time
      - timeZoneId
      type: object
      properties:
        time:
          $ref: '#/components/schemas/DateTimeContract'
        timeZoneId:
          minLength: 1
          type: string
          description: Timezone ID of the airport (Olson format)
      additionalProperties: false
      description: Information about the local time at an airport
    ListingAirportContract:
      required:
      - name
      type: object
      properties:
        icao:
          type: string
          description: ICAO code of the airport
          nullable: true
        iata:
          type: string
          description: IATA code of the airport
          nullable: true
        localCode:
          type: string
          description: Code of the airport within the local or national codification system
          nullable: true
        name:
          minLength: 1
          type: string
          description: Name of the airport
        shortName:
          type: string
          description: Shortened name of the airport
          nullable: true
        municipalityName:
          type: string
          description: Name of the municipality this airport belongs to
          nullable: true
        location:
          $ref: '#/components/schemas/GeoCoordinatesContract'
        countryCode:
          type: string
          description: Two-letter country code of the airport
          nullable: true
        timeZone:
          type: string
          description: Time zone of the airport in Olson format (e.g. "Europe/Amsterdam")
          nullable: true
      additionalProperties: false
      description: Flight's airport reference contract
    GeoCoordinatesContract:
      required:
      - lat
      - lon
      type: object
      properties:
        lat:
          maximum: 90
          minimum: -90
          type: number
          description: Latitude, in degrees
          format: float
        lon:
          maximum: 180
          minimum: -180
          type: number
          description: Longitude, in degrees
          format: float
      additionalProperties: false
      description: Geographical coordinates data
    Angle:
      required:
      - deg
      - rad
      type: object
      properties:
        deg:
          maximum: 180
          minimum: -180
          type: number
          description: Angle in degrees (between `-180` and `180`)
          format: double
        rad:
          maximum: 3.141592653589793
          minimum: -3.141592653589793
          type: number
          description: Angle in radians (between `-Pi` and `Pi`)
          format: double
      additionalProperties: false
    DateTimeContract:
      required:
      - local
      - utc
      type: object
      properties:
        utc:
          type: string
          description: UTC-time
          format: date-time
        local:
          type: string
          description: Local time
          format: date-time
      additionalProperties: false
      description: Descriptor date-time represented in both UTC and local timezones
    SolarStateContract:
      required:
      - dayTime
      - location
      - sunAzimuth
      - sunElevation
      type: object
      properties:
        location:
          $ref: '#/components/schemas/GeoCoordinatesContract'
        sunElevation:
          $ref: '#/components/schemas/Angle'
        sunAzimuth:
          $ref: '#/components/schemas/Azimuth'
        dayTime:
          type: array
          items:
            $ref: '#/components/schemas/DayTime'
          description: Daytime states
        dawnAstronomical:
          $ref: '#/components/schemas/DateTimeContract'
        dawnNautical:
          $ref: '#/components/schemas/DateTimeContract'
        dawnCivil:
          $ref: '#/components/schemas/DateTimeContract'
        sunrise:
          $ref: '#/components/schemas/DateTimeContract'
        noonTrue:
          $ref: '#/components/schemas/DateTimeContract'
        sunset:
          $ref: '#/components/schemas/DateTimeContract'
        duskCivil:
          $ref: '#/components/schemas/DateTimeContract'
        duskNautical:
          $ref: '#/components/schemas/DateTimeContract'
        duskAstronomical:
          $ref: '#/components/schemas/DateTimeContract'
      additionalProperties: false
      description: Solar information at the moment
    Distance:
      required:
      - feet
      - km
      - meter
      - mile
      - nm
      type: object
      properties:
        meter:
          type: number
          description: Distance in meters
          format: double
        km:
          type: number
          description: Distance in kilometers
          format: double
        mile:
          type: number
          description: Distance in statute miles
          format: double
        nm:
          type: number
          description: Distance in nautical miles
          format: double
        feet:
          type: number
          description: Distance in feet
          format: double
      additionalProperties: false
    ModelFlightTimeEnum:
      enum:
      - Standard
      - ML01
      type: string
      description: "Models of calculating the flight time.<p>Possible values:</p>\r\n<ul>\r\n<li><b>0 - Standard</b>: Standard model of calculation which takes into account the great circle distance and the average speed of all aircraft typically operating on those distances.</li>\r\n<li><b>1 - ML01</b>: Experimental machine learning (ML) model, which attempts to provide more accurate prediction of the flight time by taking into account the history of flights on specified route and aircraft type within the recent year. This may come in handy in case when on certain routes flights take significant detours due to extended airspace closures dictated by war conflicts, sanction regulations, etc. This can result in significantly increased flight times comparing to regular estimations. Or, some routes generally experience longer delays than other routes of the same distance. This model attempts to take such factors into account and reflect it in the prediction. If a model cannot be applied due to lack of historical and/or aircraft data or prediction is too off set, it automatically fallbacks to `Standard`.</li>\r\n</ul>\r\n"
    AirportDistanceTimeContract:
      required:
      - approxFlightTime
      - from
      - greatCircleDistance
      - to
      type: object
      properties:
        from:
          $ref: '#/components/schemas/ListingAirportContract'
        to:
          $ref: '#/components/schemas/ListingAirportContract'
        greatCircleDistance:
          $ref: '#/components/schemas/Distance'
        approxFlightTime:
          type: string
          description: "Approximate flight time based on re-calculation of great circle distance\r\nagainst statistical duration average of multiple flights covered similar\r\ndistance before."
          format: date-span
      additionalProperties: false
      description: "Contract containing information on distance and approximate flight time\r\nbetween specified airports"
    Azimuth:
      required:
      - deg
      - rad
      type: object
      properties:
        deg:
          maximum: 360
          minimum: 0
          type: number
          description: Angle in degrees (between `0` and `360`)
          format: double
        rad:
          maximum: 6.283185307179586
          minimum: 0
          type: number
          description: Angle in radians (`0` and `2 * Pi`)
          format: double
      additionalProperties: false