pyopenmeteo 0.1.0__py3-none-any.whl

pyopenmeteo/__init__.py

@@ -0,0 +1,78 @@
+"""pyopenmeteo - a Python wrapper for the Open-Meteo weather API family."""
+
+from pyopenmeteo.api.forecast import ForecastAPI
+from pyopenmeteo.api.historical import HistoricalAPI, HistoricalForecastAPI
+from pyopenmeteo.api.geo import GeocodingAPI, ElevationAPI, Location
+from pyopenmeteo.api.marine import MarineAPI
+from pyopenmeteo.api.climate import ClimateAPI
+from pyopenmeteo.api.air_quality import AirQualityAPI
+from pyopenmeteo.api.ensemble import EnsembleAPI
+from pyopenmeteo.api.flood import FloodAPI
+from pyopenmeteo.api.satellite import SatelliteRadiationAPI
+from pyopenmeteo.api.seasonal import SeasonalAPI
+from pyopenmeteo.core.exceptions import (
+    MeteoPyError,
+    APIError,
+    RateLimitError,
+    ServerError,
+    GeocodingError,
+    LocationNotFoundError,
+    ValidationError,
+    ConnectionError,
+)
+from pyopenmeteo.core.response import WeatherResponse
+from pyopenmeteo.params.units import (
+    TemperatureUnit,
+    WindSpeedUnit,
+    PrecipitationUnit,
+    TimeFormat,
+    CellSelection,
+    LengthUnit,
+)
+from pyopenmeteo.params.pressure_levels import PressureVar, pressure_level, pressure_levels_range
+from pyopenmeteo.params.solar import PanelOrientation
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # APIs
+    "ForecastAPI",
+    "HistoricalAPI",
+    "HistoricalForecastAPI",
+    "GeocodingAPI",
+    "ElevationAPI",
+    "Location",
+    "MarineAPI",
+    "ClimateAPI",
+    "AirQualityAPI",
+    "EnsembleAPI",
+    "FloodAPI",
+    "SatelliteRadiationAPI",
+    "SeasonalAPI",
+    # Exceptions
+    "MeteoPyError",
+    "APIError",
+    "RateLimitError",
+    "ServerError",
+    "GeocodingError",
+    "LocationNotFoundError",
+    "ValidationError",
+    "ConnectionError",
+    # Response
+    "WeatherResponse",
+    # Units
+    "TemperatureUnit",
+    "WindSpeedUnit",
+    "PrecipitationUnit",
+    "TimeFormat",
+    "CellSelection",
+    "LengthUnit",
+    # Pressure levels
+    "PressureVar",
+    "pressure_level",
+    "pressure_levels_range",
+    # Solar
+    "PanelOrientation",
+    # Version
+    "__version__",
+]

pyopenmeteo/api/__init__.py

@@ -0,0 +1,26 @@
+from pyopenmeteo.api.forecast import ForecastAPI
+from pyopenmeteo.api.historical import HistoricalAPI, HistoricalForecastAPI
+from pyopenmeteo.api.geo import GeocodingAPI, ElevationAPI, Location
+from pyopenmeteo.api.marine import MarineAPI
+from pyopenmeteo.api.climate import ClimateAPI
+from pyopenmeteo.api.air_quality import AirQualityAPI
+from pyopenmeteo.api.ensemble import EnsembleAPI
+from pyopenmeteo.api.flood import FloodAPI
+from pyopenmeteo.api.satellite import SatelliteRadiationAPI
+from pyopenmeteo.api.seasonal import SeasonalAPI
+
+__all__ = [
+    "ForecastAPI",
+    "HistoricalAPI",
+    "HistoricalForecastAPI",
+    "GeocodingAPI",
+    "ElevationAPI",
+    "Location",
+    "MarineAPI",
+    "ClimateAPI",
+    "AirQualityAPI",
+    "EnsembleAPI",
+    "FloodAPI",
+    "SatelliteRadiationAPI",
+    "SeasonalAPI",
+]

pyopenmeteo/api/air_quality.py

