Introduction
WeatherMesh is the world’s most accurate AI weather model, and is used operationally to guide the largest balloon constellation in the world.
WeatherMesh currently predicts surface temperature, pressure, winds, precipitation, and radiation; and then geopotential, temperature, winds, and moisture at 28 pressure levels. It has both a deterministic and and ensemble forecast system, each with a resolution of 0.25 degrees. It also has a specialized point-forecasting model for arbitrary locations in between grid points.
The WindBorne API is designed to be predictable, performant, and easy to use.
Need access?
Email data@windbornesystems.comPython Library
The easiest way to access data is through our command line interface. This allows querying of all endpoints and saving to files.
You can also use the python library directly. See the python library documentation for more information.
Authentication
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.
You should have an API key and a client id. Conceptually, you can think of your client id as a username and your API key as your password. You should make sure to keep your API key safe and secure.
To authenticate, pass HTTP basic auth headers in the GET request with username YOUR_CLIENT_ID
and password YOUR_API_KEY
. This follows RFC 7617; ie, as is standard, the credentials are colon-separated then base-64 encoded; many HTTP libraries will do this for you.
Using JWTs from a key server ▸
Point forecasts
This endpoint 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.
These forecasts are at hourly resolution out to 5 days and then 6-hourly beyond that.
It accepts the following query string 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 following:
Name | Type | Description |
---|---|---|
forecasts | [Forecast] | An array of forecasts, in the same order as the input coordinates |
initialization_time | string | The ISO 8601 date string of the forecast initialization time |
A forecast is an array of the form:
Name | Type | Description |
---|---|---|
temperature_2m | number | The temperature at 2m above ground level, in degrees Celsius |
dewpoint_2m | number | The dewpoint at 2m above ground level, in degrees Celsius |
wind_u_10m | number | The U component of wind speed at 10m above ground level, in m/s |
wind_v_10m | number | The V component of wind speed at 10m above ground level, in m/s |
pressure_msl | number | The pressure as converted to MSL pressure, in hPa |
latitude | number | The latitude of the point, between -90 and 90 |
longitude | number | The longitude of the point, between -180 and 180 |
time | string | The ISO8601 timestamp of when this forecast point is valid |
Example: Using the point forecasts API
In this example, we request forecasts for two points (the Golden Gate Bridge and the Statue of Liberty) using the wb_get_request
function from the Authentication section above. We request forecasts for 0-2 hours, starting from the latest initialization time.
You may consider instead using the get_point_forecasts function from the pip library.
The response groups forecasts first by point, then by forecast hour. Each forecast hour contains the forecasted values for various weather variables.
Gridded forecast, single variable
This endpoint allows getting the gridded output of global forecasts for a single variable. The variable is set in the url; for a surface variable, the endpoint is /gridded/{variable}
whereas for an upper-level variable, the endpoint is /gridded/{level}/{variable}
. These outputs are returned as a netCDF (.nc) file.
This endpoint can be used for both the latest forecast (by specifying time
) or for fetching historical forecasts (by specifying initialization_time
and forecast_hour
). Available initialization times and forecast hours can be found from the forecast hours endpoint.
Valid variables are:
Name | Description | Type |
---|---|---|
temperature_2m | 2m temperature | surface |
wind_u_10m | 10m u-component of wind | surface |
wind_v_10m | 10m v-component of wind | surface |
pressure_msl | Mean sea level pressure | surface |
geopotential | Geopotential (not geopotential height) | upper-level |
temperature | Temperature | upper-level |
wind_u | U-component of wind | upper-level |
wind_v | V-component of wind | upper-level |
This will generally be a redirect to a presigned URL on R2, so you will need to follow the redirect to get the file. Only in the short time it takes for the file to be uploaded will it be served directly.
It accepts the following query string parameters:
Name | Type | Description |
---|---|---|
time | string | The time at which the forecast is valid. This may be of format ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. 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. Alternatively, you can specify initialization_time and forecast_hour . |
initialization_time | string | The initialization time for the forecast. This may be of format ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. This looks solely at the date and the hour; minutes and seconds are discarded. Must be used in conjunction with forecast_hour . Cannot be used with time . |
forecast_hour | number | An integer representing the number of hours from the initialization_time for which to get the forecast. For example, if initialization_time is 2023-01-01T00:00:00 and forecast_hour is 6 , the forecast will be for 2023-01-01T06:00:00 . Must be used in conjunction with initialization_time . Cannot be used with time . |
ens_member | string | The ensemble member to get initialization times for. Can be mean or a number between 1 and 25. Cannot be used with intracycle . |
intracycle | boolean | Whether to return initialization times 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 ens_member . |
Gridded forecast, all variables at all levels
This command allows getting the full gridded output of global forecasts, including data for all variables at all levels. These outputs are returned as a netCDF (.nc) file.
This will generally be a redirect to a presigned URL on R2, so you will need to follow the redirect to get the file. Only in the short time it takes for the file to be uploaded will it be served directly.
It accepts the following query string parameters:
Name | Type | Description |
---|---|---|
time | string | The time at which the forecast is valid. This may be of format ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. 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. Alternatively, you can specify initialization_time and forecast_hour . |
initialization_time | string | The initialization time for the forecast. This may be of format ISO 8601, YYYYMMDDHH, or YYYY-MM-DDTHH. This looks solely at the date and the hour; minutes and seconds are discarded. Must be used in conjunction with forecast_hour . Cannot be used with time . |
forecast_hour | number | An integer representing the number of hours from the initialization_time for which to get the forecast. For example, if initialization_time is 2023-01-01T00:00:00 and forecast_hour is 6 , the forecast will be for 2023-01-01T06:00:00 . Must be used in conjunction with initialization_time . Cannot be used with time . |
ens_member | string | The ensemble member to get initialization times for. Can be mean or a number between 1 and 25. Cannot be used with intracycle . |
intracycle | boolean | Whether to return initialization times 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 ens_member . |
Example: Using the gridded forecast API
In this example, we request the 2m temperature forecast one week from the time that the script is run, at 00:00 UTC. We use the wb_get_request
function from the Authentication section above.
You may consider instead using the get_gridded_forecast function from the pip library.
This example queries for 2m temperature and uses the io and xarray libraries to process the response into an xarray dataset. The returned dataset has three variables: latitude, longitude, and temperature_2m. The latitude and longitude variables are 1D arrays of the latitudes and longitudes of the grid points, respectively. The temperature_2m variable is a 2D array of the forecasted 2 meter temperatures at each grid point. The dataset contains additional metadata in the form of attributes.
Example: Fetching a historical gridded forecast
In this example, we request the 2m temperature forecast for a prior initialization time. In this specific case, we request the forecast initialized the previous day at 00:00 UTC and forecasted for 48 hours beyond that. We use the wb_get_request
function from the Authentication section above.
You may consider instead using the get_gridded_forecast function from the pip library.
This example queries for 2m temperature and uses the io and xarray libraries to process the response into an xarray dataset. The returned dataset has three variables: latitude, longitude, and temperature_2m. The latitude and longitude variables are 1D arrays of the latitudes and longitudes of the grid points, respectively. The temperature_2m variable is a 2D array of the forecasted 2 meter temperatures at each grid point. The dataset contains additional metadata in the form of attributes.
Initialization Times
This endpoint allows getting the available initialization times for point forecasts and other endpoints.
It can optionally accept the following query string parameters:
Name | Type | Description |
---|---|---|
ens_member | string | The ensemble member to get initialization times for. Can be mean or a number between 1 and 25. Cannot be used with intracycle . |
intracycle | boolean | Whether to return initialization times 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 ens_member . |
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: Using the initialization times API
In this example, we request the available initialization times for point forecasts using the wb_get_request
function from the Authentication section above.
You may consider instead using the get_initialization_times function from the pip library.
The response includes a list of available initialization times formatted as ISO8601 timestamps. Initialization times are ordered from newest to oldest, with an additional entry indicating the latest initialization time.
Generation Times
This endpoint provides the creation times for each forecast hour output file, allowing you to track when specific forecast data became available.
It can optionally accept the following query string parameters:
Name | Type | Description |
---|---|---|
ens_member | string | The ensemble member to get generation times for. Can be mean or a number between 1 and 25. Cannot be used with intracycle . |
intracycle | boolean | Whether to return generation times 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 ens_member . |
It returns a nested dictionary structure:
Name | Type | Description |
---|---|---|
initialization_time | object | The top-level keys are ISO8601 timestamps of initialization times, ordered from newest to oldest. Each initialization time maps to an object containing forecast hour generation times. |
forecast_hour | string | Within each initialization time object, the keys are forecast hours (as strings), and the values are ISO8601 timestamps indicating when that forecast hour's output file was created. |
This endpoint is useful for:
- Monitoring the progress of forecast generation
- Determining data freshness and latency
- Identifying when specific forecast hours become available
- Tracking the temporal pattern of model output generation
Forecast Hours
This endpoint allows getting the available forecast hours for different model initialization times. This may include initialization times that are not included in the initialization times API that represent forecasts that are still in the process of being generated.
It can optionally accept the following query string parameters:
Name | Type | Description |
---|---|---|
ens_member | string | The ensemble member to get forecast hours for. Can be mean or a number between 1 and 25. Cannot be used with intracycle . |
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 ens_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. |
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. |
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: Using the tropical cyclones forecast API
Here is an example of making a request to the tropical cyclones forecast API using Python, again using the wb_get_request
function from the Authentication section above. This example queries for tropical cyclones and saves the response in a json file.
In this example, we request the tropical cyclones within Eastern Pacific basin for an initialization time .
The response is an object (dictionary) with keys being tropical cyclone IDs and values being arrays of ground track points.