IMGWTools - Narzędzie do pobierania danych IMGW

Biblioteka Python i narzędzia do pobierania danych publicznych z Instytutu Meteorologii i Gospodarki Wodnej (IMGW-PIB). Dane pochodzą z serwisu IMGW Dane Publiczne.

Obsługuje również dane z modeli probabilistycznych opadów maksymalnych (PMAXTP) z serwisu IMGW Klimat.

---

Funkcjonalności

• Biblioteka Python - pip install imgwtools do integracji z innymi projektami
• CLI - narzędzie linii poleceń do pobierania danych
• REST API - FastAPI z dokumentacją OpenAPI/Swagger
• Web GUI - interfejs webowy z mapą interaktywną

Obsługiwane dane:

• Aktualne dane meteorologiczne i hydrologiczne przez API IMGW
• Historyczne dane archiwalne (ZIP/CSV)
• Ostrzeżenia hydrologiczne i meteorologiczne
• Dane PMAXTP (opady maksymalne prawdopodobne)
• Lista stacji z koordynatami

Kluczowa zasada: Dane NIE są przechowywane na serwerze (domyślnie) - generowane są bezpośrednie linki do serwerów IMGW.

Opcjonalne cache'owanie (dane hydrologiczne):

• SQLite database dla danych historycznych
• Lazy loading - dane pobierane przy pierwszym zapytaniu
• Włączane przez IMGW_DB_ENABLED=true

---

Instalacja

# Tylko biblioteka (minimalne zależności: httpx, pydantic)
pip install imgwtools

# Z CLI
pip install imgwtools[cli]

# Z REST API
pip install imgwtools[api]

# Pełna instalacja (CLI + API + DB + spatial)
pip install imgwtools[full]

# Dla deweloperów (z repozytorium)
git clone https://github.com/Daldek/IMGWTools.git
cd IMGWTools
pip install -e ".[dev]"

---

Użycie jako biblioteka Python

IMGWTools można używać jako biblioteki w innych projektach Python (np. HydroLOG).

Dane PMAXTP (opady maksymalne prawdopodobne)

from imgwtools import fetch_pmaxtp

# Pobierz dane dla Warszawy
result = fetch_pmaxtp(latitude=52.23, longitude=21.01, method="POT")

# Opad 15-minutowy z prawdopodobieństwem 50%
precip = result.data.get_precipitation(15, 50)
print(f"Opad 15-min, p=50%: {precip} mm")  # 13.34 mm

# Dostępne czasy trwania: 5, 10, 15, 30, 45, 60, 90, 120, 180... minut
# Dostępne prawdopodobieństwa: 1, 2, 5, 10, 20, 50... %

Aktualne dane hydrologiczne

from imgwtools import fetch_hydro_current

# Wszystkie stacje
stations = fetch_hydro_current()
print(f"Liczba stacji: {len(stations)}")

# Konkretna stacja
data = fetch_hydro_current(station_id="150160180")
print(f"Stan wody: {data[0].water_level_cm} cm")

Aktualne dane synoptyczne

from imgwtools import fetch_synop

# Wszystkie stacje synoptyczne
stations = fetch_synop()

# Po nazwie
warszawa = fetch_synop(station_name="Warszawa")
print(f"Temperatura: {warszawa[0].temperature_c}°C")

Lista stacji z koordynatami

from imgwtools import get_hydro_stations_with_coords

# Pobierz stacje z API hydro-back.imgw.pl
stations = get_hydro_stations_with_coords()
print(f"Liczba stacji: {len(stations)}")

# Filtruj stacje w stanie alarmowym
alarmed = [s for s in stations if s.water_state == "alarm"]
for s in alarmed:
    print(f"{s.name}: {s.latitude}, {s.longitude}")

Pobieranie danych archiwalnych

from imgwtools import download_hydro_data, parse_zip_file

# Pobierz dane dobowe za 2023 rok
zip_data = download_hydro_data("dobowe", 2023)

# Parsuj dane
for station, record in parse_zip_file(zip_data, "dobowe"):
    print(f"{station.name}: {record.water_level_cm} cm ({record.measurement_date})")

Wersja asynchroniczna

import asyncio
from imgwtools import fetch_pmaxtp_async, fetch_hydro_current_async

async def main():
    # Równoległe zapytania
    pmaxtp, hydro = await asyncio.gather(
        fetch_pmaxtp_async(52.23, 21.01),
        fetch_hydro_current_async()
    )
    print(f"PMAXTP: {pmaxtp.data.get_precipitation(15, 50)} mm")
    print(f"Stacje hydro: {len(hydro)}")

asyncio.run(main())

Obsługa błędów

from imgwtools import fetch_pmaxtp, IMGWConnectionError, IMGWValidationError

try:
    result = fetch_pmaxtp(52.23, 21.01)
except IMGWValidationError as e:
    print(f"Błąd walidacji: {e}")  # np. koordynaty poza Polską
except IMGWConnectionError as e:
    print(f"Błąd połączenia: {e}")  # np. timeout, błąd serwera

---

Szybki start (CLI)

# Uruchom serwer API
imgw server --reload

# Pobierz dane hydrologiczne
imgw fetch hydro -i dobowe -y 2023

# Pobierz dane meteorologiczne
imgw fetch meteo -i miesieczne -s synop -y 2020-2023

# Pobierz aktualne dane z API
imgw fetch current hydro

