swagger: "2.0"
info:
  description: "SondeHub v2 API"
  version: "2.0.0"
  title: "SondeHub"
  termsOfService: "http://github.com/projecthorus/sondehub-infra"
  contact:
    email: "vk3fur@sondehub.org"
  license:
    name: "Creative Commons BY-SA 2.0"
    url: "https://creativecommons.org/licenses/by-sa/2.0/"
host: "api.v2.sondehub.org"
basePath: "/"
schemes:
- "https"
paths:
  /amateur/telemetry:
    put:
      summary: Upload Radiosonde Telemetry to Sondehub amateur database.
      consumes:
        - "application/json"
      produces:
        - "text/plain"
      parameters:
        - in: header
          name: User-Agent
          type: string
          description: "The software and version performing the telemetry upload, eg:  `autorx-1.4.1-beta5`"
        - $ref: "#/parameters/input_amateur_payloads"
      responses:
        200:
          description: Telemetry Saved into Database Successfuly
        500:
          description: Other Server error (including malformed data submissions)
  /sondes/telemetry:
    put:
      summary: Upload Radiosonde Telemetry to Sondehub database.
      consumes:
        - "application/json"
      produces:
        - "text/plain"
      parameters:
        - in: header
          name: Date
          description: <day-name>, <day> <month> <year> <hour>:<minute>:<second> UTC as per RFC7231. This is used to calculate receiver time offset for correcting clients that have the incorrect time.
          required: true
          type: string
          format: date-time
        - in: header
          name: User-Agent
          type: string
          description: "The software and version performing the telemetry upload, eg:  `autorx-1.4.1-beta5`"
        - $ref: "#/parameters/input_payloads"
            
                
              
      responses:
        200:
          description: Telemetry Saved into Database Successfuly
        500:
          description: Other Server error (including malformed data submissions)
    get:
      summary: Request Radiosonde Telemetry Data
      description: >
        Use this to get the current state of all the radiosondes then use the realtime API to access streaming data. Do not regularly poll this endpoint, it is rate limited.
      produces:
        - "application/json"
      parameters:
        - in: query
          name: duration
          description: How far back in time to receive data from. A shorter time period will result is higher time resolution data.
          required: false
          type: string
          enum:
            - "0"
            - "15s"
            - "1m"
            - "30m"
            - "1h"
            - "3h"
            - "6h"
            - "1d"
            - "3d"
        - in: query
          name: serial
          description: Specific serial number to query (if wanted). Requests for data for a single sonde will return the highest time resolution data available.
          required: false
          type: string
        - in: query
          name: datetime
          description: "End time to query as an ISO-8601 time string. Defaults to now. Example: `2021-02-02T11:27:38.634Z`"
          required: false
          type: string
          format: date-time

      responses:
        200:
          description: Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values
          schema:
            $ref: "#/definitions/sonde_query_results_format"
  /sondes:
    get:
      summary: Request latest sonde data indexed by serial number, with options for position/distance based-filtering.
      produces:
        - "application/json"
      parameters:
        - in: query
          name: lat
          type: number
          description:  "Latitude - if specified, lon and distance are required. Eg: -34.9285"
        - in: query
          name: lon
          description: "Longitude - if specified, lat and distance are required Eg:  138.6007"
          type: number
        - in: query
          name: distance
          description: "Distance in meters - if specified, lat and lon are required"
          type: number
        - in: query
          name: last
          description: "How far back to search in seconds. Defaults to 24hrs"
          type: number
          
      responses:
        200:
          description: Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values
          schema:
            $ref: "#/definitions/sonde_query_results_format"
  /sonde/{serial}:
    get:
      summary: Request telemetry data for an individual radiosonde
      description: >
        Use this to request all available telemetry data for an individual radiosonde, specified by serial number.
      produces:
        - "application/json"
      parameters:
        - in: path
          name: serial
          description: Serial number of the radiosonde to request data for. e.g. S1130567
          required: true
          type: string
        
      responses:
        200:
          description: Returns a time-sorted array of SondeHub Telemetry objects. If no data for the requested serial number is available, the array will be empty.
          schema:
            type: array
            items:
              $ref: "#/definitions/telemetry_format" 
  /listeners:
    put:
      summary: 'Allows a station to upload their station information to the SondeHub database, for display on the SondeHub Tracker map. This endpoint can also be used to upload chase-car positions by setting the "mobile" setting to True'
      consumes:
        - "application/json"
      produces:
        - "text/plain"
      parameters:
        - in: body
          required: true
          name: body
          schema:
            $ref: "#/definitions/listener"
      responses:
        200:
          description: Station Position successfully uploaded.
  /listeners/telemetry:
    get:
      summary: Request Listener Telemetry Data
      description: >
        Use this to get the current listener (chase car / station) telemetry
      produces:
        - "application/json"
      parameters:
        - in: query
          name: duration
          description: How far back in time to receive data from. A shorter time period will result is higher time resolution data.
          required: false
          type: string
          enum:
            - "3h"
            - "6h"
            - "1d"
            - "3d"
        - in: query
          name: uploader_callsign
          description: Specific callsign number to query (if wanted). Requests for data for a single uploader will return the highest time resolution data available.
          required: false
          type: string
        - in: query
          name: datetime
          description: "End time to query as an ISO-8601 time string. Defaults to now. Example: `2021-02-02T11:27:38.634Z`"
          required: false
          type: string
          format: date-time
      responses:
        200:
          description: Returns a dictionary keyed by uploader_callsign of a dictionary of times with listener data.
          schema:
            $ref: "#/definitions/listener"
  /listeners/stats:
    get:
      summary: Basic version stats
      description: >
        Use this to get stats on how many users are using specific software
      produces:
        - "application/json"
      responses:
        200:
          description: Returns a dictionary of softwares and versions
          schema:
            $ref: "#/definitions/listener_stats"
  /sondes/websocket:
    get:
      description: Gets a presigned URL for use in connecting to the MQTT websocket endpoint.
      produces:
        - "text/plain"
      responses:
        200:
          description: A presigned URL for connecting to the websocket MQTT feed.
  /predictions:
    get:
      description: Radiosonde landing predictions
      produces:
        - "application/json"
      parameters:
        - in: query
          name: vehicles
          type: string
          description: If provided, filters predictions to a single provided serial number. Should be provided, but left blank if no filtering is required.
      responses:
        200:
          description: Prediction results
          schema:
            $ref: "#/definitions/predictions" 
  /predictions/reverse:
    get:
      description: Radiosonde launch site predictions
      produces:
        - "application/json"
      parameters:
        - in: query
          name: vehicles
          type: string
          description: If provided, filters predictions to a single provided serial number. Should be provided, but left blank if no filtering is required.
      responses:
        200:
          description: Prediction results
          schema:
            $ref: "#/definitions/predictions" 
  /recovered:
    put:
      summary: Adds a recovery object to the SondeHub database to indicate if a radiosonde was recovered
      consumes:
        - "application/json"
      produces:
        - "text/plain"
      parameters:
        - in: header
          name: Date
          description: <day-name>, <day> <month> <year> <hour>:<minute>:<second> UTC as per RFC7231. This is used to calculate receiver time offset for correcting clients that have the incorrect time.
          required: true
          type: string
          format: date-time
        - in: header
          name: User-Agent
          type: string
          description: "The software and version performing the telemetry upload, eg:  `autorx-1.4.1-beta5`"
        - in: body
          required: true
          name: body
          schema: 
            $ref: "#/definitions/recovery_object"
              
      responses:
        200:
          description: Recovery logged
        500:
          description: Other Server error (including malformed data submissions)
    get:
      summary: Request Recovery Data
      description: >
        Use this to get the recovery data 
      produces:
        - "application/json"
      parameters:
        - in: query
          name: serial
          type: string
          description: radiosonde serial number (or multiple serial numbers separated by a comma) to filter on. If none provided all serials will be presented.
        - in: query
          name: lat
          type: number
          description:  "Latitude - if specified, lon and distance are required. Eg: -34.9285"
        - in: query
          name: lon
          description: "Longitude - if specified, lat and distance are required Eg:  138.6007"
          type: number
        - in: query
          name: distance
          description: "Distance in meters - if specified, lat and lon are required"
          type: number
        - in: query
          name: last
          description: "How far back to search in seconds. Defaults to 3 days. Set to 0 for all"
          type: number

      responses:
        200:
          description: Returns a list of recovery objects
          schema:
            $ref: "#/definitions/recovery_results_format"    
  /recovered/stats:
    get:
      summary: Request Recovery Stats
      description: >
        Use this to get the recovery stats
      produces:
        - "application/json"
      parameters:
        - in: query
          name: lat
          type: number
          description:  "Latitude - if specified, lon and distance are required. Eg: -34.9285"
        - in: query
          name: lon
          description: "Longitude - if specified, lat and distance are required Eg:  138.6007"
          type: number
        - in: query
          name: distance
          description: "Distance in meters - if specified, lat and lon are required"
          type: number
        - in: query
          name: duration
          description: "How far back to search in seconds. Defaults to foreverl"
          type: number
        - in: query
          name: datetime
          description: "End time to query as an ISO-8601 time string. Defaults to now. Example: `2021-02-02T11:27:38.634Z`"
          type: string
          format: date-time
      responses:
        200:
          description: Returns a list of recovery objects
          schema:
            $ref: "#/definitions/recovery_stats"
  /sites:
    get:
      description: Radiosonde launch sites
      produces:
        - "application/json"
      responses:
        200:
          description: Prediction results
          schema:
            type: object
            additionalProperties:
              $ref: "#/definitions/site" 
            
