WindBorne Systems API Reference

Introduction

WindBorne provides a pip installable library built to interact with Data and Forecasts APIs.

WindBorne uses API keys to authenticate API requests. If an API request is not properly authenticated, it will fail. To get an API key, email data@windbornesystems.com.

In order to authenticate with the api, you must set the following environment variables:

WB_CLIENT_ID
WB_API_KEY

On unix systems (mac and linux), you can add these to your shell configuration file (e.g. ~/.bashrc, ~/.bash_profile, ~/.zshrc). On windows, you can set these as user environment variables. See the instructions on the right for examples of how to do this.

Need access?

Email data@windbornesystems.com

Installation

Bash

pip3 install windborne

Set Credentials on mac and linux

Bash

# Determine your shell and it's configuration file
# Some common configuration files are: ~/.bashrc, ~/.bash_profile, ~/.zshrc
echo $SHELL
# Edit your shell configuration file adding these two lines
export WB_CLIENT_ID='your_client_id'
export WB_API_KEY='your_api_key'
# Reload the shell configuration to apply changes immediately or restart

Set Credentials on windows

1. Press Win + X and select "System"
2. Click "Advanced system settings" on the right
3. Click "Environment Variables" at the bottom
4. Under "User variables", click "New" and add
Variable name: WB_CLIENT_ID
Variable value: your_client_id
Variable name: WB_API_KEY
Variable value: your_api_key

get_super_observations

Fetches super observations within a time range and saves them to specified file(s).

It accepts the following parameters:

Name	Type	Description
start_time	string	A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the starting time of fetching data.
end_time	string	Optional. A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the end time of fetching data. If not provided, current time is used as end time.
bucket_hours	integer	Optional. Size of time buckets in hours. Defaults to 6 hours. By default, data is split by both mission and time period.
output_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_format	string	Optional. Format to save data in separate files. Supported formats are 'json, 'csv', 'little_r' and 'netcdf'.
output_dir	string	Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.
callback	callable	Optional. If provided, this will be called every time a page of super observations is fetched. This can be used to stream data to a database or to perform custom processing. It will be called with one arg, a super observations page.
custom_save	callable	Optional. If provided, this will be called each time It will be called with two args: a list of super observations and a recommended file name. This can be used to save data in a custom format.
exit_at_end	boolean	Optional. If True, the script will exit after running out of data to fetch. Setting this to False will make this act like poll_super_observations. Defaults to True.

Example

Python

from windborne import get_super_observations
# Save to separate files
get_super_observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    output_format='csv', # or 'json', 'little_r', 'netcdf'
    output_dir='my_wb_data_folder'
)
# Save to single file
get_super_observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    bucket_hours=12,
    output_file='my_wb_data_folder/output.csv' # or '.json', '.little_r', '.nc'
)

callback for custom processing

Python

from windborne import get_super_observations
import os

def save_custom_format(super_observations, filename):
    """
    Save super observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    with open(filename, "a") as f:
        f.write("timestamp|latitude|longitude|temperature\n")
        for obs in super_observations:
            # Write observation data
            custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')}\n"
            f.write(custom_line)

# Fetch super observations and save them using the custom format
get_super_observations(
    start_time="2025-01-01_00:00",  # Start time for fetching super observations
    end_time="2025-01-01_09:00",    # End time for fetching super observations
    custom_save=save_custom_format, # Callback for custom saving
    output_format="txt",            # It will use this as an extension for the filename
)

get_observations

Fetches observations within a time range and saves them to specified file(s).

It accepts the following parameters:

Name	Type	Description
start_time	string	A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the starting time of fetching data.
end_time	string	Optional. A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the end time of fetching data. If not provided, current time is used as end time.
include_ids	boolean	Optional. Include observation IDs in response.
include_updated_at	boolean	Optional. Include update timestamps in response.
mission_id	string	Optional. Filter observations by mission ID.
min_latitude	float	Optional.Minimum latitude boundary.
max_latitude	float	Optional. Maximum latitude boundary.
min_longitude	float	Optional. Minimum longitude boundary.
max_longitude	float	Optional. Maximum longitude boundary.
bucket_hours	integer	Optional. Size of time buckets in hours. Defaults to 6 hours. By default, data is split by both mission and time period.
output_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_format	string	Optional. Format to save data in separate files. Supported formats are 'json, 'csv', 'little_r' and 'netcdf'.
output_dir	string	Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.
callback	callable	Optional. If provided, this will be called every time a page of observations is fetched. This can be used to stream data to a database or to perform custom processing. It will be called with one arg, a observations page.
custom_save	callable	Optional. If provided, this will be called each time It will be called with two args: a list of super observations and a recommended file name. This can be used to save data in a custom format.
exit_at_end	boolean	Optional. If True, the script will exit after running out of data to fetch. Setting this to False will make this act like poll_observations. Defaults to True.

Example

Python

from windborne import get_observations
# Save to separate files
get_observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    output_format='csv', # or 'json', 'little_r', 'netcdf'
    output_dir='/Users/windborne/Desktop/my_wb_data_folder'
)
# Save to single file
get_observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    bucket_hours=12,
    output_file='/Users/windborne/Desktop/output.csv' # or '.json', '.little_r', '.nc'
)

callback for custom processing

Python

from windborne import observations
import os

def save_custom_format(observations, filename):
    """
    Save observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    with open(filename, "a") as f:
        f.write("timestamp|latitude|longitude|temperature\n")
        for obs in observations:
            # Write observation data
            custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')}\n"
            f.write(custom_line)

