WindBorne Systems API Reference

Introduction

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

The windborne python library is designed to be predictable, performant, and easy to use.

If you have not set your credentials as environment variables as described detailed in CLI section, you have the option to insert your credentials into your code directly before accessing the library.

Need access?

Email data@windbornesystems.com

Installation

Python

pip install windborne

Set Credentials

Bash

import os
os.environ['WB_CLIENT_ID'] = 'your_client_id'
os.environ['WB_API_KEY'] = 'your_api_key'

super_observations

Fetches super observations data 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.
interval	integer	Optional. Interval in seconds between polls when a empty page is received (default: 60)
save_to_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
bucket_hours	int	Optional. Size of time buckets in hours. Defaults to 6 hours.
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. Callback function that receives observations. This allows custom processing or saving in custom formats.

Example

Python

from windborne import super_observations
# Save to separate files
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
super_observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    bucket_hours=12,
    save_to_file='my_wb_data_folder/output.csv' # or '.json', '.little_r', '.nc'
)

callback for custom processing

Python

from windborne import super_observations
import os

def save_custom_format(super_observations):
    """
    Save super observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    file_name = "custom_output.txt"
    write_header = not os.path.exists(file_name)  # Check if the file already exists

    with open(file_name, "a") as f:
        if write_header:
            # Write the header row if the file is newly created
            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
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
    callback=save_custom_format  # Callback super observations for custom processing
)

observations

Fetches observations data 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.
interval	integer	Optional. Interval in seconds between polls when a empty page is received (default: 60)
save_to_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
bucket_hours	int	Optional. Size of time buckets in hours. Defaults to 6 hours.
output_format	string	Optional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
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. Callback function that receives observations. This allows custom processing or saving in custom formats.

Example

Python

from windborne import observations
# Save to separate files
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
observations(
    start_time='2023-10-13_00:00',
    end_time='2024-10-14_00:00',
    bucket_hours=12,
    save_to_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):
    """
    Save observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    file_name = "custom_output.txt"
    write_header = not os.path.exists(file_name)  # Check if the file already exists

    with open(file_name, "a") as f:
        if write_header:
            # Write the header row if the file is newly created
            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
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
    callback=save_custom_format  # Callback observations for custom processing

poll_super_observations

Polls super observations continuously and saves them to specified files.

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.
interval	integer	Optional. Interval in seconds between polls when a empty page is received (default: 60)
save_to_file	string	Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
bucket_hours	int	Optional. Size of time buckets in hours. Defaults to 6 hours.
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. Callback function that receives observations. This allows custom processing or saving in custom formats.

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):
    """
    Save super observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    file_name = "custom_output.txt"
    write_header = not os.path.exists(file_name)  # Check if the file already exists

    with open(file_name, "a") as f:
        if write_header:
            # Write the header row if the file is newly created
            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
    callback=save_custom_format  # Callback super observations for custom processing
)

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.
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.
interval	integer	Optional. Interval in seconds between polls when a empty page is received (default: 60)
bucket_hours	int	Optional. Size of time buckets in hours. Defaults to 6 hours.
output_format	string	Optional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
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. Callback function that receives observations. This allows custom processing or saving in custom formats.

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):
    """
    Save observations in a custom format: `timestamp|latitude|longitude|temperature`.
    """
    file_name = "custom_output.txt"
    write_header = not os.path.exists(file_name)  # Check if the file already exists

    with open(file_name, "a") as f:
        if write_header:
            # Write the header row if the file is newly created
            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
    callback=save_custom_format  # Callback observations for custom processing

get_observations_page

Retrieves an observations page based on specified filters.

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.
save_to_file	string	Optional. Save the response data in .csv / .json format.

It returns the response of API or saves the response data in save_to_file.

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,
    save_to_file='output.csv'  # or .json
)

get_super_observations_page

Retrieves a super observations page based on specified filters.

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.
save_to_file	string	Optional. Path to save the response data in .csv/.json format.

It returns the response of API or saves the response data in save_to_file.

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,
    save_to_file='output.csv'  # or .json
)

get_flying_missions

Retrieves a list of currently flying missions.

It accepts the following parameter:

Name	Type	Description
save_to_file	string	Optional. Path to save the response data. If provided, saves the data in CSV or JSON format.

It returns the response of API or saves the response data in save_to_file.

Example

Python

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

get_mission_launch_site

Retrieves launch site information for a specified mission.

It accepts the following parameters:

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

It returns the response of API or saves the response data in save_to_file.

Example

Python

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

get_predicted_path

Fetches the predicted flight path for a given mission currently flying.

It accepts the following parameters:

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

It returns the response of API or saves the response data in save_to_file.

Example

Python

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