canairy 0.3.0rc1__tar.gz

canairy-0.3.0rc1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Institut für Angewandte Medizininformatik
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

canairy-0.3.0rc1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: canairy
+Version: 0.3.0rc1
+Summary: Client for German public air-quality APIs (UBA, Hamburger Luftmessnetz)
+Author-email: Michael Blaß <m.blass@uke.de>
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: Pytest
+Classifier: Typing :: Typed
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hishel>=1.0
+Requires-Dist: httpx-limiter>=0.2.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: ratelimit>=2.2.1
+Dynamic: license-file
+
+# canairy
+Python client for public air-quality APIs: Umweltbundesamt (UBA) and Hamburger Luftmessnetz.
+
+## Example 1
+Use data from the Umwelt Bundesamt (UBA)
+
+```python
+from datetime import datetime
+
+from canairy.uba import UBAClient
+import polars as pl
+
+
+client = UBAClient()
+
+# plot hourly NO2 values measured at station 'DENW124' between January and February 2019 
+rsp = client.get_measures(
+    datetime(2019, 1, 1, 0, 0),
+    datetime(2019, 2, 1, 0, 0),
+    "DENW134",
+    5,
+    2
+)
+df = pl.DataFrame(rsp.data)
+df.plot.line(x='date_start', y='value').properties(width=600)
+```
+
+## Example 2
+Use data from the Hamburger Luftmessnetz
+
+```python
+Display monthly PM10 data.
+
+import canairy.hh as hh
+import polars as pl
+
+
+client = hh.HHClient()
+
+res = client.get_component_data("pm10_1m")
+res = pl.DataFrame(res)
+
+res.plot.line(x='datetime', y='value', color='station').properties(width=800, height=400)
+```

canairy-0.3.0rc1/README.md

@@ -0,0 +1,44 @@
+# canairy
+Python client for public air-quality APIs: Umweltbundesamt (UBA) and Hamburger Luftmessnetz.
+
+## Example 1
+Use data from the Umwelt Bundesamt (UBA)
+
+```python
+from datetime import datetime
+
+from canairy.uba import UBAClient
+import polars as pl
+
+
+client = UBAClient()
+
+# plot hourly NO2 values measured at station 'DENW124' between January and February 2019 
+rsp = client.get_measures(
+    datetime(2019, 1, 1, 0, 0),
+    datetime(2019, 2, 1, 0, 0),
+    "DENW134",
+    5,
+    2
+)
+df = pl.DataFrame(rsp.data)
+df.plot.line(x='date_start', y='value').properties(width=600)
+```
+
+## Example 2
+Use data from the Hamburger Luftmessnetz
+
+```python
+Display monthly PM10 data.
+
+import canairy.hh as hh
+import polars as pl
+
+
+client = hh.HHClient()
+
+res = client.get_component_data("pm10_1m")
+res = pl.DataFrame(res)
+
+res.plot.line(x='datetime', y='value', color='station').properties(width=800, height=400)
+```

canairy-0.3.0rc1/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "canairy"
+version = "0.3.0rc1"
+description = "Client for German public air-quality APIs (UBA, Hamburger Luftmessnetz)"
+readme = "README.md"
+authors = [
+    { name = "Michael Blaß", email = "m.blass@uke.de" }
+]
+
+classifiers = [
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Framework :: Pydantic :: 2",
+    "Framework :: Pytest",
+    "Typing :: Typed",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Science/Research"
+]
+
+requires-python = ">=3.11"
+dependencies = [
+    "hishel>=1.0",
+    "httpx-limiter>=0.2.0",
+    "httpx>=0.28.1",
+    "pydantic>=2.11.3",
+    "ratelimit>=2.2.1",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=6.29.5",
+    "mypy>=1.15.0",
+    "pytest>=8.3.5",
+    "ruff>=0.11.5",
+]
+
+[build-system]
+requires = ["setuptools>=79"]
+build-backend = "setuptools.build_meta"
+
+
+[project.scripts]
+aq-downloader = "canairy.scripts.downloader:main"
+
+[[tool.mypy.overrides]]
+module = "ratelimit"
+ignore_missing_imports = true
+
+[tool.mypy]
+plugins = ["pydantic.mypy"]
+
+[tool.ruff.lint]
+extend-select = ["B"]

canairy-0.3.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

canairy-0.3.0rc1/src/canairy/hh/__init__.py

