Introduction

Windborne is a pip installable library built to interact with Data and Forecasts APIs, that comes with a Command Line Interface (CLI) out of the box.

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.

To ensure the library works correctly, you must set your Windborne Systems API credentials as environment variables. Follow the steps for your operating system to configure them. This setup will make your API keys available to the library every time you start a new terminal session.

Need access?

Email data@windbornesystems.com
Installation
Python
Set Credentials on macos and linux
Bash
Set Credentials on windows
Bash

windborne super-observations

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

It accepts the following arguments:

NameTypeDescription
start_timestringA 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_timestringOptional. 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.
-iintegerOptional. Interval in seconds between polls when a empty page is received (default: 60)
-bintOptional. Size of time buckets in hours. Defaults to 6 hours.
save_to_filestringOptional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_formatstringOptional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
-dstringOptional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.

Example
Bash

windborne observations

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

It accepts the following arguments:

NameTypeDescription
start_timestringA 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_timestringOptional. 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.
-mtstringOptional. Filter observations data taken after this time.
-xtstringOptional. Filter observations data take prior to this time.
-idbooleanOptional. Include observation IDs in response.
-ubooleanOptional. Include update timestamps in response.
-mstringOptional. Filter observations by mission ID.
-mlfloatOptional.Minimum latitude boundary.
-xlfloatOptional. Maximum latitude boundary.
-mgfloatOptional. Minimum longitude boundary.
-xgfloatOptional. Maximum longitude boundary.
-iintegerOptional. Interval in seconds between polls when a empty page is received (default: 60)
-bintOptional. Size of time buckets in hours. Defaults to 6 hours.
save_to_filestringOptional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc'
output_formatstringOptional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
-dstringOptional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.

Example
Bash

windborne poll-super-observations

Polls super observations data continuously saves them to specified files.

It accepts the following arguments:

NameTypeDescription
start_timestringA 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.
-iintegerOptional. Interval in seconds between polls when a empty page is received (default: 60)
-bintOptional. Size of time buckets in hours. Defaults to 6 hours.
output_formatstringOptional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
-dstringOptional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.

Example
Bash

windborne poll-observations

Polls observations data continuously and saves them to specified files.

It accepts the following arguments:

NameTypeDescription
start_timestringA 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.
-mtstringOptional. Filter observations data taken after this time.
-xtstringOptional. Filter observations data take prior to this time.
-idbooleanOptional. Include observation IDs in response.
-ubooleanOptional. Include update timestamps in response.
-mstringOptional. Filter observations by mission ID.
-mlfloatOptional.Minimum latitude boundary.
-xlfloatOptional. Maximum latitude boundary.
-mgfloatOptional. Minimum longitude boundary.
-xgfloatOptional. Maximum longitude boundary.
-iintegerOptional. Interval in seconds between polls when a empty page is received (default: 60)
-bintOptional. Size of time buckets in hours. Defaults to 6 hours.
output_formatstringOptional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'.
-dstringOptional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory.

Example
Bash

windborne super-observations-page

Retrieves a super observations page based on specified filters.

It accepts the following arguments:

NameTypeDescription
sincestringStart time of fetching observations data.
-mtstringOptional. Filter observations data taken after this time.
-xtstringOptional. Filter observations data take prior to this time.
-idbooleanInclude observation IDs in response.
-mnbooleanInclude mission names in response.
-ubooleanInclude update timestamps in response.
-mstringFilter observations by mission ID.
save_to_filestringOptional. 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
Bash

windborne observations-page

Retrieves an observations page based on specified filters including geographical bounds.

It accepts the following arguments:

NameTypeDescription
sincestringStart time of fetching observations data.
min_timestringOptional. Filter observations data taken after this time.
max_timestringOptional. Filter observations data take prior to this time.
-idbooleanOptional. Include observation IDs in response.
-mnbooleanOptional. Include mission names in response.
-mlfloatOptional.Minimum latitude boundary.
-xlfloatOptional. Maximum latitude boundary.
-mgfloatOptional. Minimum longitude boundary.
-xgfloatOptional. Maximum longitude boundary.
-ubooleanOptional. Include update timestamps in response.
-mstringOptional. Filter observations by mission ID.
save_to_filestringOptional. Save the response data in .csv / .json format.

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

