This documentation was generated from the swagger specification of the API using the swagger-markdown tool.

Try out the API here. (Note - link currently broken, some change in swagger.io - paste https://raw.githubusercontent.com/projecthorus/sondehub-infra/main/swagger.yaml into the box at the top of the page.)

The following response codes can be expected from our PUT APIs when submitting telemetry or listener position information:

Code	Description	Client should retry
200	Data submitted OK	No
20x	Data submitted, but with some issues. Refer response for details.	No
40x	Submitted data contained errors. Refer response for details.	No
50x	Server busy	Yes, up to 5 times.

All responses contain text which details any errors that have occurred when processing submitted data. If you receive anything other than a 200 or 50x response, this response text should be displayed to your users to assist in diagnosing what the issues may be.

SondeHub v2 API

http://github.com/projecthorus/sondehub-infra

Contact information:
[email protected]

License: Creative Commons BY-SA 2.0

Sondehub Infra

Upload Radiosonde Telemetry to Sondehub amateur database.

Name	Located in	Description	Required	Schema
User-Agent	header	The software and version performing the telemetry upload, eg: autorx-1.4.1-beta5	No	string
body	body		Yes

Code	Description
200	Telemetry Saved into Database Successfuly
500	Other Server error (including malformed data submissions)

Request Amateur Radiosonde Telemetry Data

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.

Name	Located in	Description	Required	Schema
duration	query	How far back in time to receive data from. A shorter time period will result is higher time resolution data.	No	string
payload_callsign	query	Specific callsign to query (if wanted). Requests for data for a single sonde will return the highest time resolution data available.	No	string
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime

Code	Description	Schema
200	Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values	amateur_query_results_format

Request Amateur Radiosonde Telemetry Data

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.

Name	Located in	Description	Required	Schema
last	query	How far back to search in seconds. Defaults to 24hrs	No	number
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime
payload_callsign	path	Specific callsign to query (if wanted). Requests for data for a single sonde will return the highest time resolution data available.	Yes	string
format	query	Valid options are csv, kml or json	No	string (string)

Code	Description	Schema
200	Returns a list of all data received	amateur_query_full_results_format

Upload Radiosonde Telemetry to Sondehub database.

Name	Located in	Description	Required	Schema
Date	header	, :: UTC as per RFC7231. This is used to calculate receiver time offset for correcting clients that have the incorrect time.	Yes	dateTime
User-Agent	header	The software and version performing the telemetry upload, eg: autorx-1.4.1-beta5	No	string
body	body		Yes

Code	Description
200	Telemetry Saved into Database Successfuly
500	Other Server error (including malformed data submissions)

Request Radiosonde Telemetry Data

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.

Name	Located in	Description	Required	Schema
duration	query	How far back in time to receive data from. A shorter time period will result is higher time resolution data.	No	string
serial	query	Specific serial number to query (if wanted). Requests for data for a single sonde will return the highest time resolution data available.	No	string
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime

Code	Description	Schema
200	Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values	sonde_query_results_format

Request latest amateur payload data indexed by serial number, with options for position/distance based-filtering.

Name	Located in	Description	Required	Schema
lat	query	Latitude - if specified, lon and distance are required. Eg: -34.9285	No	number
lon	query	Longitude - if specified, lat and distance are required Eg: 138.6007	No	number
distance	query	Distance in meters - if specified, lat and lon are required	No	number
last	query	How far back to search in seconds. Defaults to 24hrs	No	number

Code	Description	Schema
200	Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values	amateur_telm_results_format

Request latest sonde data indexed by serial number, with options for position/distance based-filtering.

Name	Located in	Description	Required	Schema
lat	query	Latitude - if specified, lon and distance are required. Eg: -34.9285	No	number
lon	query	Longitude - if specified, lat and distance are required Eg: 138.6007	No	number
distance	query	Distance in meters - if specified, lat and lon are required	No	number
last	query	How far back to search in seconds. Defaults to 24hrs	No	number

Code	Description	Schema
200	Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values	sonde_telm_results_format

Request latest sonde data indexed by serial number based on site ID

Name	Located in	Description	Required	Schema
last	query	How far back to search in seconds. Defaults to 24hrs. Limited to 7 days	No	number
site	path	Site number of the radiosonde to request data for (see /sites endpoint)	Yes	string

Code	Description	Schema
200	Returns a dictionary keyed by serial number of a dictionary of times with SondeHub Telemetry values	sonde_telm_results_format

Request telemetry data for an individual radiosonde

Use this to request all available telemetry data for an individual radiosonde, specified by serial number.

Name	Located in	Description	Required	Schema
serial	path	Serial number of the radiosonde to request data for. e.g. S1130567	Yes	string

Code	Description	Schema
200	Returns a time-sorted array of SondeHub Telemetry objects. If no data for the requested serial number is available, the array will be empty.	[ telemetry_format ]

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

Name	Located in	Description	Required	Schema
body	body		Yes	listener

Code	Description
200	Station Position successfully uploaded.

Request Listener Telemetry Data

Use this to get the current listener (chase car / station) telemetry

Name	Located in	Description	Required	Schema
duration	query	How far back in time to receive data from. A shorter time period will result is higher time resolution data.	No	string
uploader_callsign	query	Specific callsign number to query (if wanted). Requests for data for a single uploader will return the highest time resolution data available.	No	string
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime

Code	Description	Schema
200	Returns a dictionary keyed by uploader_callsign of a dictionary of times with listener data.	listener_results_format

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

Name	Located in	Description	Required	Schema
body	body		Yes	listener

Code	Description
200	Station Position successfully uploaded.

Request Listener Telemetry Data

Use this to get the current listener (chase car / station) telemetry

Name	Located in	Description	Required	Schema
duration	query	How far back in time to receive data from. A shorter time period will result is higher time resolution data.	No	string
uploader_callsign	query	Specific callsign number to query (if wanted). Requests for data for a single uploader will return the highest time resolution data available.	No	string
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime

Code	Description	Schema
200	Returns a dictionary keyed by uploader_callsign of a dictionary of times with listener data.	listener_results_format

Basic version stats

Use this to get stats on how many users are using specific software

Code	Description	Schema
200	Returns a dictionary of softwares and versions	listener_stats

Gets a presigned URL for use in connecting to the MQTT websocket endpoint.

Code	Description
200	A presigned URL for connecting to the websocket MQTT feed.

Radiosonde landing predictions

Name	Located in	Description	Required	Schema
vehicles	query	If provided, filters predictions to a single provided serial number. Should be provided, but left blank if no filtering is required.	No	string

Code	Description	Schema
200	Prediction results	predictions

Radiosonde launch site predictions

Name	Located in	Description	Required	Schema
vehicles	query	If provided, filters predictions to a single provided serial number. Should be provided, but left blank if no filtering is required.	No	string

Code	Description	Schema
200	Prediction results	predictions

Adds a recovery object to the SondeHub database to indicate if a radiosonde was recovered

Name	Located in	Description	Required	Schema
Date	header	, :: UTC as per RFC7231. This is used to calculate receiver time offset for correcting clients that have the incorrect time.	Yes	dateTime
User-Agent	header	The software and version performing the telemetry upload, eg: autorx-1.4.1-beta5	No	string
body	body		Yes	recovery_object

Code	Description
200	Recovery logged
500	Other Server error (including malformed data submissions)

Request Recovery Data

Use this to get the recovery data

Name	Located in	Description	Required	Schema
serial	query	radiosonde serial number (or multiple serial numbers separated by a comma) to filter on. If none provided all serials will be presented.	No	string
lat	query	Latitude - if specified, lon and distance are required. Eg: -34.9285	No	number
lon	query	Longitude - if specified, lat and distance are required Eg: 138.6007	No	number
distance	query	Distance in meters - if specified, lat and lon are required	No	number
last	query	How far back to search in seconds. Defaults to 3 days. Set to 0 for all	No	number

Code	Description	Schema
200	Returns a list of recovery objects	recovery_results_format

Request Recovery Stats

Use this to get the recovery stats

Name	Located in	Description	Required	Schema
lat	query	Latitude - if specified, lon and distance are required. Eg: -34.9285	No	number
lon	query	Longitude - if specified, lat and distance are required Eg: 138.6007	No	number
distance	query	Distance in meters - if specified, lat and lon are required	No	number
duration	query	How far back to search in seconds. Defaults to foreverl	No	number
datetime	query	End time to query as an ISO-8601 time string. Defaults to now. Example: 2021-02-02T11:27:38.634Z	No	dateTime

Code	Description	Schema
200	Returns a list of recovery objects	recovery_stats

Radiosonde launch sites

Code	Description	Schema
200	Prediction results	object

Site

Name	Type	Description	Required
position	[ double ]	Lat Lng	No
station	string	Station ID number	No
station_name	string	Name of the station	No
alt	double	Altitude of the station in meters	No
times	[ string ]	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).	No
rs_types	[ string ]	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"	No
burst_altitude	double	Average burst altitude for this site. Used for predictions	No
ascent_rate	double	Typical ascent rate in m/s	No
descent_rate	double	Typical descent rate in m/s	No
burst_std	double	Standard deviation from analytics of burst	No
descent_std	double	Standard deviation from analytics of descent rate	No
burst_samples	double	Number of samples used to calculate the burst altitude	No
descent_samples	double	Number of samples used to calculate the descent rate	No

