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.

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.

Open-Meteo Geocoding API (https://geocoding-api.open-meteo.com/v1/search) służy do wyszukiwania miejscowości w Polsce.

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

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
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 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.