Example
Bash

windborne flying-missions

Retrieves a list of currently flying missions.

It accepts the following argument:

NameTypeDescription
save_to_filestringOptional. 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
Bash

windborne launch-site

Retrieves launch site information for a specified mission.

It accepts the following arguments:

NameTypeDescription
mission_idstringThe mission for which to obtain launch site.
save_to_filestringOptional. 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
Bash

windborne predict-path

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

It accepts the following arguments:

NameTypeDescription
mission_idstringThe mission for which to obtain predicted flight path.
save_to_filestringOptional. 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
Bash

windborne points

This command 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 windborne init_times.

It accepts the following arguments:

NameTypeDescription
coordinatesstringA semi-colon separated list of latitude,longitude tuples, eg 37,-121;40.3,-100
min_forecast_timestringOptional. 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_timestringOptional. 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_hourintegerOptional. The minimum forecast hour to calculate point forecasts for.
max_forecast_hourintegerOptional. The maximum forecast hour to calculate point forecasts for.
initialization_timestringOptional. 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
Bash

windborne init_times

This command allows getting available initialization times for point forecasts.

It doesn't accept any arguments.

It returns the following:

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

Example
Bash

windborne grid_temp_2m

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_wind_u_10m

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_wind_v_10m

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_pressure_msl

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_500hpa_temperature

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_850hpa_temperature

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_500hpa_wind_u

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

windborne grid_500hpa_wind_v

This command 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 arguments:

NameTypeDescription
timestringAn 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_filestringPath to save the file.

EXAMPLE
Python

hist_temp_2m

This command 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 arguments:

NameTypeDescription
timestringAn 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.
hourintegerHow many hours after the run time the forecast is valid at.
save_to_filestringPath to save the file.

EXAMPLE
Bash

hist_500hpa_geopotential

This command allows getting the historical output of global 500hPa geopotential 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 arguments:

NameTypeDescription
timestringAn 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.
hourintegerHow many hours after the run time the forecast is valid at.
save_to_filestringPath to save the file.

EXAMPLE
Bash

hist_500hpa_wind_u

This command 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 arguments:

NameTypeDescription
timestringAn 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.
hourintegerHow many hours after the run time the forecast is valid at.
save_to_filestringPath to save the file.

EXAMPLE
Bash

hist_500hpa_wind_v

This command 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 arguments:

NameTypeDescription
timestringAn 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.
hourintegerHow many hours after the run time the forecast is valid at.
save_to_filestringPath to save the file.

EXAMPLE
Bash

Tropical Cyclones

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

It accepts the following arguments:

NameTypeDescription
initialization_timestringOptional. 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.
-bstringOptional. A string indicating the tropical cyclones basins to be filtered in the response. If not set, all tropical cyclones will be included.
save_to_filestringOptional. 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:

NameTypeDescription
NAstringNorth Atlantic Basin spanning from African Coast (20°E) to 140°W and Equator to 90°N.
EPstringEastern Pacific Basin spanning from 140°W to 180°W and Equator to 90°N.
WPstringWestern Pacific Basin spanning from 100°E to 180°E and Equator to 60°N.
NIstringNorth Indian Ocean Basin spanning from 45°E to 100°E and Equator to 90°N.
SIstringSouth-West Indian Ocean Basin spanning from 20°E to 90°E and 40°S to Equator.
AUstringAustralian Region Basin spanning from 90°E to 160°E and 36°S to Equator.
SPstringSouth 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:

NameTypeDescription
latitudenumberThe latitude where the tropical cyclone is predicted to be
longitudenumberThe longitude where the tropical cyclone is predicted to be
timestringThe ISO8601 timestamp of when this forecast point is valid

Example
Bash