Name	Type	Description	Required
datetime	dateTime	Time that the radiosonde was recovered	No
serial	string	Serial number of the radiosonde	Yes
lat	double	Latitude (decimal degrees) of the recovery location	Yes
lon	double	Longitude (decimal degrees) of the recovery location	Yes
alt	double	Altitude (metres) of the recovery location	Yes
recovered	boolean	was this recovery attempt was successful	Yes
recovered_by	string	callsign or name of the person who recovered the sonde	Yes
description	string	Description of the recovery effort	No

Name	Type	Description	Required
total	number	Total number of serial numbers that have had at least one attempt	Yes
recovered	number	Total number of serial numbers that have been recovered	Yes
failed	number	Total number of serial numbers that have a failed recovered attempt	Yes
chaser_count	number	Total number of unique recovery names	Yes
top_chasers	object	chaser name : number of attempted recoveries	Yes

Name	Type	Description	Required
serial	object		No

Name	Type	Description	Required
serial	telemetry_format		No

Name	Type	Description	Required
serial	object		No

Name	Type	Description	Required
amateur_query_full_results_format	array

Name	Type	Description	Required
serial	object		No

Name	Type	Description	Required
serial	amateur_telemetry_format		No

Name	Type	Description	Required
recovery_results_format	array

SondeHub telemetry format