@@ -0,0 +1,142 @@
+from datetime import date
+
+from pyopenmeteo.core.base_api import BaseAPI
+from pyopenmeteo.core.exceptions import ValidationError
+from pyopenmeteo.core.request_builder import RequestBuilder
+from pyopenmeteo.core.response import WeatherResponse
+from pyopenmeteo.params.airquality_vars import CurrentAirQualityVars, HourlyAirQualityVars
+from pyopenmeteo.params.units import TimeFormat
+
+
+class AirQualityAPI(BaseAPI):
+    """Wraps the OpenMeteo Air Quality API.
+
+    Provides hourly air quality forecasts and current conditions including
+    pollutant concentrations, pollen counts, and air quality indices for
+    any location worldwide.
+
+    Example:
+        >>> from pyopenmeteo.params.airquality_vars import HourlyAirQualityVars
+        >>> api = AirQualityAPI()
+        >>> resp = api.get(
+        ...     (48.85, 2.35),
+        ...     hourly=[HourlyAirQualityVars.PM2_5],
+        ...     forecast_days=3,
+        ... )
+    """
+
+    BASE_URL = "https://air-quality-api.open-meteo.com/v1/air-quality"
+
+    def get(
+        self,
+        location: tuple[float, float] | list[float] | str,
+        *,
+        hourly: list[HourlyAirQualityVars | str] | None = None,
+        current: list[CurrentAirQualityVars | str] | None = None,
+        timeformat: TimeFormat | str | None = None,
+        timezone: str | None = None,
+        past_days: int | None = None,
+        forecast_days: int | None = None,
+        past_hours: int | None = None,
+        forecast_hours: int | None = None,
+        start_date: str | date | None = None,
+        end_date: str | date | None = None,
+        domains: str | None = None,
+    ) -> WeatherResponse:
+        """Fetch air quality forecast data.
+
+        Args:
+            location: ``(latitude, longitude)`` tuple/list or a place-name
+                string resolved via the Geocoding API.
+            hourly: Hourly air quality variables to request.
+            current: Current-conditions air quality variables to request.
+                Accepts the same variable set as ``hourly``.
+            timeformat: ``iso8601`` (default) or ``unixtime``.
+            timezone: tz database string like ``"Europe/Paris"`` or
+                ``"auto"`` to infer from location.
+            past_days: Include this many past days in the response (0–92).
+            forecast_days: Days ahead to forecast (1–7).
+            past_hours: Past hours to include (alternative to ``past_days``).
+            forecast_hours: Hours ahead to forecast (alternative to
+                ``forecast_days``).
+            start_date: Start of an explicit date range (``YYYY-MM-DD``).
+            end_date: End of an explicit date range (``YYYY-MM-DD``).
+                Required when ``start_date`` is given.
+            domains: Air quality domain to use. One of ``"auto"``,
+                ``"cams_europe"``, ``"cams_global_reanalysis"``, or
+                ``"cams_global_forecast"``.
+
+        Returns:
+            A WeatherResponse wrapping the raw API JSON.
+
+        Raises:
+            ValidationError: If parameters fail pre-flight checks.
+            LocationNotFoundError: If a place-name string cannot be geocoded.
+            APIError: On an HTTP-level error from the server.
+            RateLimitError: On HTTP 429.
+            ServerError: On HTTP 5xx.
+            ConnectionError: If the server is unreachable.
+        """
+        self._validate(
+            hourly=hourly,
+            current=current,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            start_date=start_date,
+            end_date=end_date,
+        )
+
+        lat, lon = self.resolve_location(location)
+
+        params = RequestBuilder(
+            latitude=lat,
+            longitude=lon,
+            hourly=hourly,
+            current=current,
+            timeformat=timeformat,
+            timezone=timezone,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            past_hours=past_hours,
+            forecast_hours=forecast_hours,
+            start_date=str(start_date) if start_date is not None else None,
+            end_date=str(end_date) if end_date is not None else None,
+            domains=domains,
+        ).build()
+
+        return self._get(params)
+
+    def _validate(
+        self,
+        hourly,
+        current,
+        past_days,
+        forecast_days,
+        start_date,
+        end_date,
+    ) -> None:
+        """Validate parameters before making the API request.
+
+        Args:
+            hourly: Hourly variables requested.
+            current: Current-conditions variables requested.
+            past_days: Number of past days to include.
+            forecast_days: Number of forecast days.
+            start_date: Explicit start date.
+            end_date: Explicit end date.
+
+        Raises:
+            ValidationError: If any parameter is invalid.
+        """
+        if not any([hourly, current]):
+            raise ValidationError(
+                "At least one of hourly or current must be specified."
+            )
+        if past_days is not None and not (0 <= past_days <= 92):
+            raise ValidationError("past_days must be between 0 and 92.")
+        if forecast_days is not None and not (1 <= forecast_days <= 7):
+            raise ValidationError("forecast_days must be between 1 and 7.")
+        if (start_date is None) != (end_date is None):
+            raise ValidationError(
+                "start_date and end_date must both be provided or both omitted."
+            )

