openapi: 3.1.0
info:
  title: above_me API
  description: |-
    The above_me API allows you to fetch information about aircraft for a given position based on the [Open Glider Network](http://wiki.glidernet.org/) data.
  contact:
    email: laika.schmidt@magenta.de
  license:
    name: MIT License
    url: https://opensource.org/license/mit
  version: "0.1.4"
tags:
  - name: aircaft
    description: Information about aircraft
paths:
  /status:
    get:
      tags:
        - status
      summary: Gets current API status
      description: |-
        Returns information about last status update and number of currently
        stored states. Can be helpful to check whether the backend still
        receives new states.
      operationId: getStatus
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemStatus"
  /r/{latitude}/{longitude}/{range}:
    get:
      tags:
        - aircaft
      summary: Get information about aircraft for a given position
      description: |-
        Returns information for all aircraft that appeared in the last 5 minutes
        in the range of given _latitude_ ± _range_ and _longitude_ ± _range_.
      operationId: getAircraftForPosition
      parameters:
        - name: latitude
          in: path
          description: Latitude filter
          example: 48.858222
          required: true
          schema:
            type: number
            format: float
        - name: longitude
          in: path
          description: Longitude filter
          example: 2.2945
          required: true
          schema:
            type: number
            format: float
        - name: range
          in: path
          description: Range around filter position
          example: 15.0
          required: true
          schema:
            type: number
            format: float
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AircraftStatusOverview"
        "400":
          description: Invalid parameters given
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    AircraftStatusOverview:
      required:
        - latitude
        - longitude
        - range
        - states
      type: object
      properties:
        latitude:
          type: number
          format: float
          examples: [48.858222]
          description: Equals given latitude parameter
        longitude:
          type: number
          format: float
          examples: [2.2945]
          description: Equals given longitude parameter
        range:
          type: number
          format: float
          examples: [15.0]
          description: Equals given range parameter
        states:
          type: array
          items:
            $ref: "#/components/schemas/AircraftStatus"
          description: |-
            The aircraft states that match the given parameters sorted in ascending oder by distance to given position
    AircraftStatus:
      type: object
      properties:
        aircraft:
          $ref: "#/components/schemas/Aircraft"
        position:
          $ref: "#/components/schemas/Position"
        speed:
          type:
            - integer
            - "null"
          format: int32
          examples: [132]
          description: Speed of aircraft in _km/h_
          minimum: 0
        vertical_speed:
          type:
            - number
            - "null"
          format: float
          examples: [0.32]
          description: Vertical speed of aircraft in _m/sec_
        altitude:
          type:
            - integer
            - "null"
          format: int32
          examples: [3431]
          description: Altitude of aircraft in _m_
        turn_rate:
          type:
            - number
            - "null"
          format: float
          examples: [3.5]
          descripion: Turn rate of aircaft in _turns/min_
        course:
          type:
            - integer
            - "null"
          format: int32
          examples: [152]
          description: Course of aircraft
          minimum: 0
          maximum: 360
        time_stamp:
          type: integer
          format: int64
          examples: [670932000]
          description: Unix timestamp of latest aircraft status
          minimum: 0
        distance:
          type:
            - number
          format: float
          examples: [13.121989]
          description: Distance (in km) of the aircraft to the requested postion
    Aircraft:
      type: object
      properties:
        call_sign:
          type:
            - string
            - "null"
          examples: ["G1"]
          description: Call sign of aircraft
        registration:
          type:
            - string
            - "null"
          examples: ["D-6507"]
          description: Registration of aircraft
        model:
          type:
            - string
            - "null"
          examples: ["ASK-21"]
          description: Airplane model
    Position:
      type: object
      properties:
        latitude:
          type: number
          format: float
          examples: [48.858222]
          description: Latitude
        longitude:
          type: number
          format: float
          examples: [2.2945]
          description: Longitude
    Error:
      type: string
      examples:
        [
          'Invalid URL: Cannot parse value at index 2 with value `"-50000"` to a `u32`',
        ]
    SystemStatus:
      type: object
      properties:
        count:
          type: integer
          examples: [40]
          description: Number of currently stored states
          minimum: 0
        last_status_update:
          type:
            - integer
            - "null"
          format: int64
          examples: [670932000]
          description: Unix timestamp of latest incoming state
          minimum: 0
        last_aprs_update:
          type:
            - integer
            - "null"
          format: int64
          examples: [670932000]
          description: Unix timestamp of latest incoming APRS server message
          minimum: 0