= None ,= True ,High-level service for weather data generation.
Extends WeatherClient with caching, hybrid fetching (archive+forecast), and fallback strategies.
Parameters
latitude
float Latitude of the location.
required
longitude
float Longitude of the location.
required
cache_path
Path | NoneOptional 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
Examples
from pathlib import Pathimport pandas as pdfrom spotforecast2_safe.weather import WeatherService= WeatherService(latitude= 52.52 , longitude= 13.405 , cache_path= Path("weather_cache.parquet" ))= pd.Timestamp("2023-01-01" , tz= "UTC" )= pd.Timestamp("2023-01-07" , tz= "UTC" )= client.get_dataframe(start= start, end= end, fill_missing= False )print (df.head())print (df.tail())
temperature_2m relative_humidity_2m \
datetime
2023-01-01 00:00:00+00:00 15.2 59
2023-01-01 01:00:00+00:00 15.6 55
2023-01-01 02:00:00+00:00 15.7 52
2023-01-01 03:00:00+00:00 15.8 51
2023-01-01 04:00:00+00:00 15.8 49
precipitation rain snowfall weather_code \
datetime
2023-01-01 00:00:00+00:00 0.0 0.0 0.0 3
2023-01-01 01:00:00+00:00 0.0 0.0 0.0 3
2023-01-01 02:00:00+00:00 0.0 0.0 0.0 3
2023-01-01 03:00:00+00:00 0.0 0.0 0.0 3
2023-01-01 04:00:00+00:00 0.0 0.0 0.0 3
pressure_msl surface_pressure cloud_cover \
datetime
2023-01-01 00:00:00+00:00 1010.8 1006.4 100
2023-01-01 01:00:00+00:00 1010.9 1006.5 100
2023-01-01 02:00:00+00:00 1011.3 1006.9 100
2023-01-01 03:00:00+00:00 1011.3 1006.9 100
2023-01-01 04:00:00+00:00 1011.5 1007.1 85
cloud_cover_low cloud_cover_mid cloud_cover_high \
datetime
2023-01-01 00:00:00+00:00 0 14 100
2023-01-01 01:00:00+00:00 12 76 100
2023-01-01 02:00:00+00:00 8 25 100
2023-01-01 03:00:00+00:00 1 100 97
2023-01-01 04:00:00+00:00 0 32 78
wind_speed_10m wind_direction_10m wind_gusts_10m
datetime
2023-01-01 00:00:00+00:00 30.5 232 49.7
2023-01-01 01:00:00+00:00 30.7 231 52.2
2023-01-01 02:00:00+00:00 31.3 232 52.2
2023-01-01 03:00:00+00:00 28.4 231 52.2
2023-01-01 04:00:00+00:00 28.3 223 47.9
temperature_2m relative_humidity_2m \
datetime
2023-01-06 20:00:00+00:00 6.3 93
2023-01-06 21:00:00+00:00 5.8 96
2023-01-06 22:00:00+00:00 5.7 96
2023-01-06 23:00:00+00:00 5.5 96
2023-01-07 00:00:00+00:00 5.8 95
precipitation rain snowfall weather_code \
datetime
2023-01-06 20:00:00+00:00 0.0 0.0 0.0 3
2023-01-06 21:00:00+00:00 0.0 0.0 0.0 3
2023-01-06 22:00:00+00:00 0.0 0.0 0.0 3
2023-01-06 23:00:00+00:00 0.0 0.0 0.0 3
2023-01-07 00:00:00+00:00 0.0 0.0 0.0 3
pressure_msl surface_pressure cloud_cover \
datetime
2023-01-06 20:00:00+00:00 1018.5 1013.9 98
2023-01-06 21:00:00+00:00 1018.9 1014.3 100
2023-01-06 22:00:00+00:00 1019.1 1014.5 100
2023-01-06 23:00:00+00:00 1019.2 1014.6 99
2023-01-07 00:00:00+00:00 1018.9 1014.3 100
cloud_cover_low cloud_cover_mid cloud_cover_high \
datetime
2023-01-06 20:00:00+00:00 27 6 97
2023-01-06 21:00:00+00:00 14 8 100
2023-01-06 22:00:00+00:00 0 22 100
2023-01-06 23:00:00+00:00 0 46 99
2023-01-07 00:00:00+00:00 0 92 93
wind_speed_10m wind_direction_10m wind_gusts_10m
datetime
2023-01-06 20:00:00+00:00 9.2 249 18.7
2023-01-06 21:00:00+00:00 9.2 244 14.8
2023-01-06 22:00:00+00:00 9.5 241 15.5
2023-01-06 23:00:00+00:00 9.6 236 15.5
2023-01-07 00:00:00+00:00 9.2 228 15.8
Methods
get_dataframe Get weather DataFrame for a specified range using best available methods.
get_dataframe
= 'UTC' ,= 'h' ,= True ,= 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
start
str | pd .Timestamp Start date for the data.
required
end
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
ValueError If fill_missing=False and the merged frame still contains NaNs after resample.
Examples
import pandas as pdfrom spotforecast2_safe.weather import WeatherService= WeatherService(latitude= 51.0267 , longitude= 7.5693 )# get the weather data for the last week, using the cache if available, and filling any remaining gaps = pd.Timestamp.now(tz= "UTC" ) - pd.Timedelta(days= 7 )= pd.Timestamp.now(tz= "UTC" )= client.get_dataframe(start= start, end= end, fill_missing= False )print (df.head())print (df.tail())
temperature_2m relative_humidity_2m \
datetime
2026-05-12 23:00:00+00:00 6.4 85
2026-05-13 00:00:00+00:00 6.7 85
2026-05-13 01:00:00+00:00 6.8 84
2026-05-13 02:00:00+00:00 6.4 90
2026-05-13 03:00:00+00:00 6.1 95
precipitation rain snowfall weather_code \
datetime
2026-05-12 23:00:00+00:00 0.3 0.3 0.0 51
2026-05-13 00:00:00+00:00 0.2 0.2 0.0 51
2026-05-13 01:00:00+00:00 0.2 0.2 0.0 51
2026-05-13 02:00:00+00:00 0.5 0.5 0.0 53
2026-05-13 03:00:00+00:00 0.4 0.4 0.0 51
pressure_msl surface_pressure cloud_cover \
datetime
2026-05-12 23:00:00+00:00 1009.1 977.3 100
2026-05-13 00:00:00+00:00 1008.1 976.3 100
2026-05-13 01:00:00+00:00 1007.4 975.7 100
2026-05-13 02:00:00+00:00 1006.8 975.1 100
2026-05-13 03:00:00+00:00 1006.4 974.6 100
cloud_cover_low cloud_cover_mid cloud_cover_high \
datetime
2026-05-12 23:00:00+00:00 100 100 0
2026-05-13 00:00:00+00:00 100 100 0
2026-05-13 01:00:00+00:00 100 100 0
2026-05-13 02:00:00+00:00 100 100 8
2026-05-13 03:00:00+00:00 100 100 0
wind_speed_10m wind_direction_10m wind_gusts_10m
datetime
2026-05-12 23:00:00+00:00 12.9 213 27.0
2026-05-13 00:00:00+00:00 13.5 223 25.6
2026-05-13 01:00:00+00:00 14.9 229 28.4
2026-05-13 02:00:00+00:00 16.6 238 32.0
2026-05-13 03:00:00+00:00 14.7 239 32.0
temperature_2m relative_humidity_2m \
datetime
2026-05-14 19:00:00+00:00 6.1 88
2026-05-14 20:00:00+00:00 4.6 93
2026-05-14 21:00:00+00:00 4.0 96
2026-05-14 22:00:00+00:00 3.5 97
2026-05-14 23:00:00+00:00 3.0 99
precipitation rain snowfall weather_code \
datetime
2026-05-14 19:00:00+00:00 0.0 0.0 0.0 3
2026-05-14 20:00:00+00:00 0.0 0.0 0.0 3
2026-05-14 21:00:00+00:00 0.0 0.0 0.0 3
2026-05-14 22:00:00+00:00 0.0 0.0 0.0 3
2026-05-14 23:00:00+00:00 0.0 0.0 0.0 2
pressure_msl surface_pressure cloud_cover \
datetime
2026-05-14 19:00:00+00:00 999.1 967.6 88
2026-05-14 20:00:00+00:00 999.7 968.0 88
2026-05-14 21:00:00+00:00 1000.1 968.3 80
2026-05-14 22:00:00+00:00 1000.5 968.6 89
2026-05-14 23:00:00+00:00 1000.5 968.6 60
cloud_cover_low cloud_cover_mid cloud_cover_high \
datetime
2026-05-14 19:00:00+00:00 0 6 87
2026-05-14 20:00:00+00:00 13 10 87
2026-05-14 21:00:00+00:00 9 37 75
2026-05-14 22:00:00+00:00 5 82 41
2026-05-14 23:00:00+00:00 13 48 13
wind_speed_10m wind_direction_10m wind_gusts_10m
datetime
2026-05-14 19:00:00+00:00 1.3 262 7.2
2026-05-14 20:00:00+00:00 2.9 313 4.7
2026-05-14 21:00:00+00:00 4.0 360 6.8
2026-05-14 22:00:00+00:00 4.7 2 8.3
2026-05-14 23:00:00+00:00 6.0 9 10.8