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. Outputs have a resolution of 0.25 degrees, and are best at a time horizon between <1 and 5 days out.

The WindBorne API is designed to be predictable, performant, and easy to use.

Need access?

Email data@windbornesystems.com
Base URL

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

Example

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:

NameTypeDescription
coordinatesstringA semi-colon separated list of latitude,longitude tuples, eg 37,-121;40.3,-100
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, 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:

NameTypeDescription
forecasts[Forecast]An array of forecasts, in the same order as the input coordinates

A forecast is an array of the form:

NameTypeDescription
temperature_2mnumberThe temperature at 2m above ground level, in degrees Celsius
dewpoint_2mnumberThe dewpoint at 2m above ground level, in degrees Celsius
wind_u_10mnumberThe U component of wind speed at 10m above ground level, in m/s
wind_v_10mnumberThe V component of wind speed at 10m above ground level, in m/s
pressure_mslnumberThe pressure as converted to MSL pressure, in hPa
timestringThe ISO8601 timestamp of when this forecast point is valid

Endpoints
Sample Response

Example: Using the point forecasts API

Here is an example of making a request to the point forecasts API using Python and the wb_get_request function from the Authentication section above.

In this example, we request forecasts for two points: the Golden Gate Bridge and the Statue of Liberty. We request forecasts for 0-2 hours, starting from the latest initialization time.

In the returned response, forecasts are grouped first by point, then by forecast hour. Each forecast hour contains the forecasted values for various weather variables.

Example
Python
Example response

2m temperature

This endpoint allows getting the gridded output of global 2m temperature forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

2m dewpoint

This endpoint allows getting the gridded output of global 2m dewpoint forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

10m u-component of wind

This endpoint allows getting the gridded output of global 10m u-component of wind forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

10m v-component of wind

This endpoint allows getting the gridded output of global 10m v-component of wind forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

Mean sea level pressure

This endpoint allows getting the gridded output of global mean sea level pressure forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

500hPa geopotential

This endpoint allows getting the gridded output of global 500hPa geopotential forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

850hPa temperature

This endpoint allows getting the gridded output of global 850hPa temperature forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude).

This will generally be a redirect to a presigned URL on S3, 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:

NameTypeDescription
timestringAn ISO 8601 date string, 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.

Endpoints

Example: Using the gridded forecast API

Here is an example of making a request to the gridded forecast API using Python, again using the wb_get_request function from the Authentication section above. This example queries for 2m temperature and uses the io library to process the response into a numpy array.

In this example, we request the 2m temperature forecast one week from the time that the script is run, at 00:00 UTC.

The response is a numpy array with shape (720, 1440), which covers the globe at 0.25 degree resolution.

Example
Python
Example response

Historical 2m temperature

This endpoint allows getting the historical output of global 2m temperature forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude). If the requested forecast is not available, a 404 status code will be returned.

It accepts the following query string parameters:

NameTypeDescription
initialization_timeISO stringAn ISO formatted date string representing the initialization time of the forecast.
forecast_hournumberHow many hours after the run time the forecast is valid at.

Endpoints

Historical 500hPa geopotential

This endpoint allows getting the historical output of global 500hPa geopotential forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude). If the requested forecast is not available, a 404 status code will be returned.

This endpoint does not require authentication.

It accepts the following query string parameters:

NameTypeDescription
initialization_timeISO stringAn ISO formatted date string representing the initialization time of the forecast.
forecast_hournumberHow many hours after the run time the forecast is valid at. If unauthenticated, this must be a multiple of 24.

Endpoints

Historical 500hPa wind u

This endpoint allows getting the historical output of global 500hPa wind u forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude). If the requested forecast is not available, a 404 status code will be returned.

It accepts the following query string parameters:

NameTypeDescription
initialization_timeISO stringAn ISO formatted date string representing the initialization time of the forecast.
forecast_hournumberHow many hours after the run time the forecast is valid at.

Endpoints

Historical 500hPa wind v

This endpoint allows getting the historical output of global 500hPa wind v forecasts. These outputs are returned as a .npy file. The file is a numpy array of shape (latitude, longitude). If the requested forecast is not available, a 404 status code will be returned.

It accepts the following query string parameters:

NameTypeDescription
initialization_timeISO stringAn ISO formatted date string representing the initialization time of the forecast.
forecast_hournumberHow many hours after the run time the forecast is valid at.

Endpoints

Tropical Cyclones

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

It accepts the following query string parameters:

NameTypeDescription
initialization_timestringOptional. An ISO 8601 date string, 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 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

Endpoints
Sample Response

Planned endpoints

The model produces a number of outputs that are not yet exposed in the API. These and other endpoints will eventually be added.

  • Precipitation forecasts
  • Cloud cover forecasts
  • Ceiling and visibility forecasts
  • Region forecasts, returning points for a large number of locations (eg population centers, METAR stations) in a single query
  • Historical forecasts