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 columnsforecast_moment
(UTC datetimes) andforecast_distances
(integers), as well as any columns you select using thecolumns
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 fromforecast_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 fromforecast_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.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