blueskyapi.io Python client

blueskyapi.io provides easy access to current and historical weather forecast data. This library provides simple access to the API using Python 3.7+.

For more detailed information about the endpoints and available variables see the documentation on blueskyapi.io.

Installation

You can install it using any of the common package managers:

$ pip install blueskyapi
$ poetry add blueskyapi
$ pipenv install blueskyapi

Example

Here’s a quick example to get you started, no API key needed:

import blueskyapi

client = blueskyapi.Client()
berlin_forecast = client.latest_forecast(53.5, 13.5)

berlin_forecast
#              forecast_moment  forecast_distance  apparent_temperature_at_2m  categorical_rain_at_surface  ...  wind_v_at_80m  wind_v_at_100m  wind_v_at_max_wind  visibility_at_surface
# 0  2021-12-29 06:00:00+00:00                  0                      272.00                            1  ...           2.33            2.33              -14.98                24128.0
# 1  2021-12-29 06:00:00+00:00                  3                      272.16                            1  ...           2.10            2.10              -17.45                 4848.0
# 2  2021-12-29 06:00:00+00:00                  6                      271.84                            0  ...          -1.23           -1.23              -28.05                   95.2
# ...

Client

class blueskyapi.Client(api_key=None, base_url=None)

Client to interact with the blueskyapi.io API.

Data is returned as a pandas.DataFrame and includes the columns forecast_moment (UTC datetimes) and forecast_distances (integers), as well as any columns you select using the columns parameter.

Parameters
  • api_key (typing.Optional[str]) – Your API key (create one here).

  • base_url (typing.Optional[str]) – Only for testing purposes. Don’t use this parameter.

forecast_history(lat, lon, min_forecast_moment, max_forecast_moment=None, forecast_distances=None, columns=None)[source]

Obtain historical forecasts.

Parameters
  • lat (float) – Latitude for which to fetch the forecasts.

  • lon (float) – Longitude for which to fetch the forecasts.

  • min_forecast_moment (typing.Union[datetime.datetime, str]) – The first forecast moment to include.

  • max_forecast_moment (typing.Union[datetime.datetime, str, None]) – The last forecast moment to include.

  • forecast_distances (typing.Optional[typing.Iterable[int]]) – Forecast distances to return data for (hours from forecast_moment).

  • columns (typing.Optional[typing.Iterable[str]]) – Which variables to fetch (see this page for available variables).

Return type

pandas.core.frame.DataFrame

latest_forecast(lat, lon, forecast_distances=None, columns=None)[source]

Obtain the latest forecast.

Parameters
  • lat (float) – Latitude for which to fetch the forecast.

  • lon (float) – Longitude for which to fetch the forecast.

  • forecast_distances (typing.Optional[typing.Iterable[int]]) – Forecast distances to fetch data for (hours from forecast_moment).

  • columns (typing.Optional[typing.Iterable[str]]) –

    Which variables to fetch (see this page for available variables).

Return type

pandas.core.frame.DataFrame

Default configuration

Client instances created without an explicit API key will use the one specified in blueskyapi.default_config.api_key:

import blueskyapi

blueskyapi.default_config.api_key = "your-api-key"

client = blueskyapi.Client()
client.api_key # => "your-api-key"

Errors

exception blueskyapi.errors.Error[source]

Bases: Exception

Base class for all blueskyapi errors.

exception blueskyapi.errors.InvalidApiKey(response)[source]

Bases: blueskyapi.errors.RequestError

Raised when the given API key can’t be found.

Check your API keys to make sure you’re using a valid key.

exception blueskyapi.errors.OverRateLimit(response)[source]

Bases: blueskyapi.errors.RequestError

Raised when a request exceeds the rate limit.

The error message includes information about your current limits and used quotas.

The limit can be increased by using an API key. Even the free plan includes a much higher limit than using the API without an API key. You can create an API key here.

exception blueskyapi.errors.RequestError(response)[source]

Bases: blueskyapi.errors.Error

Indices and tables