pyopenmeteo/api/climate.py

@@ -0,0 +1,125 @@
+from datetime import date
+
+from pyopenmeteo.core.base_api import BaseAPI
+from pyopenmeteo.core.exceptions import ValidationError
+from pyopenmeteo.core.request_builder import RequestBuilder
+from pyopenmeteo.core.response import WeatherResponse
+from pyopenmeteo.params.climate_vars import ClimateModels, DailyClimateVars
+from pyopenmeteo.params.units import CellSelection, PrecipitationUnit, TemperatureUnit, TimeFormat, WindSpeedUnit
+
+
+class ClimateAPI(BaseAPI):
+    """Wraps the OpenMeteo Climate Change API.
+
+    Provides daily climate projections (1950–2100) based on CMIP6 models
+    downscaled to 10 km resolution. Requires an explicit date range and
+    daily variables.
+
+    Example:
+        >>> from pyopenmeteo.params.climate_vars import DailyClimateVars, ClimateModels
+        >>> api = ClimateAPI()
+        >>> resp = api.get(
+        ...     (40.71, -74.01),
+        ...     daily=[DailyClimateVars.TEMPERATURE_2M_MAX],
+        ...     models=[ClimateModels.MRI_AGCM3_2_S],
+        ...     start_date="2050-01-01",
+        ...     end_date="2050-12-31",
+        ... )
+    """
+
+    BASE_URL = "https://climate-api.open-meteo.com/v1/climate"
+
+    def get(
+        self,
+        location: tuple[float, float] | list[float] | str,
+        *,
+        daily: list[DailyClimateVars | str],
+        start_date: str | date,
+        end_date: str | date,
+        models: list[ClimateModels | str] | ClimateModels | str | None = None,
+        temperature_unit: TemperatureUnit | str | None = None,
+        wind_speed_unit: WindSpeedUnit | str | None = None,
+        precipitation_unit: PrecipitationUnit | str | None = None,
+        timeformat: TimeFormat | str | None = None,
+        timezone: str | None = None,
+        cell_selection: CellSelection | str | None = None,
+    ) -> WeatherResponse:
+        """Fetch climate projection data.
+
+        Args:
+            location: ``(latitude, longitude)`` tuple/list or a place-name
+                string resolved via the Geocoding API.
+            daily: Daily variables to request. Required.
+            start_date: Start of the date range (``YYYY-MM-DD``). Required.
+            end_date: End of the date range (``YYYY-MM-DD``). Required.
+            models: One or more CMIP6 climate models to use. Accepts a single
+                value or a list.
+            temperature_unit: ``celsius`` (default) or ``fahrenheit``.
+            wind_speed_unit: ``kmh`` (default), ``ms``, ``mph``, or ``kn``.
+            precipitation_unit: ``mm`` (default) or ``inch``.
+            timeformat: ``iso8601`` (default) or ``unixtime``.
+            timezone: tz database string like ``"America/New_York"`` or
+                ``"auto"`` to infer from location.
+            cell_selection: ``land`` (default), ``sea``, or ``nearest``.
+
+        Returns:
+            A WeatherResponse wrapping the raw API JSON.
+
+        Raises:
+            ValidationError: If parameters fail pre-flight checks.
+            LocationNotFoundError: If a place-name string cannot be geocoded.
+            APIError: On an HTTP-level error from the server.
+            RateLimitError: On HTTP 429.
+            ServerError: On HTTP 5xx.
+            ConnectionError: If the server is unreachable.
+        """
+        self._validate(
+            daily=daily,
+            start_date=start_date,
+            end_date=end_date,
+        )
+
+        lat, lon = self.resolve_location(location)
+
+        if isinstance(models, (str, ClimateModels)):
+            models = [models]
+
+        params = RequestBuilder(
+            latitude=lat,
+            longitude=lon,
+            daily=daily,
+            start_date=str(start_date) if start_date is not None else None,
+            end_date=str(end_date) if end_date is not None else None,
+            models=models,
+            temperature_unit=temperature_unit,
+            wind_speed_unit=wind_speed_unit,
+            precipitation_unit=precipitation_unit,
+            timeformat=timeformat,
+            timezone=timezone,
+            cell_selection=cell_selection,
+        ).build()
+
+        return self._get(params)
+
+    def _validate(
+        self,
+        daily,
+        start_date,
+        end_date,
+    ) -> None:
+        """Validate parameters before making the API request.
+
+        Args:
+            daily: Daily variables requested.
+            start_date: Explicit start date.
+            end_date: Explicit end date.
+
+        Raises:
+            ValidationError: If any parameter is invalid.
+        """
+        if not daily:
+            raise ValidationError("daily variables are required for the Climate API.")
+        if start_date is None or end_date is None:
+            raise ValidationError(
+                "start_date and end_date are both required for the Climate API."
+            )