# Pobierz dane PMAXTP
imgw fetch pmaxtp --lat 52.23 --lon 21.01

# Lista stacji
imgw list stations --type hydro

# Cache danych (wymaga IMGW_DB_ENABLED=true)
imgw db init                                   # Inicjalizacja bazy
imgw db stations --refresh                     # Pobranie listy stacji
imgw db cache --years 2020-2023 -i dobowe      # Cache danych dobowych
imgw db query -s 149180020 -y 2023 -i dobowe   # Zapytanie o dane

REST API

Po uruchomieniu serwera (imgw server):

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Przykłady:

# Aktualne dane hydrologiczne
curl http://localhost:8000/api/v1/hydro/current

# Generuj URL do pobrania danych
curl "http://localhost:8000/api/v1/download/url?data_type=hydro&interval=dobowe&year=2023"

Web GUI

Po uruchomieniu serwera dostępne pod http://localhost:8000:

• / - Dashboard
• /download - Formularze pobierania danych
• /stations - Lista stacji (dane pobierane z CSV IMGW)
• /map - Mapa interaktywna (dane z API IMGW)

Każda stacja ma link do oficjalnej strony IMGW: https://hydro.imgw.pl/#/station/{type}/{id}

---

Struktura danych IMGW

Dane hydrologiczne (1951-obecnie)

• dobowe: pliki miesięczne (przed 2023) lub roczne (od 2023)
• miesieczne: pliki roczne
• polroczne_i_roczne: pliki roczne z parametrami T, Q, H

Dane meteorologiczne (1951-obecnie)

• 1951-2000: foldery 5-letnie, pliki roczne
• 2001+: foldery roczne, pliki miesięczne
• Podtypy: klimat, opad, synop

Źródła danych stacji

• Lista stacji hydro: CSV z danepubliczne.imgw.pl (kodowanie CP1250)
• Lista stacji meteo: CSV z danepubliczne.imgw.pl (kodowanie CP1250)
• Współrzędne dla mapy: API danepubliczne.imgw.pl/api/data/hydro

---

Struktura projektu

src/imgwtools/
├── api/          # REST API (FastAPI)
├── cli/          # Narzędzie CLI (Typer)
├── core/         # Logika biznesowa
│   └── url_builder.py  # Generowanie URL-i
├── db/           # Cache SQLite (opcjonalny)
│   ├── cache_manager.py  # Lazy loading
│   ├── repository.py     # Warstwa dostępu do danych
│   └── parsers.py        # Parsery CSV z ZIP
├── web/          # Web GUI (HTMX + Jinja2)
└── config.py     # Konfiguracja

data/             # Metadane + baza SQLite (gdy włączona)
docker/           # Konfiguracja Docker
tests/            # Testy

---

Docker

cd docker
docker-compose up -d

---

Cache bazy danych (opcjonalny)

Dla częstych zapytań o dane historyczne można włączyć lokalną bazę SQLite.

Konfiguracja

# W pliku .env lub zmiennych środowiskowych
IMGW_DB_ENABLED=true
IMGW_DB_PATH=./data/imgw_hydro.db  # domyślna ścieżka

Użycie

# Inicjalizacja bazy
imgw db init

# Pobranie listy stacji (1300+ stacji)
imgw db stations --refresh

# Cache danych dla zakresu lat
imgw db cache --years 2020-2023 --interval dobowe

# Zapytanie o dane dla stacji
imgw db query --station 149180020 --years 2020-2023 --interval dobowe

# Export do CSV
imgw db query --station 149180020 --years 2023 --output dane.csv

# Status bazy (rozmiar, liczba rekordów)
imgw db status

# Optymalizacja bazy
imgw db vacuum

Obsługiwane interwały

Interwał	Opis	Parametry
dobowe	Dane dzienne	-
miesieczne	Dane miesięczne (min/mean/max)	-
polroczne	Dane półroczne/roczne	--param H/Q/T

Lazy loading

Dane są automatycznie pobierane z IMGW przy pierwszym zapytaniu i cache'owane lokalnie. Kolejne zapytania korzystają z cache.

---

Testy

Projekt zawiera kompleksowe testy jednostkowe dla publicznego API.

Uruchamianie testów

# Wszystkie testy
pytest

# Z pokryciem kodu
pytest --cov=imgwtools

# Verbose
pytest -v

Struktura testów

tests/
├── conftest.py              # Wspólne fixtures
├── unit/
│   ├── test_models.py       # Modele danych (17 testów)
│   ├── test_fetch.py        # Funkcje pobierania (19 testów)
│   ├── test_stations.py     # Funkcje stacji (17 testów)
│   └── test_urls.py         # Budowanie URL-i (22 testy)
└── integration/             # Testy integracyjne (TODO)

Pokrycie

Moduł	Pokrycie
models.py	89%
exceptions.py	100%
urls.py	100%
stations.py	59%
fetch.py	45%

Łącznie: 75 testów

---

Dokumentacja

• CLAUDE.md - Instrukcje dla Claude Code
• ARCHITECTURE.md - Architektura systemu
• PRD.md - Wymagania produktu

---

Problemy i wsparcie

Zgłoś problemy w sekcji Issues.

---

Licencja

Projekt udostępniony na licencji MIT. Szczegóły w pliku LICENSE.

---

Autor

• Piotr de Bever