sondehub-infra/swagger.yaml

504 lines
16 KiB
YAML
Raw Normal View History

2021-04-04 10:29:32 +00:00
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:
/sondes/telemetry:
put:
2021-04-04 11:25:27 +00:00
summary: Upload Radiosonde Telemetry to Sondehub database.
2021-04-04 10:29:32 +00:00
consumes:
- "application/json"
produces:
- "text/plain"
parameters:
- in: header
name: Date
2021-04-04 11:25:27 +00:00
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.
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
description: Telemetry Saved into Database Successfuly
500:
description: Other Server error (including malformed data submissions)
2021-04-04 10:29:32 +00:00
get:
2021-04-04 11:25:27 +00:00
summary: Request Radiosonde Telemetry Data
2021-04-04 10:29:32 +00:00
description: >
2021-04-04 11:25:27 +00:00
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.
2021-04-04 10:29:32 +00:00
produces:
- "application/json"
parameters:
- in: query
name: duration
2021-04-04 11:25:27 +00:00
description: How far back in time to receive data from. A shorter time period will result is higher time resolution data.
2021-04-04 10:29:32 +00:00
required: false
type: string
enum:
- "3h"
- "6h"
- "1d"
- "3d"
- in: query
name: serial
2021-04-04 11:25:27 +00:00
description: Specific serial number to query (if wanted). Requests for data for a single sonde will return the highest time resolution data available.
2021-04-04 10:29:32 +00:00
required: false
type: string
- in: query
name: datetime
2021-04-04 11:25:27 +00:00
description: "End time to query as an ISO-8601 time string. Defaults to now. Example: `2021-02-02T11:27:38.634Z`"
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
summary: Gets latest sonde data indexed by serial number, with option for position/distance based-filtering.
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
summary: Request telemetry data for an individual radiosonde
2021-04-04 10:29:32 +00:00
description: >
2021-04-04 11:25:27 +00:00
Use this to request all available telemetry data for an individual radiosonde, specified by serial number.
2021-04-04 10:29:32 +00:00
produces:
- "application/json"
parameters:
- in: path
name: serial
2021-04-04 11:25:27 +00:00
description: Serial number of the radiosonde to request data for.
2021-04-04 10:29:32 +00:00
required: true
type: string
responses:
200:
2021-04-04 11:25:27 +00:00
description: Returns a list of SondeHub Telemetry values. If no data for the requested serial number is available, the list will be empty.
2021-04-04 10:29:32 +00:00
schema:
type: array
items:
$ref: "#/definitions/telemetry_format"
/listeners:
get:
deprecated: true
2021-04-04 11:25:27 +00:00
summary: Requests a list of stations that have reported to Sondehub in the last 3 days. Used as a legacy endpoint for tracker.sondehub.org
2021-04-04 10:29:32 +00:00
produces:
- "application/json"
responses:
200:
description: List of stations receiving radiosonde data
schema:
type: array
description: Returns an array of objects containing listener data.
items:
type: object
properties:
name:
type: string
description: Callsign of the station listening
tdiff_hours:
type: number
description: Number of hours since the station was last heard from
lon:
type: number
format: double
description: Longitude of the station
lat:
type: number
format: double
description: Latitude of the station
alt:
type: number
description: number of meters above sealevel
description:
description: text description of the station
type: string
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:
2021-04-04 11:25:27 +00:00
description: Station Position successfully uploaded.
2021-04-04 10:29:32 +00:00
/sondes/websocket:
get:
2021-04-04 11:25:27 +00:00
description: Gets a presigned URL for use in connecting to the MQTT websocket endpoint.
2021-04-04 10:29:32 +00:00
produces:
- "text/plain"
responses:
200:
2021-04-04 11:25:27 +00:00
description: A presigned URL for connecting to the websocket MQTT feed.
2021-04-04 10:29:32 +00:00
/predictions:
get:
deprecated: true
2021-04-04 11:25:27 +00:00
description: Radiosonde landing predictions
2021-04-04 10:29:32 +00:00
produces:
- "application/json"
parameters:
- in: query
name: vehicles
type: string
2021-04-04 11:25:27 +00:00
description: If provided, filters predictions to a single provided serial number. Should be provided, but left blank if no filtering is required.
2021-04-04 10:29:32 +00:00
responses:
200:
description: Prediction results
schema:
$ref: "#/definitions/predictions"
/datanew:
get:
deprecated: true
2021-04-04 11:25:27 +00:00
description: "Legacy endpoint required by the sondehub tracker."
2021-04-04 10:29:32 +00:00
parameters:
- in: query
name: type
type: string
enum:
- positions
required: true
- in: query
name: max_positions
type: number
- in: query
name: mode
type: string
2021-04-04 11:25:27 +00:00
description: Duration to query
2021-04-04 10:29:32 +00:00
enum:
- "3days"
- "1day"
- "12hours"
- "6hours"
- "3hours"
- "1hour"
- in: query
name: vehicles
type: string
2021-04-04 11:25:27 +00:00
description: "Filter by serial. Currently only supports either none, or a single serial number"
2021-04-04 10:29:32 +00:00
- in: query
name: position_id
type: string
format: date-time
responses:
200:
2021-04-04 11:25:27 +00:00
description: Results compatible with sondehub mobile-tracker.
2021-04-04 10:29:32 +00:00
schema:
type: object
properties:
positions:
type: object
properties:
position:
type: array
items:
type: object
parameters:
input_payloads:
in: body
required: true
name: body
schema:
2021-04-04 11:25:27 +00:00
description: SondeHub telemetry format
2021-04-04 10:29:32 +00:00
items:
$ref: "#/definitions/telemetry_format"
definitions:
sonde_query_results_format:
type: object
properties:
serial:
type: object
properties:
datetime:
$ref: "#/definitions/telemetry_format"
telemetry_format:
2021-04-04 11:25:27 +00:00
description: SondeHub telemetry format
2021-04-04 10:29:32 +00:00
type: "object"
required:
- software_name
- software_version
- uploader_callsign
- time_received
- manufacturer
- type
- serial
- frame
- datetime
- lat
- lon
- alt
properties:
software_name:
description: >
Name of the decoding software
2021-04-04 11:25:27 +00:00
e.g. 'radiosonde_auto_rx', 'dxlAPRS', 'RS41Tracker', 'mySondy'
2021-04-04 10:29:32 +00:00
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"
2021-04-04 11:25:27 +00:00
description: "Radiosonde Manufacturer, as determined from the transmit modulation and high-level packet format."
2021-04-04 10:29:32 +00:00
enum:
- Vaisala
- Graw
- Meteomodem
- Intermet Systems
- Lockheed Martin
- Meteo-Radiy
type:
type: "string"
2021-04-04 11:25:27 +00:00
description: "The high-level radiosonde model, as can be determined just from the transmit modulation and high-level packet format."
2021-04-04 10:29:32 +00:00
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: >
2021-04-04 11:25:27 +00:00
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.
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
description: Detailed Radiosonde Model Type, as determined through analysis of the telemetry.
2021-04-04 10:29:32 +00:00
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
2021-04-04 11:25:27 +00:00
description: Station position, as a list [lat, lon, alt].
2021-04-04 10:29:32 +00:00
uploader_antenna:
type: string
2021-04-04 11:25:27 +00:00
description: Station antenna/receiver information, free-text string.
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
description: "Station callsign, # e.g. CHANGEME_AUTO_RX"
2021-04-04 10:29:32 +00:00
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:
2021-04-04 11:25:27 +00:00
description: "Optional contact e-mail, to assist SondeHub admins in resolving faults. e.g. user_contact_email@host.com"
2021-04-04 10:29:32 +00:00
type: "string"
mobile:
type: boolean
description: "Set to true to appear as a chase-car on the tracker map."
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"