# Fetch super observations and save them using the custom format
get_observations(
    start_time="2025-01-01_00:00",  # Start time for fetching observations
    end_time="2025-01-01_09:00",    # End time for fetching observations
    custom_save=save_custom_format, # Callback for custom saving
    format="txt"  # It will use this as an extension for the filename
)

poll_super_observations

Run super observation fetching in an infinite loop, continuously saving this outputs.

It accepts the following parameters:

Name	Type	Description
start_time	string	A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the starting time of fetching data.
end_time	string	Optional. A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the end time of fetching data. If not provided, current time is used as end time.
bucket_hours	integer	Optional. Size of time buckets in hours. Defaults to 6 hours. By default, data is split by both mission and time period.
output_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_format	string	Optional. Format to save data in separate files. Supported formats are 'json, 'csv', 'little_r' and 'netcdf'.
output_dir	string	Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.
callback	callable	Optional. If provided, this will be called every time a page of super observations is fetched. This can be used to stream data to a database or to perform custom processing. It will be called with one arg, a super observations page.
custom_save	callable	Optional. If provided, this will be called each time It will be called with two args: a list of super observations and a recommended file name. This can be used to save data in a custom format.

Example

Python

from windborne import poll_super_observations
poll_super_observations(
    start_time='2023-10-13_00:00',
    output_format='csv', # or 'json', 'little_r', 'netcdf'
    output_dir='my_wb_data_folder'
)

callback for custom processing

Python

from windborne import poll_super_observations
import os

def save_custom_format(super_observations, filename):
    """
    Save super observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    with open(filename, "a") as f:
        f.write("timestamp|latitude|longitude|temperature\n")
        for obs in super_observations:
            # Write observation data
            custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')}\n"
            f.write(custom_line)

# Poll super observations and save them using the custom format
poll_super_observations(
    start_time="2025-01-01_00:00",  # Start time for polling super observations
    custom_save=save_custom_format, # Callback for custom saving
    format="txt",  # It will use this as an extension for the filename
)

poll_observations

Polls observations continuously and saves them to specified file(s).

It accepts the following parameters:

Name	Type	Description
start_time	string	A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the starting time of fetching data.
end_time	string	Optional. A date string, supporting formats YYYY-MM-DD HH:MM:SS, YYYY-MM-DD_HH:MM and ISO strings, representing the end time of fetching data. If not provided, current time is used as end time.
include_ids	boolean	Optional. Include observation IDs in response.
include_updated_at	boolean	Optional. Include update timestamps in response.
mission_id	string	Optional. Filter observations by mission ID.
min_latitude	float	Optional.Minimum latitude boundary.
max_latitude	float	Optional. Maximum latitude boundary.
min_longitude	float	Optional. Minimum longitude boundary.
max_longitude	float	Optional. Maximum longitude boundary.
bucket_hours	integer	Optional. Size of time buckets in hours. Defaults to 6 hours. By default, data is split by both mission and time period.
output_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_format	string	Optional. Format to save data in separate files. Supported formats are 'json, 'csv', 'little_r' and 'netcdf'.
output_dir	string	Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.
callback	callable	Optional. If provided, this will be called every time a page of observations is fetched. This can be used to stream data to a database or to perform custom processing. It will be called with one arg, a observations page.
custom_save	callable	Optional. If provided, this will be called each time It will be called with two args: a list of super observations and a recommended file name. This can be used to save data in a custom format.

Example

Python

from windborne import poll_observations
poll_observations(
    start_time='2023-10-13_00:00',
    output_format='csv', # or 'json', 'little_r', 'netcdf'
    output_dir='/Users/windborne/Desktop/my_wb_data_folder'
)

callback for custom processing

Python

from windborne import poll_observations
import os

def save_custom_format(observations, filename):
    """
    Save observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    with open(filename, "a") as f:
        f.write("timestamp|latitude|longitude|temperature\n")
        for obs in observations:
            # Write observation data
            custom_line = f"{obs.get('timestamp', 'N/A')}|{obs.get('latitude', 'N/A')}|{obs.get('longitude', 'N/A')}|{obs.get('temperature', 'N/A')}\n"
            f.write(custom_line)

