Introduction

The BlueSky API uses the REST framework and returns JSON-encoded response bodies with standard HTTP response codes. The following sections give an overview of authentication methods and endpoints.

Base URL

The endpoints below are given relative to this URL:

https://api.blueskyapi.io

Install the blueskyapi package:

pip install blueskyapi

You can find detailed documentation for it here.

Authentication

The BlueSky API uses API keys for authentication. You can manage these in the API keys section of the user menu.

To authenticate an API call set the Authorization header to Bearer [your-key] (replace [your-key] with one of your API keys).

The Python client library does this for you.
export BLUESKY_TOKEN="your-api-key" export BLUESKY_AUTH="Authorization: Bearer $BLUESKY_TOKEN" curl -H "$BLUESKY_AUTH" [apiHost]/test
import requests bluesky_api_key = 'your-api-key' bluesky = requests.Session() bluesky.headers.update({ 'Authorization': f'Bearer {bluesky_api_key}' })
import blueskyapi blueskyapi.default_config.api_key = 'your-api-key' client = blueskyapi.Client() # or you can specify the API key for a single client: client = blueskyapi.Client(api_key='your-api-key')

Latest Forecast

GET
/forecasts/latest

This endpoint gives you access to the latest forecast.

Parameters

lat
Required

The latitude of the location for which you need forecast data. Values range from -90 (southpole) to 90 (northpole).

lon
Required

The longitude of the location for which you need forecast data. Values range from 0 to 360.

forecast_distances
Optional

Format: Comma separated list of integers

The forecast distances is the period between the forecast moment to the moment for which the forecast is made.

By default, forecasts for all available distances are returned.

columns
Optional

Which variables you need forecasts for. By default, all available variables are returned.

For a list of available variables see the data documentation.

dataset
Optional

Which dataset to query (only for users on the Professional plan). Defaults to the dataset available on the free plan.

Response

The response is a JSON object that can be directly read by pandas.read_json. All timestamps are in UTC.

curl -H "$BLUESKY_AUTH" \ [apiHost]/forecasts/latest?lat=53.5&lon=13.5
import pandas as pd response = bluesky.get( '[apiHost]/forecasts/latest', params=dict( lat=52.5, lon=13.5, forecast_distances="0,12,24", columns="apparent_temperature_at_2m,temperature_at_100m", ) ) data = pd.read_json(response.content)
data = client.latest_forecast( lat=52.5, lon=13.5, forecast_distances=[0, 12, 24], columns=["apparent_temperature_at_2m", "temperature_at_100m"], )
[ { "forecast_moment": "2023-01-07T00:00:00Z", "forecast_distance": 0, "apparent_temperature_at_2m": 285.12, "temperature_at_100m": 285.16 }, { "forecast_moment": "2023-01-07T00:00:00Z", "forecast_distance": 12, "apparent_temperature_at_2m": 285.76, "temperature_at_100m": 285.62 }, ... ]
forecast_moment forecast_distance apparent_temperature_at_2m temperature_at_100m 0 2023-01-07 00:00:00+00:00 0 285.12 285.16 1 2023-01-07 00:00:00+00:00 12 285.76 285.62 2 2023-01-07 00:00:00+00:00 24 284.16 284.06

Historical Forecasts

GET
/forecasts/history

This endpoint gives you access to current and past forecasts.

Parameters

This endpoint shares all parameters of the Latest Forecast endpoint and adds two more to specify the range of historical data:

min_forecast_moment
Optional

Timestamp of the first forecast moment you want to retrieve, in UTC. The forecast moment is the point in time at which the forecast was made. We provide four forecast moments per day, at 0:00, 6:00, 12:00, and 18:00 UTC.

By default, all forecasts from the first available date are returned.

max_forecast_moment
Optional

Timestamp of the last forecast moment you want to retrieve, in UTC.

By default, all forecasts up to the latest one are returned.

Response

The response is a JSON object that can be directly read by pandas.read_json. All timestamps are in UTC.

curl -H "$BLUESKY_AUTH" \ [apiHost]/forecasts/history?lat=53.5&lon=13.5&min_forecast_moment=[moment7dAgo]&max_forecast_moment=[moment1dAgo]
import pandas as pd response = bluesky.get( '[apiHost]/forecasts/history', params=dict( lat=52.5, lon=13.5, min_forecast_moment="[moment7dAgo]", max_forecast_moment="[moment1dAgo]", forecast_distances="0,12,24", columns="apparent_temperature_at_2m,temperature_at_100m", ) ) data = pd.read_json(response.content)
data = client.forecast_history( lat=52.5, lon=13.5, min_forecast_moment="[moment7dAgo]", max_forecast_moment="[moment1dAgo]", forecast_distances=[0, 12, 24], columns=["apparent_temperature_at_2m", "temperature_at_100m"], )
[ { "forecast_moment": "[moment7dAgo]Z", "forecast_distance": 0, "apparent_temperature_at_2m": 271.04, "temperature_at_100m": 274.84 }, { "forecast_moment": "[moment7dAgo]Z", "forecast_distance": 12, "apparent_temperature_at_2m": 273.12, "temperature_at_100m": 275.31 }, ... ]
forecast_moment forecast_distance apparent_temperature_at_2m temperature_at_100m 0 2021-12-20 00:00:00+00:00 0 271.04 274.84 1 2021-12-20 00:00:00+00:00 12 273.12 275.31 2 2021-12-20 00:00:00+00:00 24 270.72 272.81 3 2021-12-20 06:00:00+00:00 0 270.24 274.22 4 2021-12-20 06:00:00+00:00 12 271.36 273.91 5 2021-12-20 06:00:00+00:00 24 269.76 272.34 6 2021-12-20 12:00:00+00:00 0 273.12 275.47 7 2021-12-20 12:00:00+00:00 12 271.36 273.12 8 2021-12-20 12:00:00+00:00 24 274.08 273.75 9 2021-12-20 18:00:00+00:00 0 271.52 273.75 10 2021-12-20 18:00:00+00:00 12 271.04 272.50 11 2021-12-20 18:00:00+00:00 24 274.72 272.66