weather.weather_client.WeatherService

weather.weather_client.WeatherService(
    latitude,
    longitude,
    cache_path=None,
    use_forecast=True,
)

High-level service for weather data generation.

Extends WeatherClient with caching, hybrid fetching (archive+forecast), and fallback strategies.

Parameters

Name	Type	Description	Default
latitude	float	Latitude of the location.	required
longitude	float	Longitude of the location.	required
cache_path	Optional[Path]	Optional path to cache file for storing fetched data. If provided, the service will attempt to load from cache before fetching and will save new data to this path. Default is None (no caching).	None
use_forecast	bool	Whether to use forecast data for future dates (default True).	True

Methods

Name	Description
get_dataframe	Get weather DataFrame for a specified range using best available methods.

get_dataframe

weather.weather_client.WeatherService.get_dataframe(
    start,
    end,
    timezone='UTC',
    freq='h',
    fallback_on_failure=True,
    fill_missing=False,
)

Get weather DataFrame for a specified range using best available methods.

Refactored from spotpredict.create_weather_df. Since the 1.0 major release, remaining gaps after fetch are rejected by default so that synthesised values never reach downstream consumers labelled as measurements. Pass fill_missing=True to opt into the legacy forward/back-fill behavior.

Parameters

Name	Type	Description	Default
start	Union[str, pd.Timestamp]	Start date for the data.	required
end	Union[str, pd.Timestamp]	End date for the data.	required
timezone	str	Timezone for the data (default “UTC”).	'UTC'
freq	str	Frequency for the data (default “h”).	'h'
fallback_on_failure	bool	Whether to use fallback data on failure (default True).	True
fill_missing	bool	Whether to forward- and back-fill remaining NaN gaps after fetch/resample (default False). When False (the fail-safe default), any remaining NaN raises ValueError with the gap timestamps.	False

Raises

Name	Type	Description
	ValueError	If fill_missing=False and the merged frame still contains NaNs after resample.