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'

get_point_forecasts

This function allows getting 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.

Available initialization times for point forecasts can be found using get_initialization_times.

It accepts the following parameters:

Name	Type	Description
coordinates	string	A semi-colon separated list of latitude,longitude tuples, 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.

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

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

get_initialization_times

This functions allows getting available initialization times for point forecasts.

It doesn't accept any 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_temperature_2m

This function allows getting the gridded output of global 2m temperature forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_temperature_2m
data = get_temperature_2m(time="2024121600", save_to_file="filename")

get_wind_u_10m

This function allows getting the gridded output of global 10m u-component of wind forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_wind_u_10m
data = get_wind_u_10m(time="2024121600", save_to_file="filename")

get_wind_v_10m

This function allows getting the gridded output of global 10m v-component of wind forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_wind_v_10m
data = get_wind_v_10m(time="2024121600", save_to_file="filename")

get_pressure_msl

This function allows getting the gridded output of global mean sea level pressure forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_pressure_msl
data = get_pressure_msl(time="2024121600", save_to_file="filename")

get_500hpa_temperature

This function allows getting the gridded output of global 500hPa temperature forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_temperature
data = get_500hpa_temperature(time="2024121600", save_to_file="filename")

get_850hpa_temperature

This function allows getting the gridded output of global 850hPa temperature forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_850hpa_temperature
data = get_850hpa_temperature(time="2024121600", save_to_file="filename")

get_500hpa_wind_u

This function allows getting the gridded output of global 500hPa u-component of wind forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_wind_u
data = get_500hpa_wind_u(time="2024121600", save_to_file="filename")

get_500hpa_wind_v

This function allows getting the gridded output of global 500hPa v-component of wind forecasts. These outputs are returned 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.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import get_500hpa_wind_v
data = get_500hpa_wind_v(time="2024121600", save_to_file="filename")

historical_temperature_2m

This function allows getting the historical output of global 2m temperature forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_temperature_2m
data = historical_temperature_2m(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_wind_u_10m

This function allows getting the historical output of global 10m u-component of wind forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_wind_u_10m
data = historical_wind_u_10m(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_wind_v_10m

This function allows getting the historical output of global 10m v-component of wind forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_wind_v_10m
data = historical_wind_v_10m(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_pressure_msl

This function allows getting the historical output of global mean sea level pressure forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_pressure_msl
data = historical_pressure_msl(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_500hpa_temperature

This function allows getting the historical output of global 500hPa temperature forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_temperature
data = historical_500hpa_temperature(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_850hpa_temperature

This function allows getting the historical output of global 850hPa temperature forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_850hpa_temperature
data = historical_850hpa_temperature(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_500hpa_wind_u

This function allows getting the historical output of global 500hPa u-component of wind forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_wind_u
data = historical_500hpa_wind_u(time="2024121600", forecast_hour=4, save_to_file="filename")

historical_500hpa_wind_v

This function allows getting the historical output of global 500hPa v-component of wind forecasts. These outputs are returned 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
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. If there is no forecast available within an hour of the requested time, it will return a 404.
hour	integer	How many hours after the run time the forecast is valid at.
save_to_file	string	Path to save the file.

EXAMPLE

Python

from windborne import historical_500hpa_wind_v
data = historical_500hpa_wind_v(time="2024121600", forecast_hour=4, save_to_file="filename")

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.
save_to_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",
    save_to_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"
        }
    ]
}