meteostat 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

meteostat/providers/gsa/synop.py

@@ -0,0 +1,184 @@
+"""
+GeoSphere Austria Data Hub SYNOP hourly data import routine
+
+Get SYNOP (synoptic observation) hourly data for weather stations in Austria.
+
+License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
+"""
+
+from datetime import datetime
+from typing import Dict, Optional
+
+import pandas as pd
+
+from meteostat.enumerations import TTL, Parameter
+from meteostat.core.logger import logger
+from meteostat.typing import ProviderRequest
+from meteostat.core.cache import cache_service
+from meteostat.api.config import config
+from meteostat.core.network import network_service
+from meteostat.utils.conversions import ms_to_kmh, pres_to_msl
+
+
+RESOURCE_ID = "synop-v1-1h"
+
+# Mapping from GeoSphere Austria SYNOP parameter names to Meteostat parameters
+# See: https://dataset.api.hub.geosphere.at/v1/station/historical/synop-v1-1h/metadata
+PARAMETER_MAPPING: Dict[str, Parameter] = {
+    "T": Parameter.TEMP,  # Air temperature (°C) - Lufttemperatur
+    "Pg": Parameter.PRES,  # Air pressure (hPa) - Luftdruck auf Stationshöhe
+    "rel": Parameter.RHUM,  # Relative humidity (%) - Relative Feuchte
+    "ff": Parameter.WSPD,  # Wind speed (m/s) - Windgeschwindigkeit
+    "boe": Parameter.WPGT,  # Wind gust (m/s) - Windböe
+    "dd": Parameter.WDIR,  # Wind direction (°) - Windrichtung
+    "RRR": Parameter.PRCP,  # Precipitation (mm) - Niederschlagsmenge
+    "N": Parameter.CLDC,  # Cloud cover (okta) - Bedeckungsgrad
+}
+
+# Inverse mapping
+METEOSTAT_TO_GSA = {v: k for k, v in PARAMETER_MAPPING.items()}
+
+
+@cache_service.cache(TTL.DAY, "pickle")
+def get_data(
+    station_id: str,
+    elevation: int | None,
+    parameters: list[str],
+    start: datetime,
+    end: datetime,
+) -> Optional[pd.DataFrame]:
+    """
+    Fetch SYNOP data from GeoSphere Austria Data Hub API
+    """
+    logger.debug(
+        f"Fetching SYNOP hourly data for station '{station_id}' from {start} to {end}"
+    )
+
+    # Format dates as ISO 8601
+    start_str = start.strftime("%Y-%m-%dT%H:%M")
+    end_str = end.strftime("%Y-%m-%dT%H:%M")
+
+    # Build URL
+    url = f"{config.gsa_api_base_url}/station/historical/{RESOURCE_ID}"
+
+    # Make request
+    response = network_service.get(
+        url,
+        params={
+            "parameters": ",".join(parameters),
+            "station_ids": station_id,
+            "start": start_str,
+            "end": end_str,
+            "output_format": "geojson",
+        },
+    )
+
+    if response.status_code != 200:
+        logger.warning(
+            f"Failed to fetch SYNOP data for station {station_id} (status: {response.status_code})"
+        )
+        return None
+
+    try:
+        data = response.json()
+
+        if not data.get("features"):
+            logger.info(f"No SYNOP data returned for station {station_id}")
+            return None
+
+        # Get timestamps array
+        timestamps = data.get("timestamps")
+        if not timestamps:
+            logger.warning("No timestamps in SYNOP response")
+            return None
+
+        # Extract time series data from GeoJSON response
+        # New API format has timestamps at top level and data as arrays
+        feature = data["features"][0]
+        props = feature.get("properties", {})
+        params_data = props.get("parameters", {})
+
+        if not params_data:
+            logger.info(f"No parameter data returned for station {station_id}")
+            return None
+
+        # Build DataFrame from timestamps and parameter arrays
+        df_dict = {}
+        for param in parameters:
+            if param in params_data:
+                param_info = params_data[param]
+                if "data" in param_info:
+                    df_dict[param] = param_info["data"]
+
+        if not df_dict:
+            return None
+
+        # Create DataFrame with timestamps as index
+        df = pd.DataFrame(df_dict)
+        dt_index = pd.DatetimeIndex(pd.to_datetime(timestamps))
+        df.index = dt_index.tz_localize(None)
+        df.index.name = "time"
+
+        # Sort by time
+        df = df.sort_index()
+
+        # Rename columns to Meteostat parameter names
+        rename_map = {}
+        for gsadh_param, meteostat_param in PARAMETER_MAPPING.items():
+            if gsadh_param in df.columns:
+                rename_map[gsadh_param] = meteostat_param
+
+        df = df.rename(columns=rename_map)
+
+        # Convert units where necessary
+        if Parameter.WSPD in df.columns:
+            df[Parameter.WSPD] = df[Parameter.WSPD].apply(ms_to_kmh)
+
+        if Parameter.WPGT in df.columns:
+            df[Parameter.WPGT] = df[Parameter.WPGT].apply(ms_to_kmh)
+
+        # RRR returns -1 for no precipitation; convert to 0
+        if Parameter.PRCP in df.columns:
+            df[Parameter.PRCP] = df[Parameter.PRCP].replace(-1, 0)
+
+        if Parameter.PRES in df.columns:
+            df[Parameter.PRES] = df.apply(
+                lambda row: pres_to_msl(row, elevation), axis=1
+            )
+
+        # Round values
+        df = df.round(1)
+
+        return df
+
+    except Exception as error:
+        logger.warning(f"Error parsing SYNOP response: {error}", exc_info=True)
+        return None
+
+
+def fetch(req: ProviderRequest) -> Optional[pd.DataFrame]:
+    """
+    Fetch SYNOP hourly data from GeoSphere Austria Data Hub
+    """
+    if "wmo" not in req.station.identifiers:
+        return None
+
+    station_id = req.station.identifiers["wmo"]
+
+    # Map Meteostat parameters to GeoSphere Austria SYNOP parameters
+    gsa_params = []
+    for param in req.parameters:
+        if param in METEOSTAT_TO_GSA:
+            gsa_params.append(METEOSTAT_TO_GSA[param])
+
+    if not gsa_params:
+        logger.info("No mappable parameters for GeoSphere Austria SYNOP data")
+        return None
+
+    # Fetch data
+    df = get_data(station_id, req.station.elevation, gsa_params, req.start, req.end)
+
+    if df is None or df.empty:
+        return None
+
+    return df

