wtr/docs/api.md

Wewnętrzne Endpointy API

Wszystkie zewnętrzne źródła danych są wywoływane przez route handlery Next.js w app/api. Dzięki temu aplikacja ma jedno miejsce na walidację parametrów, cache, normalizację błędów i obsługę ograniczeń przeglądarki.

Dane Pogodowe i Lokalizacje

Metoda	Endpoint	Przeznaczenie
GET	/api/current-weather?latitude={lat}&longitude={lon}&region={PL|GLOBAL}	Zwraca znormalizowane bieżące warunki. Dla PL używa IMGW Hybrid, dla GLOBAL modelowych warunków Open-Meteo.
GET	/api/forecast?latitude={lat}&longitude={lon}&region={PL|GLOBAL}	Zwraca 7-dniową prognozę modelową dla współrzędnych. Dla PL łączy IMGW ALARO z Open-Meteo, dla GLOBAL używa Open-Meteo. Niepoprawne współrzędne zwracają 400, awaria źródła 502.
GET	/api/imgw-current?latitude={lat}&longitude={lon}	Pobiera surową lokalną analizę IMGW Hybrid dla współrzędnych. Niepoprawne współrzędne zwracają 400, awaria źródła 502.
GET	/api/imgw/{path}	Proxy allowlistowanych endpointów IMGW danepubliczne.imgw.pl. Obsługuje kolekcje synop, hydro, meteo, warningsmeteo, warningshydro, product oraz szczegół synop/id/{id}. Nieobsługiwana ścieżka zwraca 404.
GET	/api/locations/search?query={query}&language={pl|en}	Wyszukuje miejscowości globalnie przez Open-Meteo Geocoding. Wyniki zawierają countryCode, admin1, admin2, timezone i region PL albo GLOBAL. Zapytania krótsze niż 2 znaki albo dłuższe niż 80 znaków zwracają pustą listę.
GET	/api/locations/reverse?latitude={lat}&longitude={lon}&language={pl|en}	Ustala nazwę miejsca dla pozycji GPS przez Nominatim / OpenStreetMap. Współrzędne są zaokrąglane do trzech miejsc po przecinku.

Powiadomienia

Endpointy powiadomień działają w runtime Node.js, bo korzystają z web-push i lokalnego magazynu SQLite dla subskrypcji.

Metoda	Endpoint	Przeznaczenie
GET	/api/notifications/vapid-key	Zwraca publiczny klucz VAPID oraz informację, czy Web Push jest skonfigurowany.
POST	/api/notifications/subscriptions	Zapisuje lub aktualizuje subskrypcję Web Push dla urządzenia. Przyjmuje region PL/GLOBAL, preferencje ostrzeżeń, briefu porannego, briefu wieczornego, lokalizację, język, województwo dla PL i opcjonalny powiat TERYT.
DELETE	/api/notifications/subscriptions	Usuwa subskrypcję Web Push po jej endpointcie.
POST	/api/notifications/test	Wysyła powiadomienie testowe na wskazany endpoint subskrypcji.
GET	/api/notifications/check	Endpoint harmonogramu sprawdzający nowe ostrzeżenia meteorologiczne IMGW i wysyłający Web Push do pasujących subskrypcji.
GET	/api/notifications/daily-brief	Endpoint harmonogramu wysyłający raz dziennie poranny brief dla subskrypcji z włączoną opcją i zapisaną lokalizacją.
GET	/api/notifications/tomorrow-brief	Endpoint harmonogramu wysyłający wieczorny brief z prognozą na kolejny dzień.

Autoryzacja Harmonogramu

Endpointy harmonogramu:

• /api/notifications/check
• /api/notifications/daily-brief
• /api/notifications/tomorrow-brief

w produkcji wymagają sekretu NOTIFICATIONS_CRON_SECRET przekazanego jednym z nagłówków:

Authorization: Bearer <NOTIFICATIONS_CRON_SECRET>
x-cron-secret: <NOTIFICATIONS_CRON_SECRET>

Jeśli NOTIFICATIONS_CRON_SECRET nie jest ustawiony, endpointy harmonogramu są dostępne tylko poza NODE_ENV=production.

Cache i Odpowiedzi

Endpoint	Cache
/api/forecast	s-maxage=900, stale-while-revalidate=1800
/api/current-weather	s-maxage=120, stale-while-revalidate=300
/api/imgw-current	s-maxage=120, stale-while-revalidate=300
/api/imgw/{path}	s-maxage=300, stale-while-revalidate=600
/api/locations/search	s-maxage=86400, stale-while-revalidate=604800
/api/locations/reverse	s-maxage=86400, stale-while-revalidate=604800

Route handlery zwracają kontrolowane odpowiedzi JSON. Błędy zewnętrznych usług są mapowane na czytelne statusy HTTP, zwykle 400, 404, 502 albo 503.

Szczególny Przypadek IMGW

Publiczne endpointy ostrzeżeń IMGW potrafią zwrócić HTTP 404 z treścią:

{ "status": false, "message": "No products were found" }

Dla warningsmeteo i warningshydro aplikacja traktuje ten wariant jako poprawną pustą listę ostrzeżeń, a nie awarię źródła danych.