GET Observations

Retrieve weather observations from WindBorne's global sounding balloon constellation. Observations are returned in chronological order with the most recent data first.

/data/v1/observations/data/v1/observations

windborne observationswindborne observations

Fetches a single page of observations data either prints it, saves it to a file or returns it as a dictionary.

windborne observations-pagewindborne observations-page

Continuously poll the Observations API to fetch new or updated data. This is useful for streaming data into your systems in near real-time.

windborne poll-observationswindborne poll-observations

from windborne import get_observationsfrom windborne import get_observations

Fetches a single page of observations data either prints it, saves it to a file or returns it as a dictionary.

from windborne import get_observations_pagefrom windborne import get_observations_page

Continuously poll the Observations API to fetch new or updated data. This is useful for streaming data into your systems in near real-time.

from windborne import poll_observationsfrom windborne import poll_observations

Frequently you will need to fetch data continuously, rather than only requesting a specific page. We recommend doing so as follows:

Fetch a page of data, storing next_since .
If has_next_page is false, sleep for your polling interval (we recommend a polling interval of one minute). Otherwise, proceed immediately.
Set the since query string parameter of the following request to next_since .
Repeat!

Query parameters

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.	-

Query parameters for regular observations and poll-observations

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.

Query parameters for page observations

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.

Query parameters for regular observations and poll-observations

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.

Query parameters for page observations

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.

Response parameters

Returns an array of observation objects, each containing location, timestamp, and meteorological data. Observations are ordered by time (most recent first).

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 Optional	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	%
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

Custom processing callback

Python: Custom save example

1 from windborne import get_observationsfrom windborne import get_observations

2 import osimport os

4 def save_custom_format(observations, filename):def save_custom_format(observations, filename):

5 """ """

7 """ """

8 # Ensure directory exists # Ensure directory exists

9 os.makedirs(os.path.dirname(filename) or '.', exist_ok=True) os.makedirs(os.path.dirname(filename) or '.', exist_ok=True)

10 header_written = os.path.exists(filename) header_written = os.path.exists(filename)

11 with open(filename, "a") as f: with open(filename, "a") as f:

12 if not header_written: if not header_written:

14 ")")

15 for obs in observations: for obs in observations:

16 custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')} custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')}

17 ""

18 f.write(custom_line) f.write(custom_line)

20 # Fetch observations and save them using the custom format# Fetch observations and save them using the custom format

21 get_observations(get_observations(

22 start_time="2025-01-01_00:00", start_time="2025-01-01_00:00",

23 end_time="2025-01-01_09:00", end_time="2025-01-01_09:00",

24 custom_save=save_custom_format, # Callback for custom saving custom_save=save_custom_format, # Callback for custom saving

25 output_format="txt" # Used as an extension for the filename output_format="txt" # Used as an extension for the filename

26 ))

Continuous Polling

Continuous polling

1 import timeimport time

3 since = 0since = 0

4 while True:while True:

5 # note: this uses `wb_get_request` as defined in the authentication section # note: this uses `wb_get_request` as defined in the authentication section

6 observations_page = wb_get_request(f"https://api.windbornesystems.com/data/v1/observations?since={since}") observations_page = wb_get_request(f"https://api.windbornesystems.com/data/v1/observations?since={since}")

8 # TODO: do something useful with observations_page['observations'] # TODO: do something useful with observations_page['observations']

9 print(f"Fetched {len(observations_page['observations'])} observation(s)") print(f"Fetched {len(observations_page['observations'])} observation(s)")

11 # if there's no new data, sleep # if there's no new data, sleep

12 if not observations_page['has_next_page']: if not observations_page['has_next_page']:

13 time.sleep(60) time.sleep(60)

15 # update since for the next request # update since for the next request

How to use the observations API

curl -u "WB_CLIENT_ID:WB_API_KEY" "https://api.windbornesystems.com/data/v1/observations?since=1644561775&include_ids=true"curl -u "WB_CLIENT_ID:WB_API_KEY" "https://api.windbornesystems.com/data/v1/observations?since=1644561775&include_ids=true"

# Save to multiple csv files# Save to multiple csv files

windborne observations 2024-12-18_00:00 csvwindborne observations 2024-12-18_00:00 csv

# Save to multiple csv files using different time formats# Save to multiple csv files using different time formats

windborne observations '2024-12-18 00:00:00' csvwindborne observations '2024-12-18 00:00:00' csv

# Save to multiple csv files within specified folder# Save to multiple csv files within specified folder

windborne observations -d my_wb_data_folder '2024-12-18 00:00:00' csvwindborne observations -d my_wb_data_folder '2024-12-18 00:00:00' csv

windborne observations 2025-01-14T15:00:00.000Z csvwindborne observations 2025-01-14T15:00:00.000Z csv