Name	Type	Description	Required
dev	string	If this field is set then the payload will not be uploaded to the database. This is useful for development and testing.	No
software_name	string	Name of the decoding software e.g. 'radiosonde_auto_rx', 'dxlAPRS', 'RS41Tracker', 'mySondy'	Yes
software_version	string	Version of the decoding software e.g. '1.4.0', '20210115'	Yes
uploader_callsign	string	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.	Yes
time_received	dateTime	The time the telemetry packet was received. UTC time in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format.	Yes
manufacturer	string	Radiosonde Manufacturer, as determined from the transmit modulation and high-level packet format. Enum: "Vaisala", "Graw", "Meteomodem", "Intermet Systems", "Lockheed Martin", "Meteo-Radiy", "Meteosis", "Meisei"	Yes
type	string	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-50", "iMet-54", "LMS6-400", "LMS6-1680", "MRZ", "MTS01", "iMS-100", "RS-11G"	Yes
serial	string	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 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.	Yes
frame	number (integer)	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.	Yes
datetime	dateTime	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.	Yes
lat	double	Latitude (decimal degrees)	Yes
lon	double	Longitude (decimal degrees)	Yes
alt	double	Altitude (metres)	Yes
subtype	string	Detailed Radiosonde Model Type, as determined through analysis of the telemetry. Enum: "RS41-SG", "RS41-SGP", "RS41-SGM", "DFM06", "DFM09", "DFM09P", "DFM17", "M10", "M20", "MRZ-H1"	No
frequency	float	Transmit frequency of the radiosonde in MHz.	No
temp	float	Measured Temperature (deg C)	No
humidity	float	Measured Relative Humidity (%)	No
vel_h	float	Horizontal Velocity (m/s)	No
vel_v	float	Horizontal Velocity (m/s)	No
pressure	float	Measured Pressure (hPa)	No
heading	float	Heading (degrees True)	No
batt	float	Battery Voltage (volts)	No
sats	number (integer)	Number of SVs used in position solution	No
xdata	string (ascii hex)	Auxiliary Data (e.g Ozone data) as a hexadecimal string.	No
snr	float	Signal-to-Noise ratio of the received signal, in dB	No
rssi	float	Received-Signal-Strength-Indication of the radiosonde signal, nominally in dBm	No
uploader_position	[ double ]	Station position, as a list [lat, lon, alt].	No
uploader_antenna	string	Station antenna/receiver information, free-text string.	No

