wtr/docs/data-sources.md

Źródła Danych i Cache

wtr. korzysta z publicznych źródeł danych pogodowych i lokalizacyjnych. Dane zewnętrzne są pobierane przez route handlery Next.js, a UI pokazuje brak danych jawnie zamiast uzupełniać je estymacją.

IMGW

Dane	Źródło
Bieżąca analiza IMGW Hybrid	https://meteo.imgw.pl/api/v1/forecast/fcapi
Prognoza godzinowa IMGW ALARO	https://meteo.imgw.pl/api/v1/forecast/fcapi?m=alaro
Dane synoptyczne	https://danepubliczne.imgw.pl/api/data/synop
Pojedyncza stacja synoptyczna	https://danepubliczne.imgw.pl/api/data/synop/id/{id}
Dane hydrologiczne	https://danepubliczne.imgw.pl/api/data/hydro/
Ostrzeżenia meteorologiczne	https://danepubliczne.imgw.pl/api/data/warningsmeteo
Ostrzeżenia hydrologiczne	https://danepubliczne.imgw.pl/api/data/warningshydro
Dane meteorologiczne	https://danepubliczne.imgw.pl/api/data/meteo/
Lista produktów	https://danepubliczne.imgw.pl/api/data/product

IMGW jest traktowane jako źródło bieżących pomiarów, hydro i ostrzeżeń. Prognoza modelowa jest w interfejsie rozdzielona od pomiarów.

IMGW jest używane tylko dla lokalizacji w Polsce. Dla lokalizacji globalnych oficjalne ostrzeżenia IMGW, dane hydrologiczne IMGW, TERYT i powiatowe filtrowanie ostrzeżeń są niedostępne.

Open-Meteo

Open-Meteo Forecast API (https://api.open-meteo.com/v1/forecast) dostarcza pełny 7-dniowy horyzont prognozy, prawdopodobieństwo opadu i fallback, jeśli IMGW ALARO nie odpowiada. Poza Polską dostarcza także modelowe warunki bieżące dla dashboardu.

Open-Meteo Geocoding API (https://geocoding-api.open-meteo.com/v1/search) służy do globalnego wyszukiwania miejscowości. Wynik zawiera m.in. countryCode, admin1, admin2, timezone i współrzędne, które aplikacja zapisuje w modelu lokalizacji.

Przed większym, publicznym lub komercyjnym wdrożeniem należy sprawdzić aktualne warunki korzystania, limity i licencję Open-Meteo albo zastąpić usługę własnym dostawcą.

Capabilities per Region

Capability	Polska	Global
Bieżące warunki	IMGW Hybrid + fallback synop	Open-Meteo model
Prognoza godzinowa	IMGW ALARO + Open-Meteo	Open-Meteo
Prognoza dzienna	IMGW ALARO/Open-Meteo	Open-Meteo
Oficjalne ostrzeżenia	IMGW	niedostępne
Filtrowanie powiatowe	TERYT	niedostępne
Briefy	tak	tak, bez oficjalnych alertów
Push alerty oficjalne	IMGW	niedostępne

Nominatim / OpenStreetMap

Opcjonalny reverse geocoding GPS korzysta z publicznego endpointu:

https://nominatim.openstreetmap.org/reverse

Wywołanie następuje wyłącznie po zgodzie użytkownika. Interfejs pokazuje atrybucję OpenStreetMap. Pozycja GPS jest zaokrąglana do trzech miejsc po przecinku, czyli około 100 metrów.

Przed wdrożeniem o większym ruchu należy sprawdzić aktualną politykę użycia publicznej instancji Nominatim albo użyć własnej usługi.

Cache

Dane	Cache
IMGW Hybrid	120 sekund, stale-while-revalidate=300
Modelowe warunki bieżące Open-Meteo	120 sekund, stale-while-revalidate=300
Prognoza modelowa	900 sekund, stale-while-revalidate=1800
Proxy IMGW danepubliczne.imgw.pl	300 sekund, stale-while-revalidate=600
Wyszukiwanie miejscowości	24 godziny, stale-while-revalidate=7 dni
Reverse geocoding	24 godziny, stale-while-revalidate=7 dni

Service worker dodatkowo może cache'ować odpowiedzi GET dla /api/imgw/*, /api/imgw-current, /api/current-weather i /api/forecast, aby ostatnio pobrane dane były dostępne przy problemach z siecią.

Ograniczenia Źródeł

• Endpoint IMGW Hybrid jest częścią publicznego frontendu meteo.imgw.pl, ale nie jest opisany w stabilnej dokumentacji danepubliczne.imgw.pl.
• Publiczny endpoint synoptyczny IMGW zwraca najnowszy pomiar, a nie historię odczytów.
• IMGW ALARO zwykle dostarcza krótszy horyzont godzinowy niż 7 dni; Open-Meteo uzupełnia dalszy zakres.
• wtr. nie generuje fikcyjnych danych pogodowych.