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.

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_point_forecasts

This function gets the forecast at a given point or set of points. This runs WindBorne's custom point forecasting model, making it more accurate than simple interpolation of the gridded output.

It returns a custom points response.

It accepts the following parameters:

Name	Type	Description
coordinates	string	A list of coordinates. This may be a list of latitude,longitude tuples, eg `[(37, -121), (40.3, -100)]`, or a string with coordinates separated by semicolons, eg `37,-121;40.3,-100`
min_forecast_time	string	Optional. An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the minimum forecast time to calculate point forecasts for.
max_forecast_time	string	Optional. An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the maximum forecast time to calculate point forecasts for.
min_forecast_hour	integer	Optional. The minimum forecast hour to calculate point forecasts for.
max_forecast_hour	integer	Optional. The maximum forecast hour to calculate point forecasts for.
initialization_time	string	Optional. An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time at which the forecast was made. This looks solely at the date and the hour; minutes and seconds are discarded. If nothing is provided, the latest forecast is used. Available initialization times for point forecasts can be found using get_initialization_times.
output_file	string	Optional. If provided, the response data will be saved to this file. The file extension determines the format: .csv or .json.
print_response	boolean	Optional. If true, the response data will be printed to stdout. Default is false.

Example

Python

from windborne import get_point_forecasts

# To save response data in point_forecasts var
point_forecasts = get_point_forecasts(
    coordinates="40.7,-74.0;34.0,-118.2",
    min_forecast_hour=0,
    max_forecast_hour=24,
    initialization_time="2024121600")

# To save data in file
get_point_forecasts(
    coordinates="40.7,-74.0;34.0,-118.2",
    min_forecast_hour=0,
    max_forecast_hour=24,
    initialization_time="2024121600",
    output_file="output.csv" # .csv or .json
)

get_initialization_times

This function retrieves which initialization times are available in the API for generating point forecasts. It accepts no parameters.

It returns the following:

Name	Type	Description
available	[string]	An array of ISO8601 timestamps of available initialization times for point forecasts, ordered from newest to oldest.
latest	string	The ISO8601 timestamp of latest available initialization time for point forecasts.

Example

Python

from windborne import get_initialization_times
initialization_times = get_initialization_times()
print(initialization_times)

get_forecast_hours

This function allows getting the available forecast hours for different model initialization times. This may include initialization times that are not included in the get_initialization_times function, representing forecasts that are still in the process of being generated.

It can optionally accept the following parameters:

Name	Type	Description
ensemble_member	string or number	The ensemble member to get forecast hours for. Can be `mean` or a number between 1 and 25. Cannot be used with `intracycle`. Defaults to main deterministic run if not specified.
intracycle	boolean	Whether to return forecast hours for our intracycle model. This model comes out several hours before the main model or other models like GFS and ECMWF, and can give a directional signal on how the forecast is likely to evolve. Defaults to `false`. Cannot be used with `ensemble_member`.

It returns a dictionary where:

Name	Type	Description
key	string (ISO8601 timestamp)	An initialization time for which forecast hours are available.
value	[integer]	An array of available forecast hours for that specific initialization time.

Example Usage

Python

from windborne import get_forecast_hours
forecast_hours = get_forecast_hours()
print(forecast_hours)

Example Output Snippet

{
    "2025-05-16T00:00:00+00:00": [0, 1, 2, ..., 360],
    "2025-05-16T06:00:00+00:00": [0, 1, 2, ..., 360],
    "2025-05-16T12:00:00+00:00": [0, 1, 2, ..., 360],
    "2025-05-16T18:00:00+00:00": [0, 1, 2, ..., 360],
    "2025-05-17T00:00:00+00:00": [0, 1, 2, ..., 360],
    // ... more initialization times
}

get_gridded_forecast

This function downloads gridded forecast data to a specified NetCDF file. It can fetch either the latest available forecast for a specific time, or a historical forecast based on initialization time and forecast hour.

Variable Specification:The variable parameter determines which data is fetched. It can be specified in several ways:

'FULL': Downloads all available variables at all pressure levels.
'surface_variable_name': Downloads a specific surface variable (e.g., 'temperature_2m', 'pressure_msl').
'level/variable_name': Downloads a specific variable at a given pressure level (e.g., '500/temperature', '850/wind_v').

Refer to the API documentation for single gridded forecasts for a list of available variables.

Parameters:

