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 |
|---|---|---|
| since Optional | integer | Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Check has_next_page in the response to know when to stop. |
| min_time Optional | integer (unix seconds) | Only returns observations taken at or after this value. This filters by when the observation was taken, unlike since, which is used for pagination. |
| max_time Optional | integer (unix seconds) | Only returns observations taken at or before this value. |
| include_ids Optional | boolean | If true, will include the ID of the observation and the mission that collected it. Default: false |
| include_mission_name Optional | boolean | If true, will include the human name of the mission that collected the observation. Default: false |
| include_updated_at Optional | boolean | If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data). Default: false |
| mission_id Optional | string (UUID) | ID of a WindBorne balloon mission, as listed by Flying Missions. Returns only that mission's observations. |
| min_latitude Optional | number | Southern edge of the bounding box. Range: −90° to 90° |
| max_latitude Optional | number | Northern edge of the bounding box. Range: −90° to 90° |
| min_longitude Optional | number | Western edge of the bounding box. Range: −180° to 180° |
| max_longitude Optional | number | Eastern edge of the bounding box. Range: −180° to 180° |
| Name | Type | Description |
|---|---|---|
| start_time Required | string (YYYY-MM-DDTHH:mm:ssZ or YYYYMMDDHH) | Start time for fetching data. |
| end_time Optional | string (YYYY-MM-DDTHH:mm:ssZ or YYYYMMDDHH) | End time for fetching data. Default: now |
| -m , --mission-id Optional | string (UUID) | ID of a WindBorne balloon mission, as listed by Flying Missions. |
| -ml , --min-latitude Optional | number | Southern edge of the bounding box. Range: −90° to 90° |
| -xl , --max-latitude Optional | number | Northern edge of the bounding box. Range: −90° to 90° |
| -mg , --min-longitude Optional | number | Western edge of the bounding box. Range: −180° to 180° |
| -xg , --max-longitude Optional | number | Eastern edge of the bounding box. Range: −180° to 180° |
| -b , --bucket-hours Optional | number | Size of time buckets. Data is split by mission and time period. Unit: hours; Default: 6 |
| -d , --output-dir Optional | string | Directory path for separate files. Default: the current directory |
| output Required | string | Save all data to a single file rather than splitting by time and mission. File formats: .csv, .json, .little_r, .nc; or use csv, json, netcdf, little_r to save separate files. |
| Name | Type | Description |
|---|---|---|
| since Required | string | Start time of fetching observations data. |
| -mt , --min-time Optional | string | Filter observations data taken after this time. |
| -xt , --max-time Optional | string | Filter observations data taken prior to this time. |
| -id , --include-ids Optional | flag | If true, will include the ID of the observation and the mission that collected it. Default: false |
| -mn , --include-mission-name Optional | flag | If true, will include the human name of the mission that collected the observation. Default: false |
| -u , --include-updated-at Optional | flag | If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data). Default: false |
| -m , --mission-id Optional | string (UUID) | ID of a WindBorne balloon mission, as listed by Flying Missions. Returns only that mission's observations. |
| -ml , --min-latitude Optional | number | Southern edge of the bounding box. Range: −90° to 90° |
| -xl , --max-latitude Optional | number | Northern edge of the bounding box. Range: −90° to 90° |
| -mg , --min-longitude Optional | number | Western edge of the bounding box. Range: −180° to 180° |
| -xg , --max-longitude Optional | number | Eastern edge of the bounding box. Range: −180° to 180° |
| output_file Optional | string | Path to save the response data in .csv/.json format. |
| Name | Type | Description |
|---|---|---|
| start_time Required | str (YYYY-MM-DDTHH:mm:ssZ or YYYYMMDDHH) | Start time for fetching data. |
| end_time Optional | str (YYYY-MM-DDTHH:mm:ssZ or YYYYMMDDHH) | End time for fetching data. Default: now |
| mission_id Optional | str (UUID) | ID of a WindBorne balloon mission, as listed by Flying Missions. |
| min_latitude Optional | float | Southern edge of the bounding box. Range: −90° to 90° |
| max_latitude Optional | float | Northern edge of the bounding box. Range: −90° to 90° |
| min_longitude Optional | float | Western edge of the bounding box. Range: −180° to 180° |
| max_longitude Optional | float | Eastern edge of the bounding box. Range: −180° to 180° |
| include_updated_at Optional | bool | If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data). Default: true |
| bucket_hours Optional | float | Size of time buckets. Data is split by mission and time period. Unit: hours; Default: 6 |
| output_file Optional | str | Save all data to a single file instead of bucketing. Supported formats: .csv, .json, .little_r, .nc. |
| output_format Optional | str | Format for saving separate files. Allowed: json, csv, little_r, netcdf |
| output_dir Optional | str | Directory path for separate files. Default: the current directory |
| callback Optional | function | Called for each fetched page. Receives one argument: the observations page. Use to stream or process data. |
| custom_save Optional | function | Custom file saving hook. Called with (observations list, recommended filename). |
| exit_at_end Optional | bool | Whether to exit after reaching the end of data. If false, behaves like poll_observations. Default: true |
| Name | Type | Description |
|---|---|---|
| since Optional | str | int | Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Also accepts an ISO 8601 time. |
| min_time Optional | str | Filter observations data taken after this time. |
| max_time Optional | str | Filter observations data taken prior to this time. |
| include_ids Optional | bool | If true, will include the ID of the observation and the mission that collected it. Default: false |
| include_mission_name Optional | bool | If true, will include the human name of the mission that collected the observation. Default: false |
| include_updated_at Optional | bool | If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data). Default: false |
| mission_id Optional | str (UUID) | ID of a WindBorne balloon mission, as listed by Flying Missions. Returns only that mission's observations. |
| min_latitude Optional | float | Southern edge of the bounding box. Range: −90° to 90° |
| max_latitude Optional | float | Northern edge of the bounding box. Range: −90° to 90° |
| min_longitude Optional | float | Western edge of the bounding box. Range: −180° to 180° |
| max_longitude Optional | float | Eastern edge of the bounding box. Range: −180° to 180° |
| output_file Optional | str | 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 |
|---|---|---|
| has_next_page | boolean | Indicates whether or not there is a subsequent page of data. |
| next_page | string | null | The URL for the next page of data. If there is no subsequent page (i.e., has_next_page is false), this will be null. |
| next_since | integer | null | Pass this value unchanged as the since query parameter when checking for new observations. It can be null when no observations are returned. |
| observations | object[] | Data points; see below for description of data point structure. In some limited cases, this may have zero elements. |
| altitude | number | null | Altitude. Unit: meters |
| humidity | number | null | Relative humidity. Unit: % |
| specific_humidity | number | null | Specific humidity. Unit: mg/kg |
| latitude | number | null | Latitude. 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. Unit: degrees |
| longitude | number | null | Longitude. 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. Unit: degrees |
| pressure | number | null | Pressure. Unit: hPa |
| speed_u | number | null | Eastward wind component. Unit: m/s |
| speed_v | number | null | Northward wind component. Unit: m/s |
| temperature | number | null | Temperature. Unit: °C |
| timestamp | number (unix seconds) | When the measurement was taken. |
| id | integer | The unique ID of this specific observation. Present when: include_ids=true |
| mission_id | string (UUID) | The unique ID of the mission that collected this observation. Present when: include_ids=true |
| mission_name | string | null | The human name of the mission that collected this observation. Present when: include_mission_name=true |
| updated_at | number (unix seconds) | When the observation was last updated in the database (e.g. from a re-processing of sensor data). Present when: include_updated_at=true |