SondeHub amateur balloon telemetry format

Name	Type	Description	Required
dev	string	If this field is set then the payload will not be uploaded to the database. This is useful for development and testing.	No
software_name	string	Name of the decoding software e.g. 'horusgui'	Yes
software_version	string	Version of the decoding software e.g. '1.4.0', '20210115'	Yes
uploader_callsign	string	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.	Yes
time_received	dateTime	The time the telemetry packet was received. UTC time in YYYY-MM-DDTHH:MM:SS.SSSSSSZ format.	Yes
payload_callsign	string	Callsign for the payload	Yes
datetime	dateTime	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.	Yes
lat	double	Latitude (decimal degrees)	Yes
lon	double	Longitude (decimal degrees)	Yes
alt	double	Altitude (metres)	Yes
frequency	float	Transmit frequency of the radiosonde in MHz.	No
temp	float	Measured Temperature (deg C)	No
humidity	float	Measured Relative Humidity (%)	No
vel_h	float	Horizontal Velocity (m/s)	No
vel_v	float	Horizontal Velocity (m/s)	No
pressure	float	Measured Pressure (hPa)	No
heading	float	Heading (degrees True)	No
batt	float	Battery Voltage (volts)	No
sats	number (integer)	Number of SVs used in position solution	No
snr	float	Signal-to-Noise ratio of the received signal, in dB	No
rssi	float	Received-Signal-Strength-Indication of the radiosonde signal, nominally in dBm	No
uploader_position	[ double ]	Station position, as a list [lat, lon, alt].	No
uploader_antenna	string	Station antenna/receiver information, free-text string.	No
telemetry_hidden	boolean	This field is usually set by the server and usually does not need to be set when uploading. This controls if the data should be shown in default dashboards and the website.	No
historical	boolean	Set this to true if uploading data in the past	No
upload_time	date-time	Set by the server to indicate the servers received time. Not not set this when uploading.	Yes

Name	Type	Description	Required
listener_stats	object

Example

{
  "radiosonde_auto_rx": {
    "telemetry_count": 500,
    "unique_callsigns": 10,
    "versions": {
      "1.5.8": {
        "telemetry_count": 25463802,
        "unique_callsigns": 327
      }
    }
  }
}

Name	Type	Description	Required
software_name	string	Software Name, # e.g. radiosonde_auto_rx	No
software_version	string	Software version number, e.g. 1.5.1	No
uploader_callsign	string	Station callsign, # e.g. CHANGEME_AUTO_RX	No
uploader_position	[ double ]	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.	No
uploader_antenna	string	Uploader's antenna description	No
uploader_contact_email	string	Optional contact e-mail, to assist SondeHub admins in resolving faults. e.g. [email protected]	No
mobile	boolean	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.	No

Name	Type	Description	Required
predictions	array