weather.client.WeatherClient

weather.client.WeatherClient(latitude, longitude)

Client for fetching weather data from Open-Meteo API. Handles the low-level API interactions, parameter building, and response parsing.

Parameters

Name	Type	Description	Default
latitude	float	Latitude of the location.	required
longitude	float	Longitude of the location.	required

Examples

# Fetching from Open-Meteo requires a live network connection.
import pandas as pd
from spotforecast2_safe.weather import WeatherClient
client = WeatherClient(latitude=52.52, longitude=13.405)
df = client.fetch_archive(
    start=pd.Timestamp("2023-01-01", tz="UTC"),
    end=pd.Timestamp("2023-01-02", tz="UTC"),
)
print(df.head())

Construction and attribute inspection do not require a network call:

from spotforecast2_safe.weather.client import WeatherClient

client = WeatherClient(latitude=52.52, longitude=13.405)
assert client.latitude == 52.52
assert client.longitude == 13.405
print(f"WeatherClient at ({client.latitude}, {client.longitude})")
print("HOURLY_PARAMS count:", len(client.HOURLY_PARAMS))

WeatherClient at (52.52, 13.405)
HOURLY_PARAMS count: 15

Methods

Name	Description
fetch_archive	Fetch historical data from Archive API.
fetch_forecast	Fetch forecast data from Forecast API.

fetch_archive

weather.client.WeatherClient.fetch_archive(start, end, timezone='UTC')

Fetch historical data from Archive API.

Parameters

Name	Type	Description	Default
start	pd.Timestamp	Start date for the historical data.	required
end	pd.Timestamp	End date for the historical data.	required
timezone	str	Timezone for the data (default “UTC”).	'UTC'

Examples

# Requires a live connection to archive-api.open-meteo.com.
import pandas as pd
from spotforecast2_safe.weather import WeatherClient
client = WeatherClient(latitude=52.52, longitude=13.405)
df = client.fetch_archive(
    start=pd.Timestamp("2023-01-01", tz="UTC"),
    end=pd.Timestamp("2023-01-02", tz="UTC"),
)
print(df.head())

fetch_forecast

weather.client.WeatherClient.fetch_forecast(
    days_ahead,
    timezone='UTC',
    past_days=0,
)

Fetch forecast data from Forecast API.

Parameters

Name	Type	Description	Default
days_ahead	int	Number of days ahead for the forecast.	required
timezone	str	Timezone for the data (default “UTC”).	'UTC'
past_days	int	Recent past days to also request from the forecast endpoint via Open-Meteo’s past_days parameter (0–92). The archive endpoint lags several days, so past_days lets the forecast endpoint backfill that recent window; without it the [now - archive_lag, today] range is fetched by neither endpoint and is later carried forward as a flat line.	0

Examples

# Requires a live connection to api.open-meteo.com.
from spotforecast2_safe.weather import WeatherClient
client = WeatherClient(latitude=52.52, longitude=13.405)
df = client.fetch_forecast(days_ahead=7)
print(df.head())