Name	Type	Description
variable	string	Specifies the forecast variable(s) to download. See "Variable Specification" above.
output_file	string	Path (including filename) where the NetCDF (.nc) file will be saved.
time	string	The time at which the forecast is valid (for latest forecasts). Formats: ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. Minutes/seconds are discarded. Cannot be used with `initialization_time` and `forecast_hour`.
initialization_time	string	The initialization time for the forecast (for historical forecasts). Formats: ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. Minutes/seconds are discarded. Must be used with `forecast_hour`. Cannot be used with `time`.
forecast_hour	integer	Number of hours from `initialization_time` for which to get the historical forecast. Must be used with `initialization_time`. Cannot be used with `time`.
ensemble_member	string or number	Optional. The ensemble member to fetch. Can be `'mean'` or a number (e.g., 1 to 25). Cannot be used with `intracycle`.
intracycle	boolean	Optional. Set to `True` to use the intracycle forecast model. Defaults to `False`. Cannot be used with `ensemble_member`.

The function does not return any data directly but saves it to the specified output_file. It will print status messages to the console.

Example: Latest Full Forecast

Python

from windborne import get_gridded_forecast

get_gridded_forecast(
    variable='FULL',
    time='2025052009',
    output_file='latest_full_forecast.nc'
)
print("Downloaded latest full forecast to latest_full_forecast.nc")

Example: Latest Surface Variable Forecast

Python

from windborne import get_gridded_forecast

get_gridded_forecast(
    variable='temperature_2m',
    time='2025052009',
    output_file='latest_temp_2m.nc'
)
print("Downloaded latest 2m temperature forecast to latest_temp_2m.nc")

Example: Latest Upper-Level Ensemble Mean Forecast

Python

from windborne import get_gridded_forecast

get_gridded_forecast(
    variable='500/geopotential',
    time='2025052009',
    output_file='latest_500hpa_geo.nc',
    ensemble_member='mean'
)
print("Downloaded latest 500hPa geopotential mean ensemble forecast to latest_500hpa_geo.nc")

Example: Historical Forecast

Python

from windborne import get_gridded_forecast

get_gridded_forecast(
    variable='850/wind_u',
    initialization_time='2025051706',
    forecast_hour=12,
    output_file='historical_850_u.nc',
    intracycle=True
)
print("Downloaded historical 850hPa u-wind forecast to historical_850_u.nc")

get_full_gridded_forecast

This command allows getting the full gridded output of global forecasts, including data for all variables at all levels. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It returns a python response object with content being the bytes of the netcdf file. While we typically recommend using the output_file parameter, this can be used for custom handling of the response.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_full_gridded_forecast
get_full_gridded_forecast(time="2025052009", output_file="filename")

get_temperature_2m

This function allows getting the gridded output of global 2m temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_temperature_2m
get_temperature_2m(time="2025052009", output_file="filename")

get_wind_u_10m

This function allows getting the gridded output of global 10m u-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_wind_u_10m
get_wind_u_10m(time="2025052009", output_file="filename")

get_wind_v_10m

This function allows getting the gridded output of global 10m v-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_wind_v_10m
get_wind_v_10m(time="2025052009", output_file="filename")

get_pressure_msl

This function allows getting the gridded output of global mean sea level pressure forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_pressure_msl
get_pressure_msl(time="2025052009", output_file="filename")

get_500hpa_temperature

This function allows getting the gridded output of global 500hPa temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_temperature
get_500hpa_temperature(time="2025052009", output_file="filename")

get_850hpa_temperature

This function allows getting the gridded output of global 850hPa temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_850hpa_temperature
get_850hpa_temperature(time="2025052009", output_file="filename")

get_500hpa_wind_u

This function allows getting the gridded output of global 500hPa u-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_wind_u
get_500hpa_wind_u(time="2025052009", output_file="filename")

get_500hpa_wind_v

This function allows getting the gridded output of global 500hPa v-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If there is no forecast available within an hour of the requested time, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_wind_v
get_500hpa_wind_v(time="2025052009", output_file="filename")

historical_temperature_2m

This function allows getting the historical output of global 2m temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_temperature_2m
data = historical_temperature_2m(initialization_time="2025051706", forecast_hour=4, output_file="temperature_2m.nc")

historical_wind_u_10m

This function allows getting the historical output of global 10m u-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_wind_u_10m
data = historical_wind_u_10m(initialization_time="2025051706", forecast_hour=4, output_file="wind_u_10m.nc")

historical_wind_v_10m