@@ -0,0 +1,2 @@
+from . import aqi as aqi
+from ._client import HHClient as HHClient

canairy-0.3.0rc1/src/canairy/hh/_client.py

@@ -0,0 +1,150 @@
+from datetime import datetime
+import json
+import time
+from typing import Any
+import logging
+
+from hishel.httpx import SyncCacheClient
+import httpx
+from ratelimit import limits, sleep_and_retry
+
+from httpx._types import QueryParamTypes
+
+from ._models import (
+    BaseParams,
+    HHComponent,
+    HHComponentParams,
+    HHComponentData,
+    HHComponentDataParams,
+    HHCore,
+    HHStation,
+    HHStationDataParams,
+    HHThreshold,
+    HHListParams,
+    HHStationData,
+)
+
+from ._typing import GroupCodes_T, TimeSpans_T, Periods_T
+
+__all__ = ["HHClient"]
+
+logger = logging.getLogger(__name__)
+LOG_FMT = "%(levelname)-10s %(message)s"
+MAX_RETRIES = 8
+
+
+class HHClient:
+    BASE_URL = "https://hamburg.luftmessnetz.de/api"
+
+    def __init__(self) -> None:
+        self._client = SyncCacheClient(timeout=60)
+
+    def get_components(
+        self,
+        *,
+        active: bool | None = None,
+        group_code: GroupCodes_T | None = None,
+    ) -> list[HHComponent]:
+        """Retrieve component's metadata."""
+        params = HHComponentParams(active=active, group_code=group_code)
+        return HHComponent.from_response(self._get("components", params))
+
+    def get_component_data(
+        self,
+        code: str,
+        *,
+        stationgroup: str | None = None,
+        timespan: TimeSpans_T | None = None,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[HHComponentData]:
+        params = HHComponentDataParams(
+            stationgroup=stationgroup, timespan=timespan, start=start, end=end
+        )
+        result = self._get(f"components/{code}/data", params)
+        return HHComponentData.from_response(result)
+
+    def get_cores(self) -> list[HHCore]:
+        """Retrieve core metadata."""
+        return HHCore.from_response(self._get("cores"))
+
+    def get_thresholds(self) -> list[HHThreshold]:
+        """Retrieve the thresholds for each each core."""
+        return HHThreshold.from_response(self._get("exceeds"))
+
+    def get_stations(
+        self,
+        *,
+        active: bool | None = None,
+        include_hidden: bool | None = None,
+    ) -> list[HHStation]:
+        """Retrieve a list of all measuring stations and their metadata."""
+        params = HHListParams(active=active, include_hidden=include_hidden)
+        return HHStation.from_response(self._get("stations", params=params))
+
+    def get_station(self, code: str) -> HHStation:
+        """Retrieve metadata of a single station."""
+        return HHStation(**self._get(f"stations/{code}"))
+
+    def get_station_data(
+        self,
+        station_code: str,
+        *,
+        period: Periods_T,
+        timespan: TimeSpans_T,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        core: str | None = None,
+    ) -> list[HHStationData]:
+        params = HHStationDataParams(
+            period=period, timespan=timespan, start=start, end=end, core=core
+        )
+        return HHStationData.from_response(
+            self._get(f"stations/{station_code}/data", params)
+        )
+
+    @sleep_and_retry
+    @limits(120, period=60)
+    def _get(self, endpoint: str, params: BaseParams | None = None) -> Any:
+        params_ = params.model_dump(exclude_none=True) if params else None
+        meta = self._client.head(self._url(endpoint), params=params_).raise_for_status()
+
+        if (meta.headers.get("Transfer-Encoding") == "chunked") or (
+            "content-length" not in meta.headers
+        ):
+            logging.debug("Streaming response")
+            return backoff(self._stream, self._url(endpoint), params=params_)
+
+        logging.debug("Non-streaming response")
+        return (
+            backoff(self._client.get, self._url(endpoint), params=params_)
+            .raise_for_status()
+            .json()
+        )
+
+    def _stream(
+        self,
+        endpoint: str,
+        *,
+        params: QueryParamTypes | None = None,
+        method: str = "GET",
+    ) -> Any:
+        with self._client.stream(method, endpoint, params=params) as stream:
+            stream.raise_for_status()
+            buff = json.loads("".join(data for data in stream.iter_text()))
+        return buff
+
+    def _url(self, endpoint: str) -> str:
+        return f"{HHClient.BASE_URL}/{endpoint}"
+
+
+
+def backoff(func, *args, **kwargs) -> Any:   # type: ignore
+    base = 2
+    for i in range(1, MAX_RETRIES + 1):
+        try:
+            return func(*args, **kwargs)
+        except httpx.RemoteProtocolError:
+            logging.debug(f"RemoteProtoclolError: retry {i}")
+            timeout = base**i
+            time.sleep(timeout)

canairy-0.3.0rc1/src/canairy/hh/_models.py

@@ -0,0 +1,126 @@
+from datetime import datetime
+from typing import Annotated, Any, Self
+
+from pydantic import BaseModel, field_serializer, Field
+
+from ._typing import GroupCodes_T, Periods_T, TimeSpans_T, StationGroup_T
+
+
+class BaseParams(BaseModel):
+    pass
+
+class _ActiveParam(BaseParams):
+    active: bool | None = None
+
+class _HiddenParam(BaseParams):
+    include_hidden: bool | None = None
+
+class HHListParams(_ActiveParam, _HiddenParam):
+    pass
+
+class ItemListModel(BaseParams):
+    @classmethod
+    def from_response(cls, result: list[Any]) -> list[Self]:
+        return [cls(**item) for item in result]
+
+
+
+class HHCore(ItemListModel):
+    code: str
+    active: bool
+    group: StationGroup_T
+    name: str
+    short_name: Annotated[str, Field(validation_alias="shortName")]
+    description: str | None
+    default_period: Annotated[str, Field(validation_alias="defaultPeriod")]
+    periods: list[str]
+    decimal_points: Annotated[int, Field(validation_alias="decimalPoints")]
+    components: list[str]
+
+
+class HHThreshold(ItemListModel):
+    active: bool
+    code: str
+    component: str
+    core: str
+    name: str
+    description: str | None
+    value: float
+    max_count: Annotated[int | None, Field(validation_alias="maxCount")]
+    start: datetime | None
+
+
+class DatetimeRangeParams(BaseParams):
+    start: datetime | None = None
+    end: datetime | None = None
+
+    @field_serializer("start", "end")
+    def custom_dt(self, dt: datetime) -> str:
+        return dt.strftime("%d.%m.%Y %H:%M")
+
+
+class HHComponentParams(_ActiveParam):
+    group_code: GroupCodes_T | None
+
+
+class HHStation(ItemListModel):
+    name: str
+    code: str
+    code_eu: Annotated[str, Field(validation_alias="codeEu")]
+    address: str
+    lat: str
+    lng: str
+    active: bool
+    stationgroups: list[str]
+    measuring_start: Annotated[
+        datetime | None, Field(validation_alias="measuringStart")
+    ]
+    measuring_end: Annotated[datetime | None, Field(validation_alias="measuringEnd")]
+    measuring_height: Annotated[int | None, Field(validation_alias="measuringHeight")]
+    url: str
+    information: str | None
+    components: list[str]
+    active_components: Annotated[list[str], Field(validation_alias="activeComponents")]
+    partials: list
+    lqis: list[str]
+    exceeds: list[str]
+
+
+class HHStationData(ItemListModel):
+    datetime: datetime
+    station: str
+    core: str
+    component: str
+    period: Periods_T
+    value: int
+
+
+class HHComponentDataParams(DatetimeRangeParams):
+    stationgroup: str | None = None
+    timespan: TimeSpans_T | None = None
+
+
+class HHComponentData(ItemListModel):
+    datetime: datetime
+    station: str
+    core: str
+    component: str
+    period: Periods_T
+    value: float | None
+
+
+class HHComponent(ItemListModel):
+    code: str
+    core: str
+    period: str
+    description: str | None
+    unit: str
+    min: int
+    max: int
+    decimal_points: Annotated[int, Field(validation_alias="decimalPoints")]
+
+
+class HHStationDataParams(DatetimeRangeParams):
+    period: Periods_T
+    timespan: TimeSpans_T
+    core: str | None

canairy-0.3.0rc1/src/canairy/hh/_typing.py

@@ -0,0 +1,22 @@
+from typing import Literal
+
+
+Periods_T = Literal["1h", "24h", "8hg", "24hg", "1m", "1y", "1yaot40", "5yaot40"]
+
+TimeSpans_T = Literal[
+    "currentday",
+    "currentmonth",
+    "currentyear",
+    "lastday",
+    "lastweek",
+    "lastmonth",
+    "lastyear",
+    "all",
+    "custom",
+]
+
+StationGroup_T = Literal[
+    "all", "background", "industrial", "meteorology", "ozone", "special", "traffic", "pollution"
+]
+
+GroupCodes_T = Literal["meteorology", "pollution"]

canairy-0.3.0rc1/src/canairy/hh/aqi.py

@@ -0,0 +1,29 @@
+__all__ = ["components", "clf_bins", "clf_thresholds", "ratings"]
+
+
+components = ("no2_1h", "so2_1h", "o3_1h", "co_8hg", "pm10_24hg")
+
+ratings = {
+    1: "sehr gut",
+    2: "gut",
+    3: "befriedigend",
+    4: "ausreichend",
+    5: "schlecht",
+    6: "sehr schlecht",
+}
+
+clf_bins = {
+    "no2_1h": [25, 50, 100, 200, 500],
+    "so2_1h": [25, 50, 120, 350, 1000],
+    "o3_1h": [33, 65, 120, 180, 240],
+    "co_8hg": [1, 2, 4, 10, 30],
+    "pm10_24hg": [10, 20, 35, 50, 100],
+}
+
+clf_thresholds = {
+    "no2_1h": 200,
+    "so2_1h": 350,
+    "o3_1h": 180,
+    "co_8hg": 10,
+    "pm10_24hg": 50,
+}

canairy-0.3.0rc1/src/canairy/scripts/downloader.py

@@ -0,0 +1,87 @@
+import argparse
+import datetime
+import pathlib
+import pickle
+import logging
+import sys
+
+from pydantic import BaseModel
+
+from canairy.uba import UBAClient
+
+
+class Component(BaseModel):
+    id: int
+    code: str
+    scope: int
+
+
+DEFAULT_COMPONENTS = [
+    Component(id=1, code="PM10", scope=2),
+    Component(id=2, code="CO", scope=4),
+    Component(id=3, code="O3", scope=2),
+    Component(id=4, code="SO2", scope=2),
+    Component(id=5, code="NO2", scope=2),
+    Component(id=9, code="PM2", scope=2),
+]
+
+
+def main(argv=None) -> int:
+    if argv is None:
+        argv = sys.argv
+    args = _parse_cl(argv)
+
+    if not args.outpath.exists():
+        args.outpath.mkdir(parents=True)
+
+    logging.basicConfig(
+        filename=str(args.outpath.joinpath("download.log")),
+        level=logging.INFO,
+        format="%(asctime)s - %(levelname)s - %(message)s"
+    )
+
+    client = UBAClient()
+    download_multi_station(client, **vars(args))
+
+    return 0
+
+
+def download_multi_station(client, year_start: int, outpath: pathlib.Path) -> None:
+
+    for year in range(year_start, datetime.date.today().year): 
+        logging.info(f"New year: {year}")
+        date_dir = outpath.joinpath(str(year))
+        if not date_dir.exists():
+            date_dir.mkdir(parents=True)
+
+        for station in client.get_stations().data:
+            logging.info(f"Station: {station.code}")
+            station_dir = date_dir.joinpath(f"{station.code}")
+            if not station_dir.exists():
+                station_dir.mkdir()
+            for component in DEFAULT_COMPONENTS:
+                logging.info(f"Component: {component.code}")
+                res = client.get_measures(
+                    datetime.datetime(year, 1, 1, 0, 0),
+                    datetime.datetime(year+1, 12, 31, 23, 0),
+                    station.id,
+                    component.id,
+                    component.scope,
+                )
+                fname = station_dir.joinpath(f"{component.code}_{component.scope}.pkl")
+                with fname.open("wb") as file:
+                    pickle.dump(res.model_dump(mode="json"), file)
+
+
+def _parse_cl(argv) -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-y", "--year-start", type=int, default=2016)
+    parser.add_argument("outpath", type=pathlib.Path)
+    return parser.parse_args(argv[1:])
+
+
+def _int_or_str(val: str) -> int | str:
+    try:
+        return int(val)
+    except ValueError:
+        return val

canairy-0.3.0rc1/src/canairy/uba/__init__.py

@@ -0,0 +1 @@
+from ._client import UBAClient as UBAClient