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.comwindborne super-observations
Fetches super observations data within a time range and saves them to specified file(s).
It accepts the following arguments:
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. |
-i | integer | Optional. Interval in seconds between polls when a empty page is received (default: 60) |
-b | int | Optional. Size of time buckets in hours. Defaults to 6 hours. |
save_to_file | string | Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc' |
output_format | string | Optional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'. |
-d | string | Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory. |
windborne observations
Fetches observations data within a time range and saves them to specified file(s).
It accepts the following arguments:
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. |
-mt | string | Optional. Filter observations data taken after this time. |
-xt | string | Optional. Filter observations data take prior to this time. |
-id | boolean | Optional. Include observation IDs in response. |
-u | boolean | Optional. Include update timestamps in response. |
-m | string | Optional. Filter observations by mission ID. |
-ml | float | Optional.Minimum latitude boundary. |
-xl | float | Optional. Maximum latitude boundary. |
-mg | float | Optional. Minimum longitude boundary. |
-xg | float | Optional. Maximum longitude boundary. |
-i | integer | Optional. Interval in seconds between polls when a empty page is received (default: 60) |
-b | int | Optional. Size of time buckets in hours. Defaults to 6 hours. |
save_to_file | string | Optional. Saves all data to a single file instead of bucketing. Supported formats are '.csv', '.json', '.little_r' and '.nc' |
output_format | string | Optional. Format to save data in separate files. Can be 'csv', 'json', 'netcdf' or 'little_r'. |
-d | string | Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory. |
windborne poll-super-observations
Polls super observations data continuously saves them to specified files.
It accepts the following arguments:
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. |
-i | integer | Optional. Interval in seconds between polls when a empty page is received (default: 60) |
-b | 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'. |
-d | string | Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory. |
windborne poll-observations
Polls observations data continuously and saves them to specified files.
It accepts the following arguments:
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. |
-mt | string | Optional. Filter observations data taken after this time. |
-xt | string | Optional. Filter observations data take prior to this time. |
-id | boolean | Optional. Include observation IDs in response. |
-u | boolean | Optional. Include update timestamps in response. |
-m | string | Optional. Filter observations by mission ID. |
-ml | float | Optional.Minimum latitude boundary. |
-xl | float | Optional. Maximum latitude boundary. |
-mg | float | Optional. Minimum longitude boundary. |
-xg | float | Optional. Maximum longitude boundary. |
-i | integer | Optional. Interval in seconds between polls when a empty page is received (default: 60) |
-b | 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'. |
-d | string | Optional. Directory path where the separate files should be saved. If not provided, files will be saved in current directory. |
windborne super-observations-page
Retrieves a super observations page based on specified filters.
It accepts the following arguments:
Name | Type | Description |
---|---|---|
since | string | Start time of fetching observations data. |
-mt | string | Optional. Filter observations data taken after this time. |
-xt | string | Optional. Filter observations data take prior to this time. |
-id | boolean | Include observation IDs in response. |
-mn | boolean | Include mission names in response. |
-u | boolean | Include update timestamps in response. |
-m | 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.
windborne observations-page
Retrieves an observations page based on specified filters including geographical bounds.
It accepts the following arguments:
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. |
-id | boolean | Optional. Include observation IDs in response. |
-mn | boolean | Optional. Include mission names in response. |
-ml | float | Optional.Minimum latitude boundary. |
-xl | float | Optional. Maximum latitude boundary. |
-mg | float | Optional. Minimum longitude boundary. |
-xg | float | Optional. Maximum longitude boundary. |
-u | boolean | Optional. Include update timestamps in response. |
-m | string | Optional. Filter observations by mission ID. |
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.
windborne flying-missions
Retrieves a list of currently flying missions.
It accepts the following argument:
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.
windborne launch-site
Retrieves launch site information for a specified mission.
It accepts the following arguments:
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.
windborne predict-path
Fetches the predicted flight path for a given mission currently flying.
It accepts the following arguments:
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.
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:
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.
windborne init_times
This command allows getting available initialization times for point forecasts.
It doesn't accept any arguments.
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
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:
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. |
Tropical Cyclones
This endpoint allows getting the predicted ground track of active tropical cyclones.
It accepts the following arguments:
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. |
-b | 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 |