WindBorne Systems API Reference

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

https://forecasts.windbornesystems.com/api/v1

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

import os
import time
# install dependencies with `pip3 install requests`
import requests


def wb_get_request(url):
    """
    Make a GET request to WindBorne, authorizing with WindBorne correctly
    """

    client_id = os.environ['WB_CLIENT_ID']  # Make sure to set this!
    api_key = os.environ['WB_API_KEY']   # Make sure to set this!

    # make the request, checking the status code to make sure it succeeded
    response = requests.get(url, auth=(client_id, api_key))
    response.raise_for_status()

    # return the response 
    return response

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_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

Endpoints

    GET /points.json
    GET https://forecasts.windbornesystems.com/api/v1/points.json

Sample Response

{
  "forecasts": [
    [
      {
        "temperature_2m": 15.5,
        "dewpoint_2m": 10.5,
        "wind_u_10m": 5.5,
        "wind_v_10m": 5.5,
        "pressure_msl": 1013.5,
        "latitude": 37.819754,
        "longitude": -122.477847,
        "time": "2024-04-01T00:00:00Z"
      },
      {
        "temperature_2m": 15.5,
        "dewpoint_2m": 10.5,
        "wind_u_10m": 5.5,
        "wind_v_10m": 5.5,
        "pressure_msl": 1013.5,
        "latitude": 37.819754,
        "longitude": -122.477847,
        "time": "2024-04-01T01:00:00Z"
      },
      {
        "temperature_2m": 15.5,
        "dewpoint_2m": 10.5,
        "wind_u_10m": 5.5,
        "wind_v_10m": 5.5,
        "pressure_msl": 1013.5,
        "latitude": 37.819754,
        "longitude": -122.477847,
        "time": "2024-04-01T02:00:00Z"
      }
    ]
  ],
  "initialization_time": "2024-04-01T00:00:00Z"
}

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

import os
import requests

def wb_get_point_forecast(params):
    """
    Make a GET request to the WindBorne point forecast API using wb_get_request
    """
    base_url = "https://forecasts.windbornesystems.com/api/v1/points.json"
    
    # Convert the parameters dictionary to query string using requests' utility
    response = wb_get_request(f"{base_url}?{requests.compat.urlencode(params)}")
    return response.json()

params = {
    "coordinates": "37.819754,-122.477847;40.689672,-74.045847", # Golden Gate Bridge and Statue of Liberty
    "min_forecast_hour": 0,
    "max_forecast_hour": 2
}

result = wb_get_point_forecast(params)
print(result)

Example response

{'forecasts': [[{'dewpoint_2m': 8.3, 'latitude': 37.819754, 'longitude': -122.477847, 'precipitation': 0.0, 'pressure_msl': 1019.8, 'temperature_2m': 12.1, 'time': '2024-12-03T12:00:00+00:00', 'wind_u_10m': -1.1, 'wind_v_10m': -3.4}, {'dewpoint_2m': 7.9, 'latitude': 37.819754, 'longitude': -122.477847, 'precipitation': 0.0, 'pressure_msl': 1020.1, 'temperature_2m': 11.7, 'time': '2024-12-03T13:00:00+00:00', 'wind_u_10m': -0.8, 'wind_v_10m': -5.5}, {'dewpoint_2m': 7.6, 'latitude': 37.819754, 'longitude': -122.477847, 'precipitation': 0.0, 'pressure_msl': 1020.2, 'temperature_2m': 11.7, 'time': '2024-12-03T14:00:00+00:00', 'wind_u_10m': -0.7, 'wind_v_10m': -5.7}], [{'dewpoint_2m': -5.8, 'latitude': 40.689672, 'longitude': -74.045847, 'precipitation': 0.0, 'pressure_msl': 1024.4, 'temperature_2m': -0.6, 'time': '2024-12-03T12:00:00+00:00', 'wind_u_10m': 4.7, 'wind_v_10m': -3.3}, {'dewpoint_2m': -5.1, 'latitude': 40.689672, 'longitude': -74.045847, 'precipitation': 0.0, 'pressure_msl': 1024.6, 'temperature_2m': -0.0, 'time': '2024-12-03T13:00:00+00:00', 'wind_u_10m': 4.6, 'wind_v_10m': -2.5}, {'dewpoint_2m': -4.8, 'latitude': 40.689672, 'longitude': -74.045847, 'precipitation': 0.0, 'pressure_msl': 1025.1, 'temperature_2m': 1.1, 'time': '2024-12-03T14:00:00+00:00', 'wind_u_10m': 4.5, 'wind_v_10m': -2.6}]], 'initialization_time': '2024-12-03T12:00:00+00:00'}

Initialization Times

This endpoint allows getting the available initialization times for point forecasts.

It doesn't accept any query string 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.

Endpoints

    GET /initialization_times.json
    GET https://forecasts.windbornesystems.com/api/v1/initialization_times.json

Sample Response

