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_full

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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025022108", 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="2025021806", 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="2025021806", 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="2025021806", 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="2025021806", 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="2025021806", 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="2025021806", 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="2025021806", 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="2025021806", 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"
        }
    ]
}