parameters:
  input_payloads:
    in: body
    required: true
    name: body
    schema:
      description: SondeHub telemetry format
      items:
        $ref: "#/definitions/telemetry_format"
  input_amateur_payloads:
    in: body
    required: true
    name: body
    schema:
      description: SondeHub amateur telemetry format
      items:
        $ref: "#/definitions/amateur_telemetry_format"
  recovery_object:
    in: body
    required: true
    name: body
    schema: 
      description: SondeHub recovery format
      items:
        $ref: "#/definitions/recovery_object"

definitions:
  site:
    type: object
    description: "Site"
    properties:
      position:
        type: "array"
        description: Lat Lng
        items:
          type: number
          format: double
      station:
        description: Station ID number
        type: string
      station_name:
        description: Name of the station
        type: "string"
      alt:
        description: Altitude of the station in meters
        type: "number"
        format: "double"
      times:
        description: >
          A list of strings where each string represents a UTC launch schedule created in the following format:

          0:00:00 (day:hour:minute)
          When day is set to 0 it means that the following launch time occurs every day
          When day is set to 1-7 it means the following launch occurs weekly on that day (Monday - Sunday)

          Hour is expressed in 24 hour time and we stick with 3 hour windows to keep things simple so 03, 06, 09, 12, 15, 18, 21, 24

          Minutes can be any value between 0 and 60 but we always leave this value at 00 (in the tracker we subtract 45 minutes from the time to generate predictions).
        type: array
        items:
          type: string
      rs_types:
        description: >
          The radiosonde types for this site:
          Supported : "07":"iMet-1", "11":"LMS6-403", "13":"RS92", "14":"RS92", "17":"DFM-09", "18":"DFM-06", "19":"MRZ-N1", "22":"RS-11G", "23":"RS41", "24":"RS41", "34":"iMet-4", "35":"iMS-100", "41":"RS41", "42":"RS41", "52":"RS92-NGP", "54":"DFM-17", "62":"MRZ-3MK", "63":"M20", "77":"M10", "82":"LMS6-1680", "84":"iMet-54"
          Unsupported : "15":"PAZA-12M", "16":"PAZA-22", "20":"MK3", "21":"1524LA LORAN-C/GL5000", "26":"SRS-C34", "27":"AVK-MRZ", "28":"AVK–AK2-02", "29":"MARZ2-2", "30":"RS2-80", "33":"GTS1-2/GFE(L)", "45":"CF-06", "58":"AVK-BAR", "59":"M2K2-R", "68":"AVK-RZM-2", "69":"MARL-A/Vektor-M-RZM-2", "73":"MARL-A", "78":"RS90", "80":"RS92", "88":"MARL-A/Vektor-M-MRZ", "89":"MARL-A/Vektor-M-BAR", "97":"iMet-2", "99":"iMet-2"

          They can either be provided as a single list of strings containing one or more codes: "rs_types": ["41", "07"]

          If the sondes always transmit on the same known frequency this can also be provided by having each code within a nested list containing the code and frequency: "rs_types": [["41", "404.300"], ["07", "404.200"]]
        type: array
        items:
          type: string
      burst_altitude:
        description: Average burst altitude for this site. Used for predictions
        type: number
        format: "double"
      ascent_rate:
        description: Typical ascent rate in m/s
        type: number
        format: "double"
      descent_rate:
        description: Typical descent rate in m/s
        type: number
        format: "double"
      burst_std:
        description: Standard deviation from analytics of burst
        type: number
        format: "double"
      descent_std:
        description: Standard deviation from analytics of descent rate
        type: number
        format: "double"
      burst_samples:
        description: Number of samples used to calculate the burst altitude
        type: number
        format: "double"
      descent_samples:
        description: Number of samples used to calculate the descent rate
        type: number
        format: "double"
  recovery_object:
    type: object
    required:
      - serial
      - lat
      - lon
      - alt
      - recovered_by
      - recovered
    properties:
      datetime:
        type: "string"
        format: "date-time"
        description: Time that the radiosonde was recovered
      serial:
        description: Serial number of the radiosonde
        type: string
      lat:
        description: Latitude (decimal degrees) of the recovery location
        type: "number"
        format: "double"
      lon:
        description: Longitude (decimal degrees) of the recovery location
        type: "number"
        format: "double"
      alt:
        description: Altitude (metres) of the recovery location
        type: "number"
        format: "double"
      recovered:
        description: was this recovery attempt was successful
        type: boolean
      recovered_by:
        description: callsign or name of the person who recovered the sonde
        type: string
      description:
        description: Description of the recovery effort
        type: string
  recovery_stats:
    type: object
    required:
      - total
      - recovered
      - failed
      - chaser_count
      - top_chasers
    properties:
      total:
        type: number
        description: Total number of serial numbers that have had at least one attempt
      recovered:
        description: Total number of serial numbers that have been recovered
        type: number
      failed:
        description: Total number of serial numbers that have a failed recovered attempt
        type: number
      chaser_count:
        description: Total number of unique recovery names
        type: number
      top_chasers:
        description: "chaser name : number of attempted recoveries"
        type: object
  sonde_query_results_format:
    type: object
    properties:
      serial:
        type: object
        properties:
          datetime: 
            $ref: "#/definitions/telemetry_format"
  recovery_results_format:
    type: array
    items:
      $ref: "#/definitions/recovery_object"
  telemetry_format:
    description: SondeHub telemetry format
    type: "object"
    required:
      - software_name
      - software_version
      - uploader_callsign
      - time_received
      - manufacturer
      - type
      - serial
      - frame
      - datetime
      - lat
      - lon
      - alt
    properties:
      dev:
        description: >
          If this field is set then the payload will not be uploaded to the database. This is useful for development and testing.
        type: "string"
      software_name:
        description: >
          Name of the decoding software
          
          e.g. 'radiosonde_auto_rx', 'dxlAPRS', 'RS41Tracker', 'mySondy'
        type: "string"
      software_version:
        description: >
          Version of the decoding software

          e.g. '1.4.0', '20210115'
        type: "string"
      uploader_callsign:
        type: "string"
        description: >
          Callsign of the uploader

          Arbitrary string. Uploader position information and other metadata will be handled separately, but will need to match this callsign to enable calculation of listener statistics.
      time_received:
        description: >
          The time the telemetry packet was received. UTC time in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format.
        type: "string"
        format: "date-time"
      manufacturer:
        type: "string"
        description: "Radiosonde Manufacturer, as determined from the transmit modulation and high-level packet format."
        enum:
          - Vaisala
          - Graw
          - Meteomodem
          - Intermet Systems
          - Lockheed Martin
          - Meteo-Radiy
      type:
        type: "string"
        description: "The high-level radiosonde model, as can be determined just from the transmit modulation and high-level packet format."
        enum:
          - RS41
          - DFM
          - M10
          - M20
          - iMet-4
          - iMet-54
          - LMS6-400
          - LMS6-1680
          - MRZ
      serial:
        type: "string"
        description: >
          Radiosonde Serial Number. Where possible this should be in the format which matches the sticker/label on the radiosonde itself

          iMet-1/iMet-4 sondes do not provide a serial number, and so auto_rx [generates](https://github.com/projecthorus/radiosonde_auto_rx/wiki/Model-Specific-Notes#intermet-imet-1--imet-4) a serial number based on launch time and transmit frequency. DFM sondes do not regularly transmit their serial number, and so data from these sondes should not be uploaded before the serial number is known.
      
      frame:
        type: "number"
        format: "integer"
        description: >
          Frame Number, ideally unique over the entire flight. Should be taken from the telemetry. For some radiosondes (DFM, M10, M20), the datetime (converted to a unix time) is used instead of the provided frame number.

      datetime:
        type: "string"
        format: "date-time"
        description: >
          Date/Time from the sonde's GPS, provided in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format

          Some sondes (e.g. iMet, LMS6) do not provide the date portion of the timestamp. In this situation, the date portion should be added on by the receiver. An example of how to handle this problem is [available here](https://github.com/projecthorus/radiosonde_auto_rx/blob/master/auto_rx/autorx/sonde_specific.py#L13).
      
      lat:
        description: Latitude (decimal degrees)
        type: "number"
        format: "double"
      lon:
        description: Longitude (decimal degrees)
        type: "number"
        format: "double"
      alt:
        description: Altitude (metres)  
        type: "number"
        format: "double"
        
      subtype:
        description: Detailed Radiosonde Model Type, as determined through analysis of the telemetry.
        type: "string"
        enum:
           - 'RS41-SG'
           - 'RS41-SGP'
           - 'RS41-SGM'
           - 'DFM06'
           - 'DFM09'
           - 'DFM09P'
           - 'DFM17'
           - 'M10'
           - 'M20'
           - 'MRZ-H1'

      frequency:
        type: "number"
        format: "float"
        description: Transmit frequency of the radiosonde in MHz.
      temp:
        type: "number"
        format: "float"
        description: Measured Temperature (deg C)  
      humidity:
        type: "number"
        format: "float"
        description: Measured Relative Humidity (%)
      vel_h:
        type: "number"
        format: "float"
        description: Horizontal Velocity (m/s)  
      vel_v:
        type: "number"
        format: "float"
        description: Horizontal Velocity (m/s)  
      pressure:
        description: Measured Pressure (hPa)  
        type: "number"
        format: "float"

      heading:
        type: "number"
        format: "float"
        description: Heading (degrees True)  
      batt:
        type: "number"
        format: "float"
        description: Battery Voltage (volts)  
      sats:
        type: "number"
        format: "integer"
        description: Number of SVs used in position solution  
      
      xdata:
        type: "string"
        format: "ascii hex"
        description: Auxiliary Data (e.g Ozone data) as a hexadecimal string.  
      
      snr:
        type: number
        format: float
        description: Signal-to-Noise ratio of the received signal, in dB  
      rssi:
        type: number
        format: float
        description: Received-Signal-Strength-Indication of the radiosonde signal, nominally in dBm  
      uploader_position:
        type: array
        items:
          type: number
          format: double
        minItems: 3
        maxItems: 3
        description: Station position, as a list [lat, lon, alt].
      uploader_antenna:
        type: string
        description: Station antenna/receiver information, free-text string.

  amateur_telemetry_format:
    description: SondeHub amateur balloon telemetry format
    type: "object"
    required:
      - software_name
      - software_version
      - uploader_callsign
      - time_received
      - payload_callsign
      - datetime
      - lat
      - lon
      - alt
      - upload_time
    properties:
      dev:
        description: >
          If this field is set then the payload will not be uploaded to the database. This is useful for development and testing.
        type: "string"
      software_name:
        description: >
          Name of the decoding software
          
          e.g. 'horusgui'
        type: "string"
      software_version:
        description: >
          Version of the decoding software

          e.g. '1.4.0', '20210115'
        type: "string"
      uploader_callsign:
        type: "string"
        description: >
          Callsign of the uploader

          Arbitrary string. Uploader position information and other metadata will be handled separately, but will need to match this callsign to enable calculation of listener statistics.
      time_received:
        description: >
          The time the telemetry packet was received. UTC time in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format.
        type: "string"
        format: "date-time"
      payload_callsign:
        type: "string"
        description: >
          Callsign for the payload

      datetime:
        type: "string"
        format: "date-time"
        description: >
          Date/Time from the sonde's GPS, provided in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format

          Some sondes (e.g. iMet, LMS6) do not provide the date portion of the timestamp. In this situation, the date portion should be added on by the receiver. An example of how to handle this problem is [available here](https://github.com/projecthorus/radiosonde_auto_rx/blob/master/auto_rx/autorx/sonde_specific.py#L13).
      
      lat:
        description: Latitude (decimal degrees)
        type: "number"
        format: "double"
      lon:
        description: Longitude (decimal degrees)
        type: "number"
        format: "double"
      alt:
        description: Altitude (metres)  
        type: "number"
        format: "double"

      frequency:
        type: "number"
        format: "float"
        description: Transmit frequency of the radiosonde in MHz.
      temp:
        type: "number"
        format: "float"
        description: Measured Temperature (deg C)  
      humidity:
        type: "number"
        format: "float"
        description: Measured Relative Humidity (%)
      vel_h:
        type: "number"
        format: "float"
        description: Horizontal Velocity (m/s)  
      vel_v:
        type: "number"
        format: "float"
        description: Horizontal Velocity (m/s)  
      pressure:
        description: Measured Pressure (hPa)  
        type: "number"
        format: "float"

      heading:
        type: "number"
        format: "float"
        description: Heading (degrees True)  
      batt:
        type: "number"
        format: "float"
        description: Battery Voltage (volts)  
      sats:
        type: "number"
        format: "integer"
        description: Number of SVs used in position solution  
      
      snr:
        type: number
        format: float
        description: Signal-to-Noise ratio of the received signal, in dB  
      rssi:
        type: number
        format: float
        description: Received-Signal-Strength-Indication of the radiosonde signal, nominally in dBm  
      uploader_position:
        type: array
        items:
          type: number
          format: double
        minItems: 3
        maxItems: 3
        description: Station position, as a list [lat, lon, alt].
      uploader_antenna:
        type: string
        description: Station antenna/receiver information, free-text string.
  listener_stats:
    type: object
    additionalProperties:
      description: softwareName
      type: object
    example:
      radiosonde_auto_rx:
        telemetry_count: 500
        unique_callsigns: 10
        versions:
          "1.5.8":  
            telemetry_count: 25463802
            unique_callsigns: 327
  listener:
    type: object
    properties:
      software_name:
        description: 'Software Name, # e.g. radiosonde_auto_rx'
        type: "string"
      software_version: 
        description: "Software version number,  e.g. 1.5.1"
        type: "string"
      uploader_callsign:
        description: "Station callsign, # e.g. CHANGEME_AUTO_RX"
        type: "string"
      uploader_position:
        description: "Station position, as a list [lat, lon, alt] Note: This may be set to null, which will result in the station position not appearing on the map."
        type: array
        items:
          type: number
          format: double
        minItems: 3
        maxItems: 3
      uploader_antenna:
        description: Uploader's antenna description
        type: "string"
      uploader_contact_email: 
        description: "Optional contact e-mail, to assist SondeHub admins in resolving faults. e.g. user_contact_email@host.com"
        type: "string"
      mobile:
        type: boolean
        description: "Indicates that the station is mobile, and should appear as a chase car on the tracker map. Set to false if this is a fixed station."
  predictions:
    type: array
    items:
      type: object
      properties: 
        vehicle:
          type: string
          description: callsign / serial of the radiosonde
        time:
          type: string
          format: date-time
        latitude: 
          type: number
        longitude:
          type: number
        altitude:
          type: number
        ascent_rate:
          type: number
        descent_rate:
          type: number
        burst_altitude:
          type: number
        landed:
          enum:
            - 1
            - 0
        data:  
          description: This is the json output from the Tāwhirimātea predictor http://tawhiri.cusf.co.uk
          type: string
      
     
externalDocs:
  description: "Sondehub Infra"
  url: "http://github.com/projecthorus/sondehub-infra"