# Poll super observations and save them using the custom format
poll_observations(
    start_time="2025-01-01_00:00",  # Start time for polling observations
    custom_save=save_custom_format, # Callback for custom saving
    format="txt",  # It will use this as an extension for the filename
)

get_observations_page

Fetches a page of observations, optionally saving it to a file. This is an extremely thin wrapper around the observations endpoint, with an identical return type.

It accepts the following parameters:

Name	Type	Description
since	string	Optional. Start time of fetching observations data.
min_time	string	Optional. Filter observations data taken after this time.
max_time	string	Optional. Filter observations data take prior to this time.
include_ids	boolean	Optional. Include observation IDs in response.
include_mission_name	boolean	Optional. Include mission names in response.
include_updated_at	boolean	Optional. Include update timestamps in response.
mission_id	string	Optional. Filter observations by mission ID.
min_latitude	float	Optional.Minimum latitude boundary.
max_latitude	float	Optional. Maximum latitude boundary.
min_longitude	float	Optional. Minimum longitude boundary.
max_longitude	float	Optional. Maximum longitude boundary.
output_file	string	Optional. Save the response data in .csv / .json format.

Example

Python

from windborne import get_observations_page
observations_page = get_observations_page(
    since='2024-12-17_00:00',
    min_time='2024-12-18_19:00',
    min_latitude=45.0,
    max_latitude=50.0,
    min_longitude=-120.0,
    max_longitude=-110.0,
    include_ids=True,
    include_mission_name=True,
    include_updated_at=True,
    output_file='output.csv'  # or .json
)

get_super_observations_page

Fetches a page of super observations, optionally saving it to a file. This is an extremely thin wrapper around the super observations endpoint, with an identical return type.

It accepts the following parameters:

Name	Type	Description
since	string	Start time of fetching observations data.
min_time	string	Optional. Filter observations data taken after this time.
max_time	string	Optional. Filter observations data take prior to this time.
include_ids	boolean	Include observation IDs in response.
include_mission_name	boolean	Include mission names in response.
include_updated_at	boolean	Include update timestamps in response.
mission_id	string	Filter observations by mission ID.
output_file	string	Optional. Path to save the response data in .csv/.json format.

Example

Python

from windborne import get_super_observations_page
super_observations_page = get_super_observations_page(
    since='2024-12-18_00:00',
    mission_id='bbf8c77a-40cc-45ce-bef3-adb3a7d0b532',
    include_ids=True,
    include_mission_name=True,
    include_updated_at=True,
    output_file='output.csv'  # or .json
)

get_flying_missions

Retrieves flying missions and optionally saves to a file. Returns a list of missions, including their id, name, and launch time.

It accepts the following parameters:

Name	Type	Description
output_file	string	Optional. Path to save the response data. If provided, saves the data in CSV or JSON format.
print_results	boolean	Optional. If True, prints the response data.

Example

Python

from windborne import get_flying_missions
missions = get_flying_missions(output_file='output.json')

get_mission_launch_site

Retrieves launch site information for a specified mission, optionally saving it to a file. Returns a dictionary containing the launch site information.

It accepts the following parameters:

Name	Type	Description
mission_id	string	The mission for which to obtain launch site.
output_file	string	Optional. Path to save the response data. If provided, saves the data in CSV or JSON format.
print_result	boolean	Optional. If True, prints the response data.

Example

Python

from windborne import get_mission_launch_site
site = get_mission_launch_site(mission_id='494f8cb2-5fed-4c81-b3c4-5eacaa2ba4e0', output_file='output.json')

get_predicted_path

Fetches the predicted flight path for a given mission, assuming it is currently flying. Returns a list of coordinates.

It accepts the following parameters:

Name	Type	Description
mission_id	string	The mission for which to obtain predicted flight path.
output_file	string	Optional. Path to save the response data. If provided, saves the data in CSV or JSON format.

Example

Python

from windborne import get_predicted_path
path = get_predicted_path(mission_id='494f8cb2-5fed-4c81-b3c4-5eacaa2ba4e0', output_file='output.json')