{
    'available': [
        '2024-12-10T00:00:00+00:00',
        '2024-12-09T18:00:00+00:00',
        '2024-12-09T12:00:00+00:00',
        '2024-12-09T06:00:00+00:00',
        '2024-12-09T00:00:00+00:00',
        '2024-12-08T18:00:00+00:00',
        '2024-12-08T12:00:00+00:00',
        '2024-12-08T06:00:00+00:00',
        '2024-12-08T00:00:00+00:00',
        '2024-12-07T18:00:00+00:00',
                  . . .
        '2024-12-01T12:00:00+00:00',
        '2024-12-01T06:00:00+00:00',
        '2024-12-01T00:00:00+00:00',
        '2024-11-30T18:00:00+00:00',
        '2024-11-30T12:00:00+00:00',
        '2024-11-30T06:00:00+00:00',
        '2024-11-30T00:00:00+00:00'
    ],
    'latest': '2024-12-10T00:00:00+00:00'
}

Example: Using the initialization times forecasts API

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

In this example, we request to get the available initialization times for point forecasts.

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.

Example

Python

import os
import requests

def wb_get_initialization_times():
    """
    Make a GET request to the WindBorne initialization times forecast API using wb_get_request
    """
    base_url = "https://forecasts.windbornesystems.com/api/v1/initialization_times.json"
    
    response = wb_get_request(base_url)
    return response.json()

result = wb_get_initialization_times()
print(result)

Example response

{'available': ['2024-12-10T00:00:00+00:00', '2024-12-09T18:00:00+00:00', '2024-12-09T12:00:00+00:00', '2024-12-09T06:00:00+00:00', '2024-12-09T00:00:00+00:00', '2024-12-08T18:00:00+00:00', '2024-12-08T12:00:00+00:00', '2024-12-08T06:00:00+00:00', '2024-12-08T00:00:00+00:00', '2024-12-07T18:00:00+00:00', '2024-12-07T12:00:00+00:00', '2024-12-07T06:00:00+00:00', '2024-12-07T00:00:00+00:00', '2024-12-06T18:00:00+00:00', '2024-12-06T12:00:00+00:00', '2024-12-06T06:00:00+00:00', '2024-12-06T00:00:00+00:00', '2024-12-05T18:00:00+00:00', '2024-12-05T12:00:00+00:00', '2024-12-05T06:00:00+00:00', '2024-12-05T00:00:00+00:00', '2024-12-04T18:00:00+00:00', '2024-12-04T12:00:00+00:00', '2024-12-04T06:00:00+00:00', '2024-12-04T00:00:00+00:00', '2024-12-03T18:00:00+00:00', '2024-12-03T12:00:00+00:00', '2024-12-03T06:00:00+00:00', '2024-12-03T00:00:00+00:00', '2024-12-02T18:00:00+00:00', '2024-12-02T12:00:00+00:00', '2024-12-02T06:00:00+00:00', '2024-12-02T00:00:00+00:00', '2024-12-01T18:00:00+00:00', '2024-12-01T12:00:00+00:00', '2024-12-01T06:00:00+00:00', '2024-12-01T00:00:00+00:00', '2024-11-30T18:00:00+00:00', '2024-11-30T12:00:00+00:00', '2024-11-30T06:00:00+00:00', '2024-11-30T00:00:00+00:00'], 'latest': '2024-12-10T00:00:00+00:00'}

2m temperature

This endpoint allows getting the gridded output of global 2m temperature forecasts. These outputs are returned as a netCDF (.nc) file.

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:

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.

Endpoints

    GET /gridded/temperature_2m
    GET https://forecasts.windbornesystems.com/api/v1/gridded/temperature_2m

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 netCDF (.nc) file.

It accepts the following query string 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.

Endpoints

    GET /gridded/wind_u_10m
    GET https://forecasts.windbornesystems.com/api/v1/gridded/wind_u_10m

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 netCDF (.nc) file.

It accepts the following query string 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.

Endpoints

    GET /gridded/wind_v_10m
    GET https://forecasts.windbornesystems.com/api/v1/gridded/wind_v_10m

Mean sea level pressure

This endpoint allows getting the gridded output of global mean sea level pressure forecasts. These outputs are returned as a netCDF (.nc) file.

It accepts the following query string 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.

Endpoints

    GET /gridded/pressure_msl
    GET https://forecasts.windbornesystems.com/api/v1/gridded/pressure_msl

500hPa geopotential

This endpoint allows getting the gridded output of global 500hPa geopotential forecasts. These outputs are returned as a netCDF (.nc) file.

It accepts the following query string 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.

Endpoints

    GET /gridded/500/geopotential
    GET https://forecasts.windbornesystems.com/api/v1/gridded/500/geopotential

850hPa temperature

This endpoint allows getting the gridded output of global 850hPa temperature forecasts. These outputs are returned as a netCDF (.nc) file.

It accepts the following query string 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.

Endpoints

    GET /gridded/850/temperature
    GET https://forecasts.windbornesystems.com/api/v1/gridded/850/temperature

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 and xarray libraries to process the response into an xarray dataset.

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

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

Python

from datetime import datetime, timedelta, timezone
import io
import os
import requests
import xarray as xr

