WindBorne observations are high-frequency, at once every ten seconds, but as our balloons are comparatively slow-moving (relative to the distances at which weather changes), this may be excessive for some applications. Indeed, previous data assimilation experiments have suggested that reducing the resolution of the dataset helps with impact.
"Superobbing" averages observations in a smart way to reduce effective resolution while preserving key data attributes. Our current algorithm for superobbing the data is straightforward, having two parameters corresponding to maximum "bucket" size in altitude (a max of 100m) and in time (a max of 30 minutes).
The algorithm accumulates observations sequentially until an observation doesn't satisfy either threshold; usually the altitude threshold is triggered, but when flying in a stable-altitude mode (where the balloon might not deviate by more than tens of meters over the course of many hours) the time condition might apply. When that happens, the previous observations get averaged into a single "superobbed" observation, and a new bucket starts.
Whenever a new observation comes out for a mission, it checks whether it fits into the last superobservation bucket (ie, is less than half an hour from the start and is no more than 100m different in altitude). If the observation does fit into that superobservation bucket, it updates the superobservation. If it doesn't, it creates a new superobservation. As such, superobservations are regularly updated.
Given this, we strongly recommend passing include_ids and merging based on the ID. The super observations endpoint is identical in behavior to the normal observations endpoint, and allows fetching data via an authenticated GET request.
Fetches a single page of observations data either prints it, saves it to a file or returns it as a dictionary.
Continuously poll the Observations API to fetch new or updated data. This is useful for streaming data into your systems in near real-time.
Fetches a single page of observations data either prints it, saves it to a file or returns it as a dictionary.
Continuously poll the Observations API to fetch new or updated data. This is useful for streaming data into your systems in near real-time.
| Name | Type | Description | Format |
|---|---|---|---|
| since Optional | numeric | A unix timestamp (seconds since unix epoch) for when to start fetching data from. Note: The API will return data that is either new or has been updated since this timestamp. We recommend using this for pagination. | unix timestamp |
| min_time Optional | numeric | A unix timestamp (seconds since unix epoch) for filtering data. Note: If provided, will only return observations taken at a timestamp greater than or equal to this value. In contrast to since, which is used for pagination, this is used for filtering. | unix timestamp |
| max_time Optional | numeric | A unix timestamp (seconds since unix epoch) for filtering data. Note: If provided, will only return observations taken at a timestamp less than or equal to this value. | unix timestamp |
| include_ids Optional | boolean | If true, will include the id of the observation and the mission that collected it. | - |
| include_mission_name Optional | boolean | If true, will include the human name of the mission that collected the observation. | - |
| include_updated_at Optional | boolean | If true, will include when the observation was last updated in the database (eg from a re-processing of sensor data). | - |
| mission_id Optional | string | If set, will filter to only missions with this ID. IDs can be found via the flying missions route. | - |
| min_latitude Optional | numeric | If provided, will only return observations with a latitude greater than or equal to this value. | - |
| max_latitude Optional | numeric | If provided, will only return observations with a latitude less than or equal to this value. | - |
| min_longitude Optional | numeric | If provided, will only return observations with a longitude greater than or equal to this value. | - |
| max_longitude Optional | numeric | If provided, will only return observations with a longitude less than or equal to this value. | - |
| Name | Type | Description |
|---|---|---|
| start_time Required | string | Start time for fetching data. Note: Supports 'YYYY-MM-DD HH:MM:SS', 'YYYY-MM-DD_HH:MM', and ISO strings. |
| end_time Optional | string | End time for fetching data. Note: Supports 'YYYY-MM-DD HH:MM:SS', 'YYYY-MM-DD_HH:MM', and ISO strings. If omitted, current time is used. |
| output Required | string | Save all data to a single file rather than splitting by time and mission. Note: File formats '.csv', '.json', '.little_r', '.nc'; or use 'csv', 'json', 'netcdf', 'little_r' to save separate files. |
| -d Optional | string | Directory path where separate files should be saved. Note: Defaults to current directory if omitted. |
| -mt Optional | string | Filter observations data taken after this time. |
| -xt Optional | string | Filter observations data taken prior to this time. |
| -u Optional | boolean | Include update timestamps in response. |
| -m Optional | string | Restrict observations to the provided mission id. |
| -ml Optional | number | Minimum latitude boundary. |
| -xl Optional | number | Maximum latitude boundary. |
| -mg Optional | number | Minimum longitude boundary. |
| -xg Optional | number | Maximum longitude boundary. |
| -b Optional | number | Size of time buckets in hours. Note: Defaults to 6 hours. |
| Name | Description |
|---|---|
| since Required | Start time of fetching observations data. |
| -mt Optional | Filter observations data taken after this time. |
| -xt Optional | Filter observations data take prior to this time. |
| -id Optional | Include observation IDs in response. |
| -mn Optional | Include mission names in response. |
| -u Optional | Include update timestamps in response. |
| -m Optional | Filter observations by mission ID. |
| save_to_file Optional | Path to save the response data in .csv/.json format. |
| Name | Type | Description |
|---|---|---|
| start_time | string | Start time for fetching data. Note: Supports YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM, and ISO strings. |
| end_time | string | End time for fetching data. Note: Supports YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM, and ISO strings. If omitted, current time is used. |
| bucket_hours | number | Size of time buckets in hours. Note: Defaults to 6 hours. Data is split by mission and time period. |
| output_file | string | Save all data to a single file instead of bucketing. Note: Supported formats '.csv', '.json', '.little_r', '.nc'. |
| output_format | string | Format for saving separate files. Note: Options 'json', 'csv', 'little_r', 'netcdf'. |
| output_dir | string | Directory path for separate files. Note: Defaults to current directory if omitted. |
| callback | function | Called for each fetched page. Note: Receives one argument: the observations page. Use to stream or process data. |
| custom_save | function | Custom file saving hook. Note: Called with (observations list, recommended filename). |
| exit_at_end | boolean | Whether to exit after reaching the end of data. Note: If false, behaves like poll_observations. Defaults to true. |
| Name | Description |
|---|---|
| since | Start time of fetching observations data. |
| min_time | Filter observations data taken after this time. |
| max_time | Filter observations data taken prior to this time. |
| include_ids | Include observation IDs in response. |
| include_mission_name | Include mission names in response. |
| include_updated_at | Include update timestamps in response. |
| mission_id | Filter observations by mission ID. |
| output_file | Path to save the response data in .csv/.json format. |
The response contains pagination information and an array of super observation data points.
| Name | Type | Description | Format |
|---|---|---|---|
| has_next_page | boolean | Indicates where or not there is a subsequent page of data. | - |
| next_page | string | The url for the next page of data. If there is no subsequent page (ie, has_next_page is false), this will be null. | - |
| next_since | numeric | A unix timestamp that can be used in the since query string parameter when fetching subsequent pages, indicating where the data for the next page starts. Note: This is still provided even when there is no next page so that the client may poll the endpoint without concern for missing new data. | unix timestamp |
| observations | array | An array of data points; see below for description of data point structure. Note: In some limited cases, this may have zero elements. | - |
| altitude | numeric | Altitude | meters |
| humidity | numeric | Relative humidity | percent |
| specific_humidity | numeric | Specific humidity | mg/kg |
| latitude | numeric | Latitude. Note: This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row. | degrees |
| longitude | numeric | Longitude. Note: This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row. | degrees |
| pressure | numeric | Pressure | hectopascals |
| speed_u | numeric | Wind speed in direction of increasing longitude. Note: For compatibility reasons, this is additionally provided as speed_y | m/s |
| speed_v | numeric | Wind speed in direction of increasing latitude. Note: For compatibility reasons, this is additionally provided as speed_x | m/s |
| temperature | numeric | Temperature | ºC |
| timestamp | numeric | A unix timestamp (seconds since unix epoch) for when the measurement was taken | unix timestamp |
| id Optional | numeric | The unique id of this specific observation. Note: Only present when include_ids is set to true. | - |
| mission_id Optional | string | The unique id of the mission that collected this observation. Note: Only present when include_ids is set to true. | - |
| mission_name Optional | string | The human name of the mission that collected this observation. Note: Only present when include_mission_name is set to true. | - |
| updated_at Optional | numeric | A unix timestamp (seconds since unix epoch) for when the observation was last updated in the database (eg from a re-processing of sensor data). Note: Only present when include_updated_at is set to true. | unix timestamp |