# Save to multiple little_r files# Save to multiple little_r files

windborne observations 2024-12-18_00:00 little_rwindborne observations 2024-12-18_00:00 little_r

# Save to multiple json files# Save to multiple json files

windborne observations 2024-12-18_00:00 jsonwindborne observations 2024-12-18_00:00 json

# Save to single file# Save to single file

windborne observations 2025-01-16_14:00 my_wb_data_folder/output.csvwindborne observations 2025-01-16_14:00 my_wb_data_folder/output.csv

windborne observations 2024-12-18_12:00 2024-12-18_14:00 output.jsonwindborne observations 2024-12-18_12:00 2024-12-18_14:00 output.json

windborne observations 2024-12-18_12:00 2024-12-18_14:00 output.little_rwindborne observations 2024-12-18_12:00 2024-12-18_14:00 output.little_r

# Optional args# Optional args

windborne observations -b 12 2024-12-18_12:00 2024-12-18_14:00 output.jsonwindborne observations -b 12 2024-12-18_12:00 2024-12-18_14:00 output.json

# Poll observations# Poll observations

# Save to multiple csv files # Save to multiple csv files

windborne poll-observations 2024-12-18_00:00 csv windborne poll-observations 2024-12-18_00:00 csv

# Save to multiple csv files using different time formats # Save to multiple csv files using different time formats

windborne poll-observations '2024-12-18 00:00:00' csv windborne poll-observations '2024-12-18 00:00:00' csv

# Save to multiple csv files within specified folder # Save to multiple csv files within specified folder

windborne poll-observations -d my_wb_data_folder '2024-12-18 00:00:00' csv windborne poll-observations -d my_wb_data_folder '2024-12-18 00:00:00' csv

windborne poll-observations 2025-01-14T15:00:00.000Z csv windborne poll-observations 2025-01-14T15:00:00.000Z csv

# Save to multiple little_r files # Save to multiple little_r files

windborne poll-observations 2024-12-18_00:00 little_r windborne poll-observations 2024-12-18_00:00 little_r

# Save to multiple json files # Save to multiple json files

windborne poll-observations 2024-12-18_00:00 json windborne poll-observations 2024-12-18_00:00 json

# Optional args # Optional args

windborne poll-observations -b 12 2024-12-18_12:00 json windborne poll-observations -b 12 2024-12-18_12:00 json

# Page observations# Page observations

# Basic page observations usage with .csv and .json formats # Basic page observations usage with .csv and .json formats

windborne observations-page 2024-12-18_00:00 output.csv windborne observations-page 2024-12-18_00:00 output.csv

windborne observations-page 2024-12-18_00:00 output.json windborne observations-page 2024-12-18_00:00 output.json

# Geographic filters for page observations # Geographic filters for page observations

windborne observations-page -ml 45.0 -xl 50.0 -mg -120.0 -xg 110.0 2024-12-18_00:00 output.csv windborne observations-page -ml 45.0 -xl 50.0 -mg -120.0 -xg 110.0 2024-12-18_00:00 output.csv

from windborne import get_observationsfrom windborne import get_observations

# Save to separate files# Save to separate files

get_observations(get_observations(

start_time='2023-10-13_00:00', start_time='2023-10-13_00:00',

end_time='2024-10-14_00:00', end_time='2024-10-14_00:00',

output_format='csv', # or 'json', 'little_r', 'netcdf' output_format='csv', # or 'json', 'little_r', 'netcdf'

output_dir='my_wb_data_folder' output_dir='my_wb_data_folder'

))

# Save to single file# Save to single file

get_observations(get_observations(

start_time='2023-10-13_00:00', start_time='2023-10-13_00:00',

end_time='2024-10-14_00:00', end_time='2024-10-14_00:00',

bucket_hours=12, bucket_hours=12,

output_file='my_wb_data_folder/output.csv' # or '.json', '.little_r', '.nc' output_file='my_wb_data_folder/output.csv' # or '.json', '.little_r', '.nc'

))

#Poll Observations#Poll Observations

from windborne import poll_observations from windborne import poll_observations

poll_observations( poll_observations(

start_time='2023-10-13_00:00', start_time='2023-10-13_00:00',

output_format='csv', # or 'json', 'little_r', 'netcdf' output_format='csv', # or 'json', 'little_r', 'netcdf'

output_dir='/Users/windborne/Desktop/my_wb_data_folder' output_dir='/Users/windborne/Desktop/my_wb_data_folder'

) )

#Observation Pages#Observation Pages

from windborne import get_observations_pagefrom windborne import get_observations_page