def wb_get_gridded_2t(params):
    """
    Make a GET request to the WindBorne gridded forecast API for 2m temperature using wb_get_request
    """
    base_url = "https://forecasts.windbornesystems.com/api/v1/gridded/temperature_2m"

    # Convert the parameters dictionary to query string and make the request
    req = f"{base_url}?{requests.compat.urlencode(params)}"
    response = wb_get_request(f"{base_url}?{requests.compat.urlencode(params)}")

    # Read the content as a netCDF dataset
    nc_file = io.BytesIO(response.content)
    return xr.open_dataset(nc_file)

now = datetime.now(tz=timezone.utc)
one_week_from_now = now + timedelta(days=7)
params = {"time": one_week_from_now.strftime("%Y-%m-%dT00:00:00Z")}
result = wb_get_gridded_2t(params)
print("Dataset: ", result, "\n")
print("Units: ", result["temperature_2m"].units, "\n")
print("Values: ", result["temperature_2m"].values)

Example response

Dataset:  <xarray.Dataset> Size: 4MB
Dimensions:         (lat: 720, lon: 1440)
Dimensions without coordinates: lat, lon
Data variables:
    latitude        (lat) float32 3kB ...
    longitude       (lon) float32 6kB ...
    temperature_2m  (lat, lon) float32 4MB ...
Attributes:
    initialization_time:  2024-12-11T18:00:00+00:00
    forecast_hour:        174
    description:          Gridded forecast data for temperature_2m
    source:               WindBorne WeatherMesh Qfiz 

Units:  K 

Values:  [[250.7576  250.72754 250.7576  ... 251.08824 251.20847 250.93794]
 [250.6073  250.69748 250.6073  ... 250.54718 250.6073  250.51712]
 [250.2466  250.457   250.39688 ... 250.27666 250.2466  250.15642]
 ...
 [245.5274  245.5274  245.49734 ... 245.55746 245.5274  245.70776]
 [245.5274  245.49734 245.3771  ... 245.49734 245.49734 245.58752]
 [245.55746 245.5274  245.40717 ... 245.49734 245.55746 245.58752]]

Historical 2m temperature

This endpoint 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 returned.

It accepts the following query string parameters:

Name	Type	Description
initialization_time	ISO string	An ISO formatted date string representing the initialization time of the forecast.
forecast_hour	number	How many hours after the run time the forecast is valid at.

Endpoints

    GET /gridded/historical/temperature_2m
    GET https://forecasts.windbornesystems.com/api/v1/gridded/historical/temperature_2m

Historical 500hPa geopotential

This endpoint 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 returned.

This endpoint does not require authentication.

It accepts the following query string parameters:

Name	Type	Description
initialization_time	ISO string	An ISO formatted date string representing the initialization time of the forecast.
forecast_hour	number	How many hours after the run time the forecast is valid at. If unauthenticated, this must be a multiple of 24.

Endpoints

    GET /gridded/historical/500/geopotential
    GET https://forecasts.windbornesystems.com/api/v1/gridded/historical/500/geopotential

Historical 500hPa wind u

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

It accepts the following query string parameters:

Name	Type	Description
initialization_time	ISO string	An ISO formatted date string representing the initialization time of the forecast.
forecast_hour	number	How many hours after the run time the forecast is valid at.

Endpoints

    GET /gridded/historical/500/wind_u
    GET https://forecasts.windbornesystems.com/api/v1/gridded/historical/500/wind_u

Historical 500hPa wind v

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

It accepts the following query string parameters:

Name	Type	Description
initialization_time	ISO string	An ISO formatted date string representing the initialization time of the forecast.
forecast_hour	number	How many hours after the run time the forecast is valid at.

Endpoints

    GET /gridded/historical/500/wind_v
    GET https://forecasts.windbornesystems.com/api/v1/gridded/historical/500/wind_v

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

Endpoints

    GET /tropical_cyclones
    GET https://forecasts.windbornesystems.com/api/v1/tropical_cyclones

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"
        }
    ]
}

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.

Example

Python

import os
import requests

def wb_get_tropical_cyclones(params):
    """
    Make a GET request to the WindBorne gridded forecast API for tropical cyclones using wb_get_request
    """
    base_url = "https://forecasts.windbornesystems.com/api/v1/tropical_cyclones"

    # Convert the parameters dictionary to query string using requests' utility
    response = wb_get_request(f"{base_url}?{requests.compat.urlencode(params)}")

    return response.json()

params = {
    "initialization_time": "2024-11-18T06:00:00",
    "basin": "EP"
}

result = wb_get_tropical_cyclones(params)
print(result)

Example response

{
    "CyNH00032024": [
        {
            "latitude": 42.0,
            "longitude": -150.25,
            "time": "2024-11-19T00:00:00"
        },
        {
            "latitude": 41.5,
            "longitude": -143.25,
            "time": "2024-11-19T06:00:00"
        },
                    . . .
        {
            "latitude": 47.0,
            "longitude": -140.25,
            "time": "2024-11-22T06:00:00"
        },
        {
            "latitude": 45.0,
            "longitude": -141.25,
            "time": "2024-11-22T12:00:00"
        }
    ]
}

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