meteostat/providers/index.py

@@ -473,6 +473,113 @@ PROVIDER_METNO_FORECAST = ProviderSpec(
     module="meteostat.providers.metno.forecast",
 )
 
+PROVIDER_GSA_HOURLY = ProviderSpec(
+    id=Provider.GSA_HOURLY,
+    name="GeoSphere Austria Hourly",
+    granularity=Granularity.HOURLY,
+    priority=Priority.HIGHEST,
+    grade=Grade.RECORD,
+    license=License(
+        commercial=True,
+        attribution="GeoSphere Austria",
+        name="CC BY 4.0",
+        url="https://creativecommons.org/licenses/by/4.0/",
+    ),
+    requires=["identifiers"],
+    countries=["AT"],
+    parameters=[
+        Parameter.TEMP,
+        Parameter.PRCP,
+        Parameter.PRES,
+        Parameter.WSPD,
+        Parameter.WDIR,
+        Parameter.RHUM,
+        Parameter.TSUN,
+    ],
+    start=date(1880, 4, 1),
+    module="meteostat.providers.gsa.hourly",
+)
+
+PROVIDER_GSA_SYNOP = ProviderSpec(
+    id=Provider.GSA_SYNOP,
+    name="GeoSphere Austria SYNOP",
+    granularity=Granularity.HOURLY,
+    priority=Priority.HIGH,
+    grade=Grade.OBSERVATION,
+    license=License(
+        commercial=True,
+        attribution="GeoSphere Austria",
+        name="CC BY 4.0",
+        url="https://creativecommons.org/licenses/by/4.0/",
+    ),
+    requires=["identifiers"],
+    countries=["AT"],
+    parameters=[
+        Parameter.TEMP,
+        Parameter.PRES,
+        Parameter.RHUM,
+        Parameter.WSPD,
+        Parameter.WDIR,
+        Parameter.PRCP,
+    ],
+    start=date(2000, 1, 1),
+    module="meteostat.providers.gsa.synop",
+)
+
+PROVIDER_GSA_DAILY = ProviderSpec(
+    id=Provider.GSA_DAILY,
+    name="GeoSphere Austria Daily",
+    granularity=Granularity.DAILY,
+    priority=Priority.HIGHEST,
+    grade=Grade.RECORD,
+    license=License(
+        commercial=True,
+        attribution="GeoSphere Austria",
+        name="CC BY 4.0",
+        url="https://creativecommons.org/licenses/by/4.0/",
+    ),
+    requires=["identifiers"],
+    countries=["AT"],
+    parameters=[
+        Parameter.TEMP,
+        Parameter.TMIN,
+        Parameter.TMAX,
+        Parameter.PRCP,
+        Parameter.PRES,
+        Parameter.RHUM,
+        Parameter.WSPD,
+        Parameter.TSUN,
+    ],
+    start=date(1880, 4, 1),
+    module="meteostat.providers.gsa.daily",
+)
+
+PROVIDER_GSA_MONTHLY = ProviderSpec(
+    id=Provider.GSA_MONTHLY,
+    name="GeoSphere Austria Monthly",
+    granularity=Granularity.MONTHLY,
+    priority=Priority.HIGHEST,
+    grade=Grade.RECORD,
+    license=License(
+        commercial=True,
+        attribution="GeoSphere Austria",
+        name="CC BY 4.0",
+        url="https://creativecommons.org/licenses/by/4.0/",
+    ),
+    requires=["identifiers"],
+    countries=["AT"],
+    parameters=[
+        Parameter.TEMP,
+        Parameter.TMIN,
+        Parameter.TMAX,
+        Parameter.PRCP,
+        Parameter.PRES,
+        Parameter.TSUN,
+    ],
+    start=date(1880, 4, 1),
+    module="meteostat.providers.gsa.monthly",
+)
+
 
 DEFAULT_PROVIDERS = [
     PROVIDER_HOURLY,
@@ -493,4 +600,8 @@ DEFAULT_PROVIDERS = [
     PROVIDER_CLIMAT,
     PROVIDER_METAR,
     PROVIDER_METNO_FORECAST,
+    PROVIDER_GSA_HOURLY,
+    PROVIDER_GSA_SYNOP,
+    PROVIDER_GSA_DAILY,
+    PROVIDER_GSA_MONTHLY,
 ]

meteostat/providers/meteostat/daily.py

@@ -10,7 +10,7 @@ import pandas as pd
 from meteostat.providers.meteostat.shared import filter_model_data, handle_exceptions
 from meteostat.typing import ProviderRequest
 from meteostat.core.cache import cache_service
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.utils.data import reshape_by_source
 
 ENDPOINT = config.daily_endpoint

meteostat/providers/meteostat/hourly.py

@@ -9,7 +9,7 @@ import pandas as pd
 
 from meteostat.providers.meteostat.shared import filter_model_data, handle_exceptions
 from meteostat.typing import ProviderRequest
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.core.cache import cache_service
 from meteostat.utils.data import reshape_by_source
 

meteostat/providers/meteostat/monthly.py

@@ -6,7 +6,7 @@ from typing import Optional
 
 import pandas as pd
 
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.enumerations import TTL
 from meteostat.providers.meteostat.shared import filter_model_data, handle_exceptions
 from meteostat.typing import ProviderRequest

meteostat/providers/meteostat/shared.py

@@ -4,7 +4,7 @@ from typing import Optional, Callable, TypeVar
 
 import pandas as pd
 
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.core.logger import logger
 from meteostat.core.providers import provider_service
 from meteostat.enumerations import Grade

meteostat/providers/metno/forecast.py

@@ -3,7 +3,7 @@ from urllib.error import HTTPError
 
 import pandas as pd
 
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.enumerations import TTL, Parameter
 from meteostat.core.logger import logger
 from meteostat.core.network import network_service
@@ -11,9 +11,6 @@ from meteostat.typing import ProviderRequest
 from meteostat.utils.conversions import percentage_to_okta
 from meteostat.core.cache import cache_service
 
-
-ENDPOINT = config.metno_forecast_endpoint
-USER_AGENT = config.metno_user_agent
 CONDICODES = {
     "clearsky": 1,
     "cloudy": 3,
@@ -130,13 +127,26 @@ def map_data(record):
 
 @cache_service.cache(TTL.HOUR, "pickle")
 def get_df(latitude: float, longitude: float, elevation: int) -> Optional[pd.DataFrame]:
-    file_url = ENDPOINT.format(
+    endpoint = config.metno_forecast_endpoint
+    user_agent = config.metno_user_agent
+
+    if not endpoint:
+        logger.warning("MET Norway forecast endpoint is not configured.")
+        return None
+
+    if not user_agent:
+        logger.warning(
+            "MET Norway requires a unique user agent as per their terms of service. Please use config to specify your user agent. For now, this provider is skipped."
+        )
+        return None
+
+    file_url = endpoint.format(
         latitude=latitude,
         longitude=longitude,
         elevation=elevation,
     )
 
-    headers = {"User-Agent": USER_AGENT}
+    headers = {"User-Agent": user_agent}
 
     try:
         response = network_service.get(file_url, headers=headers)
@@ -173,12 +183,6 @@ def get_df(latitude: float, longitude: float, elevation: int) -> Optional[pd.Dat
 
 
 def fetch(req: ProviderRequest) -> Optional[pd.DataFrame]:
-    if not USER_AGENT:
-        logger.warning(
-            "MET Norway requires a unique user agent as per their terms of service. Please use config to specify your user agent. For now, this provider is skipped."
-        )
-        return None
-
     return get_df(
         req.station.latitude,
         req.station.longitude,

meteostat/providers/noaa/ghcnd.py

@@ -82,7 +82,7 @@ def create_df(element, dict_element):
         df_element = move_col_to_front(col, df_element)
 
     # Convert numerical values to float
-    df_element.loc[:, element] = df_element.loc[:, element].astype(float)
+    df_element[element] = df_element[element].astype(float)
 
     return df_element
 

meteostat/providers/noaa/isd_lite.py

@@ -65,13 +65,26 @@ def get_df(usaf: str, wban: str, year: int) -> Optional[pd.DataFrame]:
     try:
         df = pd.read_fwf(
             f"{ISD_LITE_ENDPOINT}{year}/{filename}",
-            parse_dates={"time": [0, 1, 2, 3]},
             na_values=["-9999", -9999],
             header=None,
             colspecs=COLSPECS,
             compression="gzip",
         )
 
+        # Parse datetime from first 4 columns (year, month, day, hour)
+        df[0] = pd.to_datetime(
+            df[0].astype(str)
+            + "-"
+            + df[1].astype(str).str.zfill(2)
+            + "-"
+            + df[2].astype(str).str.zfill(2)
+            + " "
+            + df[3].astype(str).str.zfill(2)
+            + ":00",
+            format="%Y-%m-%d %H:%M",
+        )
+        df = df.drop(columns=[1, 2, 3])
+
         # Rename columns
         df.columns = COLUMN_NAMES
 

meteostat/providers/noaa/metar.py

@@ -8,7 +8,7 @@ import pandas as pd
 from metar import Metar
 
 from meteostat.core.logger import logger
-from meteostat.core.config import config
+from meteostat.api.config import config
 from meteostat.enumerations import TTL, Frequency, Parameter
 from meteostat.typing import ProviderRequest
 from meteostat.utils.conversions import temp_dwpt_to_rhum

meteostat/utils/conversions.py

@@ -8,7 +8,7 @@ The code is licensed under the MIT license.
 import math
 from typing import Optional
 
-from numpy import isnan
+import pandas as pd
 
 from meteostat.enumerations import Parameter, Unit, UnitSystem
 
@@ -73,14 +73,21 @@ def kelvin_to_celsius(value):
     """
     Convert Kelvin to Celsius
     """
-    return value - 273.15 if value is not None and not isnan(value) else None
+    return value - 273.15 if not pd.isna(value) else None
 
 
 def ms_to_kmh(value):
     """
     Convert m/s to km/h
     """
-    return value * 3.6 if value is not None and not isnan(value) else None
+    return value * 3.6 if not pd.isna(value) else None
+
+
+def hours_to_minutes(value):
+    """
+    Convert duration from hours to minutes
+    """
+    return value * 60 if not pd.isna(value) else None
 
 
 def temp_dwpt_to_rhum(row: dict):
@@ -93,38 +100,30 @@ def temp_dwpt_to_rhum(row: dict):
             math.exp((17.625 * row["dwpt"]) / (243.04 + row["dwpt"]))
             / math.exp((17.625 * row["temp"]) / (243.04 + row["temp"]))
         )
-        if row["temp"] is not None and row["dwpt"] is not None
+        if not pd.isna(row["temp"]) and not pd.isna(row["dwpt"])
         else None
     )
 
 
 def pres_to_msl(row: dict, altitude: Optional[int] = None, temp: str = Parameter.TEMP):
-    """
-    Convert local air pressure to MSL
-    """
     try:
-        return (
-            None
-            if (
-                not row[Parameter.PRES]
-                or not row[temp]
-                or not altitude
-                or row[Parameter.PRES] == -999
-            )
-            else round(
-                row[Parameter.PRES]
-                * math.pow(
-                    (
-                        1
-                        - (
-                            (0.0065 * altitude)
-                            / (row[temp] + 0.0065 * altitude + 273.15)
-                        )
-                    ),
-                    -5.257,
-                ),
-                1,
-            )
+        pres = row.get(Parameter.PRES)
+        t = row.get(temp)
+
+        if pd.isna(pres) or pd.isna(t) or altitude is None or pres == -999:
+            return None
+
+        # Type narrowing for arithmetic operations
+        if not isinstance(pres, (int, float)) or not isinstance(t, (int, float)):
+            return None
+
+        return round(
+            pres
+            * math.pow(
+                1 - (0.0065 * altitude) / (t + 0.0065 * altitude + 273.15),
+                -5.257,
+            ),
+            1,
         )
     except Exception:
         return None
@@ -134,14 +133,14 @@ def percentage_to_okta(value):
     """
     Convert cloud cover percentage to oktas
     """
-    return round(value / 12.5) if value is not None and not isnan(value) else None
+    return round(value / 12.5) if not pd.isna(value) else None
 
 
 def jcm2_to_wm2(value):
     """
     Convert Joule/CM^2 to Watt/M^2
     """
-    return round(value * 2.78) if value is not None and not isnan(value) else None
+    return round(value * 2.78) if not pd.isna(value) else None
 
 
 def to_direction(value):

meteostat/utils/guards.py

@@ -0,0 +1,51 @@
+"""
+Guard functions for Meteostat.
+
+The code is licensed under the MIT license.
+"""
+
+from datetime import datetime
+from meteostat.api.config import config
+from meteostat.core.logger import logger
+from meteostat.enumerations import Granularity
+from meteostat.typing import Request
+
+
+def request_size_guard(req: Request) -> None:
+    """
+    Guard to block large requests
+    """
+    if not config.block_large_requests:
+        logger.debug("Large request blocking is disabled.")
+        return
+
+    if isinstance(req.station, list) and len(req.station) > 10:
+        raise ValueError(
+            "Requests with more than 10 stations are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    if req.granularity not in [Granularity.HOURLY, Granularity.DAILY]:
+        return
+
+    if req.start is None:
+        raise ValueError(
+            "Hourly and daily requests without a start date are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    time_diff_years = abs((req.end or datetime.now()).year - req.start.year)
+
+    logger.debug(f"Request time range: {time_diff_years} years.")
+
+    if req.granularity is Granularity.HOURLY and time_diff_years > 3:
+        raise ValueError(
+            "Hourly requests longer than 3 years are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )
+
+    if req.granularity is Granularity.DAILY and time_diff_years > 30:
+        raise ValueError(
+            "Daily requests longer than 30 years are blocked by default. "
+            "To enable large requests, set `config.block_large_requests = False`."
+        )

meteostat/utils/parsers.py

@@ -13,7 +13,6 @@ import pytz
 
 from meteostat.api.stations import stations as stations_service
 from meteostat.api.point import Point
-from meteostat.core.config import config
 from meteostat.typing import Station
 
 
@@ -54,12 +53,6 @@ def parse_station(
         # It's a list
         stations = station
 
-    if config.block_large_requests and len(stations) > 10:
-        raise ValueError(
-            "Requests with more than 10 stations are blocked by default. "
-            "To enable large requests, set `config.block_large_requests = False`."
-        )
-
     # Get station meta data
     data = []
     point_counter = 0