This function allows getting the historical output of global 10m v-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_wind_v_10m
data = historical_wind_v_10m(initialization_time="2025051706", forecast_hour=4, output_file="wind_v_10m.nc")

historical_pressure_msl

This function allows getting the historical output of global mean sea level pressure forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_pressure_msl
data = historical_pressure_msl(initialization_time="2025051706", forecast_hour=4, output_file="pressure_msl.nc")

historical_500hpa_temperature

This function allows getting the historical output of global 500hPa temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_temperature
data = historical_500hpa_temperature(initialization_time="2025051706", forecast_hour=4, output_file="500hpa_temperature.nc")

historical_850hpa_temperature

This function allows getting the historical output of global 850hPa temperature forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_850hpa_temperature
data = historical_850hpa_temperature(initialization_time="2025051706", forecast_hour=4, output_file="850hpa_temperature.nc")

historical_500hpa_wind_u

This function allows getting the historical output of global 500hPa u-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_wind_u
data = historical_500hpa_wind_u(initialization_time="2025051706", forecast_hour=4, output_file="500hpa_wind_u.nc")

historical_500hpa_wind_v

This function allows getting the historical output of global 500hPa v-component of wind forecasts. These outputs are saved as a netCDF (.nc) file.

If the requested forecast is not available, a 404 status code will be displayed.

It accepts the following parameters:

Name	Type	Description
initialization_time	string	An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time for which to get the forecast. This looks solely at the date and the hour; minutes and seconds are discarded.
forecast_hour	integer	How many hours after the run time the forecast is valid at.
output_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_wind_v
data = historical_500hpa_wind_v(initialization_time="2025051706", forecast_hour=4, output_file="500hpa_wind_v.nc")

Tropical Cyclones

This endpoint allows getting the predicted ground track of active tropical cyclones.

It accepts the following query string parameters:

Name	Type	Description
initialization_time	string	Optional. An ISO 8601 date string, supporting formats YYYYMMDDHH, YYYY-MM-DDTHH, and YYYY-MM-DDTHH:mm:ss., representing the time at which the forecast was made. This looks solely at the date and the hour; minutes and seconds are discarded. If nothing is provided, the latest forecast is used.
basin	string	Optional. A string indicating the tropical cyclones basins to be filtered in the response. If not set, all tropical cyclones will be included.
output_file	string	Optional. Path to save the response data. If provided, saves the data in .json, .csv, .gpx, .geojson, .kml, .little_r format.

The basin parameter defines specific geographical regions where tropical cyclones are present:

Name	Type	Description
NA	string	North Atlantic Basin spanning from African Coast (20°E) to 140°W and Equator to 90°N.
EP	string	Eastern Pacific Basin spanning from 140°W to 180°W and Equator to 90°N.
WP	string	Western Pacific Basin spanning from 100°E to 180°E and Equator to 60°N.
NI	string	North Indian Ocean Basin spanning from 45°E to 100°E and Equator to 90°N.
SI	string	South-West Indian Ocean Basin spanning from 20°E to 90°E and 40°S to Equator.
AU	string	Australian Region Basin spanning from 90°E to 160°E and 36°S to Equator.
SP	string	South Pacific Basin spanning from 160°E to 120°W and 40°S to Equator.

It returns an object (dictionary) with keys being tropical cyclone IDs and values being arrays of ground track points. Each ground track point is of the form:

Name	Type	Description
latitude	number	The latitude where the tropical cyclone is predicted to be
longitude	number	The longitude where the tropical cyclone is predicted to be
time	string	The ISO8601 timestamp of when this forecast point is valid

Example

Python

from windborne import get_tropical_cyclones
# Get tropical cyclones for the latest available initialization time
cyclones = get_tropical_cyclones()
# Set initialization time, basin and save to file
cyclones = get_tropical_cyclones(
    initialization_time="2024121600",
    basin="NA",
    output_file="output.geojson"
)

Sample Response

{
    "2024121118": [
        {
            "latitude": 55.0,
            "longitude": 163.5,
            "time": "2024-12-12T00:00:00"
        },
        {
            "latitude": 56.0,
            "longitude": 163.75,
            "time": "2024-12-12T06:00:00"
        },
                    . . .
        {
            "latitude": 57.75,
            "longitude": 167.25,
            "time": "2024-12-15T00:00:00"
        },
        {
            "latitude": 58.0,
            "longitude": 165.25,
            "time": "2024-12-15T06:00:00"
        }
    ]
}