observations_page = get_observations_page(observations_page = get_observations_page(

since='2024-12-17_00:00', since='2024-12-17_00:00',

min_time='2024-12-18_19:00', min_time='2024-12-18_19:00',

min_latitude=45.0, min_latitude=45.0,

max_latitude=50.0, max_latitude=50.0,

min_longitude=-120.0, min_longitude=-120.0,

max_longitude=-110.0, max_longitude=-110.0,

include_ids=True, include_ids=True,

include_mission_name=True, include_mission_name=True,

include_updated_at=True, include_updated_at=True,

output_file='output.csv' # or .json output_file='output.csv' # or .json

))

content-type: application/json

1 {{

2 "has_next_page": true, "has_next_page": true,

3 "next_page": "https://api.windbornesystems.com/data/v1/observations?since=1644571775", "next_page": "https://api.windbornesystems.com/data/v1/observations?since=1644571775",

4 "next_since": 1644571775, "next_since": 1644571775,

5 "observations": [ "observations": [

6 { {

7 "altitude": 8.3, "altitude": 8.3,

8 "humidity": null, "humidity": null,

9 "id": 9762766, "id": 9762766,

10 "latitude": 37.42113, "latitude": 37.42113,

11 "longitude": -122.10341, "longitude": -122.10341,

12 "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c", "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c",

13 "mission_name": "W-260", "mission_name": "W-260",

14 "pressure": null, "pressure": null,

15 "specific_humidity": null, "specific_humidity": null,

16 "speed_u": 0.2, "speed_u": 0.2,

17 "speed_v": 0.2, "speed_v": 0.2,

18 "temperature": null, "temperature": null,

19 "timestamp": 1644561775, "timestamp": 1644561775,

20 "updated_at": 1644561775 "updated_at": 1644561775

21 }, },

22 { {

23 "altitude": 0.49, "altitude": 0.49,

24 "humidity": null, "humidity": null,

25 "id": 9762767, "id": 9762767,

26 "latitude": 37.42113, "latitude": 37.42113,

27 "longitude": -122.10341, "longitude": -122.10341,

28 "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c", "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c",

29 "mission_name": "W-260", "mission_name": "W-260",

30 "pressure": null, "pressure": null,

31 "specific_humidity": null, "specific_humidity": null,

32 "speed_u": -0.2, "speed_u": -0.2,

33 "speed_v": -0.2, "speed_v": -0.2,

34 "temperature": null, "temperature": null,

35 "timestamp": 1644561785, "timestamp": 1644561785,

36 "updated_at": 1644561785 "updated_at": 1644561785

37 }, },

38 { {

39 "altitude": 0.49, "altitude": 0.49,

40 "humidity": null, "humidity": null,

41 "id": 9762768, "id": 9762768,

42 "latitude": 37.42113, "latitude": 37.42113,

43 "longitude": -122.10341, "longitude": -122.10341,

44 "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c", "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c",

45 "mission_name": "W-260", "mission_name": "W-260",

46 "pressure": null, "pressure": null,

47 "specific_humidity": null, "specific_humidity": null,

48 "speed_u": 0.2, "speed_u": 0.2,

49 "speed_v": -0.2, "speed_v": -0.2,

50 "temperature": null, "temperature": null,

51 "timestamp": 1644561795, "timestamp": 1644561795,

52 "updated_at": 1644561795 "updated_at": 1644561795

53 }, },

54 { {

55 "altitude": 0.49, "altitude": 0.49,

56 "humidity": null, "humidity": null,

57 "id": 9762769, "id": 9762769,

58 "latitude": 37.42113, "latitude": 37.42113,

59 "longitude": -122.10341, "longitude": -122.10341,

60 "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c", "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c",

61 "mission_name": "W-260", "mission_name": "W-260",

62 "pressure": null, "pressure": null,

63 "specific_humidity": null, "specific_humidity": null,

64 "speed_u": 0.2, "speed_u": 0.2,

65 "speed_v": 0.2, "speed_v": 0.2,

66 "temperature": null, "temperature": null,

67 "timestamp": 1644561805, "timestamp": 1644561805,

68 "updated_at": 1644561805 "updated_at": 1644561805

69 }, },

70 { {

71 "altitude": 8.3, "altitude": 8.3,

72 "humidity": null, "humidity": null,

73 "id": 9762770, "id": 9762770,

74 "latitude": 37.42113, "latitude": 37.42113,

75 "longitude": -122.10341, "longitude": -122.10341,

76 "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c", "mission_id": "a4695144-c119-4ca7-ade2-512ae0aa332c",

77 "mission_name": "W-260", "mission_name": "W-260",

78 "pressure": null, "pressure": null,

79 "specific_humidity": null, "specific_humidity": null,

80 "speed_u": -0.2, "speed_u": -0.2,

81 "speed_v": 0.2, "speed_v": 0.2,

82 "temperature": null, "temperature": null,

83 "timestamp": 1644561815, "timestamp": 1644561815,

84 "updated_at": 1644561815 "updated_at": 1644561815

85 } }

86 ] ]

87 }}