pyopenmeteo/api/ensemble.py

@@ -0,0 +1,161 @@
+from datetime import date
+
+from pyopenmeteo.core.base_api import BaseAPI
+from pyopenmeteo.core.exceptions import ValidationError
+from pyopenmeteo.core.request_builder import RequestBuilder
+from pyopenmeteo.core.response import WeatherResponse
+from pyopenmeteo.params.ensemble_vars import DailyEnsembleVars, EnsembleModels, HourlyEnsembleVars
+from pyopenmeteo.params.units import CellSelection, PrecipitationUnit, TemperatureUnit, TimeFormat, WindSpeedUnit
+
+
+class EnsembleAPI(BaseAPI):
+    """Wraps the OpenMeteo Ensemble Forecast API.
+
+    Provides probabilistic weather forecasts from ensemble model runs,
+    with up to 35 forecast days of hourly or daily data. A ``models``
+    selection is required.
+
+    Example:
+        >>> from pyopenmeteo.params.ensemble_vars import HourlyEnsembleVars, EnsembleModels
+        >>> api = EnsembleAPI()
+        >>> resp = api.get(
+        ...     (48.85, 2.35),
+        ...     hourly=[HourlyEnsembleVars.TEMPERATURE_2M],
+        ...     models=EnsembleModels.ICON_EU_EPS,
+        ...     forecast_days=7,
+        ... )
+    """
+
+    BASE_URL = "https://ensemble-api.open-meteo.com/v1/ensemble"
+
+    def get(
+        self,
+        location: tuple[float, float] | list[float] | str,
+        *,
+        hourly: list[HourlyEnsembleVars | str] | None = None,
+        daily: list[DailyEnsembleVars | str] | None = None,
+        models: list[EnsembleModels | str] | EnsembleModels | str,
+        temperature_unit: TemperatureUnit | str | None = None,
+        wind_speed_unit: WindSpeedUnit | str | None = None,
+        precipitation_unit: PrecipitationUnit | str | None = None,
+        timeformat: TimeFormat | str | None = None,
+        timezone: str | None = None,
+        past_days: int | None = None,
+        forecast_days: int | None = None,
+        past_hours: int | None = None,
+        forecast_hours: int | None = None,
+        start_date: str | date | None = None,
+        end_date: str | date | None = None,
+        cell_selection: CellSelection | str | None = None,
+    ) -> WeatherResponse:
+        """Fetch ensemble weather forecast data.
+
+        Args:
+            location: ``(latitude, longitude)`` tuple/list or a place-name
+                string resolved via the Geocoding API.
+            hourly: Hourly variables to request.
+            daily: Daily aggregate variables to request.
+            models: One or more ensemble models to use. Required. Accepts a
+                single value or a list.
+            temperature_unit: ``celsius`` (default) or ``fahrenheit``.
+            wind_speed_unit: ``kmh`` (default), ``ms``, ``mph``, or ``kn``.
+            precipitation_unit: ``mm`` (default) or ``inch``.
+            timeformat: ``iso8601`` (default) or ``unixtime``.
+            timezone: tz database string like ``"Europe/Paris"`` or ``"auto"``
+                to infer from location.
+            past_days: Include this many past days in the response (0–92).
+            forecast_days: Days ahead to forecast (1–35).
+            past_hours: Past hours to include (alternative to ``past_days``).
+            forecast_hours: Hours ahead to forecast (alternative to
+                ``forecast_days``).
+            start_date: Start of an explicit date range (``YYYY-MM-DD``).
+            end_date: End of an explicit date range (``YYYY-MM-DD``).
+                Required when ``start_date`` is given.
+            cell_selection: ``land`` (default), ``sea``, or ``nearest``.
+
+        Returns:
+            A WeatherResponse wrapping the raw API JSON.
+
+        Raises:
+            ValidationError: If parameters fail pre-flight checks.
+            LocationNotFoundError: If a place-name string cannot be geocoded.
+            APIError: On an HTTP-level error from the server.
+            RateLimitError: On HTTP 429.
+            ServerError: On HTTP 5xx.
+            ConnectionError: If the server is unreachable.
+        """
+        self._validate(
+            hourly=hourly,
+            daily=daily,
+            models=models,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            start_date=start_date,
+            end_date=end_date,
+        )
+
+        lat, lon = self.resolve_location(location)
+
+        if isinstance(models, (str, EnsembleModels)):
+            models = [models]
+
+        params = RequestBuilder(
+            latitude=lat,
+            longitude=lon,
+            hourly=hourly,
+            daily=daily,
+            models=models,
+            temperature_unit=temperature_unit,
+            wind_speed_unit=wind_speed_unit,
+            precipitation_unit=precipitation_unit,
+            timeformat=timeformat,
+            timezone=timezone,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            past_hours=past_hours,
+            forecast_hours=forecast_hours,
+            start_date=str(start_date) if start_date is not None else None,
+            end_date=str(end_date) if end_date is not None else None,
+            cell_selection=cell_selection,
+        ).build()
+
+        return self._get(params)
+
+    def _validate(
+        self,
+        hourly,
+        daily,
+        models,
+        past_days,
+        forecast_days,
+        start_date,
+        end_date,
+    ) -> None:
+        """Validate parameters before making the API request.
+
+        Args:
+            hourly: Hourly variables requested.
+            daily: Daily variables requested.
+            models: Ensemble model(s) requested.
+            past_days: Number of past days to include.
+            forecast_days: Number of forecast days.
+            start_date: Explicit start date.
+            end_date: Explicit end date.
+
+        Raises:
+            ValidationError: If any parameter is invalid.
+        """
+        if not any([hourly, daily]):
+            raise ValidationError(
+                "At least one of hourly or daily must be specified."
+            )
+        if not models:
+            raise ValidationError("models is required for the Ensemble API.")
+        if past_days is not None and not (0 <= past_days <= 92):
+            raise ValidationError("past_days must be between 0 and 92.")
+        if forecast_days is not None and not (1 <= forecast_days <= 35):
+            raise ValidationError("forecast_days must be between 1 and 35.")
+        if (start_date is None) != (end_date is None):
+            raise ValidationError(
+                "start_date and end_date must both be provided or both omitted."
+            )

pyopenmeteo/api/flood.py

@@ -0,0 +1,123 @@
+from datetime import date
+
+from pyopenmeteo.core.base_api import BaseAPI
+from pyopenmeteo.core.exceptions import ValidationError
+from pyopenmeteo.core.request_builder import RequestBuilder
+from pyopenmeteo.core.response import WeatherResponse
+from pyopenmeteo.params.flood_vars import DailyFloodVars, FloodModels
+
+
+class FloodAPI(BaseAPI):
+    """Wraps the OpenMeteo Global Flood API.
+
+    Provides daily river discharge forecasts with up to 210 forecast days.
+    Ensemble mode returns individual ensemble member columns in the response.
+
+    Example:
+        >>> from pyopenmeteo.params.flood_vars import DailyFloodVars
+        >>> api = FloodAPI()
+        >>> resp = api.get(
+        ...     (48.20, 16.37),
+        ...     daily=[DailyFloodVars.RIVER_DISCHARGE],
+        ...     forecast_days=30,
+        ... )
+    """
+
+    BASE_URL = "https://flood-api.open-meteo.com/v1/flood"
+
+    def get(
+        self,
+        location: tuple[float, float] | list[float] | str,
+        *,
+        daily: list[DailyFloodVars | str],
+        past_days: int | None = None,
+        forecast_days: int | None = None,
+        start_date: str | date | None = None,
+        end_date: str | date | None = None,
+        models: list[FloodModels | str] | FloodModels | str | None = None,
+        ensemble: bool | None = None,
+    ) -> WeatherResponse:
+        """Fetch river discharge flood forecast data.
+
+        Args:
+            location: ``(latitude, longitude)`` tuple/list or a place-name
+                string resolved via the Geocoding API.
+            daily: Daily flood variables to request. Required.
+            past_days: Include this many past days in the response (0–92).
+            forecast_days: Days ahead to forecast (1–210).
+            start_date: Start of an explicit date range (``YYYY-MM-DD``).
+            end_date: End of an explicit date range (``YYYY-MM-DD``).
+                Required when ``start_date`` is given.
+            models: One or more hydrological models to use. Accepts a single
+                value or a list.
+            ensemble: When ``True``, returns all ensemble members as separate
+                columns in the response.
+
+        Returns:
+            A WeatherResponse wrapping the raw API JSON.
+
+        Raises:
+            ValidationError: If parameters fail pre-flight checks.
+            LocationNotFoundError: If a place-name string cannot be geocoded.
+            APIError: On an HTTP-level error from the server.
+            RateLimitError: On HTTP 429.
+            ServerError: On HTTP 5xx.
+            ConnectionError: If the server is unreachable.
+        """
+        self._validate(
+            daily=daily,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            start_date=start_date,
+            end_date=end_date,
+        )
+
+        lat, lon = self.resolve_location(location)
+
+        if isinstance(models, (str, FloodModels)):
+            models = [models]
+
+        params = RequestBuilder(
+            latitude=lat,
+            longitude=lon,
+            daily=daily,
+            past_days=past_days,
+            forecast_days=forecast_days,
+            start_date=str(start_date) if start_date is not None else None,
+            end_date=str(end_date) if end_date is not None else None,
+            models=models,
+            ensemble=ensemble,
+        ).build()
+
+        return self._get(params)
+
+    def _validate(
+        self,
+        daily,
+        past_days,
+        forecast_days,
+        start_date,
+        end_date,
+    ) -> None:
+        """Validate parameters before making the API request.
+
+        Args:
+            daily: Daily variables requested.
+            past_days: Number of past days to include.
+            forecast_days: Number of forecast days.
+            start_date: Explicit start date.
+            end_date: Explicit end date.
+
+        Raises:
+            ValidationError: If any parameter is invalid.
+        """
+        if not daily:
+            raise ValidationError("daily variables are required for the Flood API.")
+        if past_days is not None and not (0 <= past_days <= 92):
+            raise ValidationError("past_days must be between 0 and 92.")
+        if forecast_days is not None and not (1 <= forecast_days <= 210):
+            raise ValidationError("forecast_days must be between 1 and 210.")
+        if (start_date is None) != (end_date is None):
+            raise ValidationError(
+                "start_date and end_date must both be provided or both omitted."
+            )