TapHome

Forecast.Solar

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 03. 2026
Forecast.Solar

Forecast.Solar to darmowe API chmurowe, które dostarcza szacunki produkcji energii słonecznej PV na podstawie lokalizacji, orientacji paneli i zainstalowanej mocy. Łączy dane o nasłonecznieniu z EU Photovoltaic Geographical Information System (PVGIS) z prognozami pogody, aby przewidzieć, ile energii wyprodukuje instalacja solarna.

TapHome łączy się z tą usługą przez HTTPS za pomocą szablonu PacketParser HTTP. Szablon odpytuje endpoint /estimate raz na godzinę (w ramach limitu darmowego planu 12 zapytań na godzinę) i udostępnia sześć czujników energii tylko do odczytu: cztery okna czasowe bieżącego dnia oraz sumy dzienne na dziś i jutro. Nie jest wymagane uwierzytelnianie ani klucz API.

Konfiguracja

Podczas importu szablonu wymaganych jest pięć parametrów. Definiują one instalację solarną i służą do budowy URL zapytania API:

  • Latitude — dziesiętna szerokość geograficzna lokalizacji systemu PV (np. 48.1778 dla Bratysławy). Zakres: od -90 do 90, dokładność do 0,0001 (~10 m).
  • Longitude — dziesiętna długość geograficzna lokalizacji systemu PV (np. 17.1426 dla Bratysławy). Zakres: od -180 do 180.
  • PV_declination — kąt nachylenia paneli w stopniach. 0 = poziomo (dach płaski), 90 = pionowo (montaż ścienny). Typowe wartości mieszkaniowe: 20–45.
  • PV_azimuth — orientacja paneli względem stron świata. -180 lub 180 = północ, -90 = wschód, 0 = południe, 90 = zachód. Dla paneli skierowanych na południe użyj 0.
  • PV_kWp — całkowita zainstalowana moc PV w kilowatach szczytowych (np. 5 dla systemu 5 kWp).

Wszystkie pięć parametrów jest przechowywanych jako zmienne modułu w TapHome i można je zmienić po imporcie bez ponownego importowania szablonu.

API Forecast.Solar używa innej konwencji azymutu niż niektóre inne narzędzia. W tym API 0 = południe, a wartości rosną zgodnie z ruchem wskazówek zegara (-90 = wschód, 90 = zachód, 180/-180 = północ). Jeśli przechodzisz z Home Assistant (gdzie 180 = południe), odejmij 180 od wartości HA.

Aby znaleźć swoje współrzędne, kliknij prawym przyciskiem na swoją lokalizację w Google Maps i skopiuj wartości szerokości/długości geograficznej.

Jak to działa

Moduł wysyła jedno żądanie HTTP na cykl odpytywania:

1
2

GET /estimate/{Latitude}/{Longitude}/{PV_declination}/{PV_azimuth}/{PV_kWp}
Accept: application/json

API zwraca odpowiedź JSON zawierającą skumulowane watogodziny w każdej godzinie (watt_hours), energię za okres (watt_hours_period), moc chwilową (watts) i sumy dzienne (watt_hours_day). Szablon analizuje watt_hours i watt_hours_day, aby uzyskać wszystkie sześć wartości urządzeń.

Dwa atrybuty usługi są odczytywane z metadanych odpowiedzi: Place (rozpoznana nazwa lokalizacji, np. „Bratislava, Slovakia") i Time zone (np. „Europe/Bratislava"). Są widoczne w widoku szczegółów modułu i potwierdzają, że API prawidłowo zidentyfikowało lokalizację.

Możliwości urządzeń

Szablon udostępnia sześć czujników energii tylko do odczytu. Wszystkie wartości podane są w watogodzinach (Wh) i reprezentują prognozowaną produkcję energii PV.

Prognoza energii w oknach czasowych

Dzień jest podzielony na cztery okna czasowe. Każde urządzenie pokazuje oczekiwaną produkcję energii w danym okresie:

  • Energy 0–9h — prognozowana produkcja od północy do 9:00. Odczytuje skumulowaną wartość watogodzin przy znaczniku czasu 09:00. W większości lokalizacji obejmuje wschód słońca do wczesnego ranka.
  • Energy 9–12h — prognozowana produkcja od 9:00 do 12:00. Obliczana jako różnica między wartościami skumulowanymi o 12:00 i 09:00.
  • Energy 12–15h — prognozowana produkcja od 12:00 do 15:00. Obliczana jako różnica między wartościami skumulowanymi o 15:00 i 12:00. Zwykle okres o najwyższej produkcji.
  • Energy 15–0h — prognozowana produkcja od 15:00 do końca dnia. Obliczana jako suma dzienna minus wartość skumulowana o 15:00. W praktyce obejmuje od 15:00 do zachodu słońca, ponieważ produkcja po zmroku spada do zera.

Ten podział pozwala smart rules celować w konkretne części dnia — na przykład zaplanować ładowanie baterii podczas szczytu 12–15h lub odłożyć energochłonne zadania na godziny z najwyższą oczekiwaną produkcją.

Sumy dzienne
  • PV Energy Forecast (Today) — całkowita prognozowana produkcja energii na bieżący dzień. Odczytuje bezpośrednio wartość watt_hours_day dla dzisiejszej daty.
  • PV Energy Forecast (Tomorrow) — całkowita prognozowana produkcja energii na następny dzień. Używa jutrzejszej daty z tej samej odpowiedzi API.

Te sumy są przydatne do planowania dziennego — na przykład decyzji, czy uruchomić pompę ciepła na energii PV czy z sieci na podstawie oczekiwanej produkcji solarnej.

Dodatkowe możliwości

API Forecast.Solar dostarcza również szacunki mocy chwilowej (waty na okresy 15-minutowe), dane energetyczne za okres bez obliczeń kumulacyjnych oraz identyfikację czasu szczytowej produkcji. Płatne plany dodają obsługę wielu orientacji paneli (2–4 płaszczyzny), historyczne dane produkcji, szacunki przy bezchmurnym niebie i współczynniki tłumienia do korekcji zacienienia. Można je dodać w przyszłej aktualizacji szablonu.

Przykłady automatyzacji

Ładowanie baterii na podstawie prognozy

Użyj urządzenia PV Energy Forecast (Today) w smart rule:

  • Warunek: PV Energy Forecast (Today) > 15000 (Wh = 15 kWh)
  • Akcja: ustawić baterię w tryb „ładuj tylko z PV"

W pochmurne dni z niską prognozą przełącz na ładowanie z sieci w godzinach taniej taryfy.

Planowanie energochłonnych zadań

Użyj urządzeń okien czasowych do identyfikacji najlepszego okresu dla zadań o dużym zużyciu:

  • Warunek: Energy 12–15h > 3000 (Wh)
  • Akcja: uruchomić pompę basenową, podgrzewacz wody lub ładowanie EV o 12:00

Rozwiązywanie problemów

Wszystkie urządzenia pokazują zero lub NaN
  1. Sprawdź połączenie internetowe TapHome Core — szablon wymaga wychodzącego dostępu HTTPS do api.forecast.solar
  2. Sprawdź, czy API odpowiada — otwórz https://api.forecast.solar/estimate/48.1778/17.1426/45/0/5 w przeglądarce (zamień na swoje parametry)
  3. Jeśli błąd zawiera kod statusu (np. „429"), limit zapytań został przekroczony. Darmowy plan pozwala na 12 zapytań na godzinę — poczekaj na reset okna kroczącego
  4. Kod statusu 400 zazwyczaj oznacza nieprawidłowe współrzędne (szerokość/długość geograficzna mogą być zamienione lub lokalizacja jest nad wodą)
Wartości prognozy wydają się zbyt wysokie lub niskie
  1. Sprawdź, czy parametr PV_kWp odpowiada rzeczywistej zainstalowanej mocy — bezpośrednio skaluje wszystkie wartości prognozy
  2. Sprawdź PV_declination — panel poziomy (0) produkuje mniej niż optymalnie nachylony panel (30–40 w Europie Środkowej)
  3. Sprawdź PV_azimuth — upewnij się, że orientacja odpowiada rzeczywistości. Pamiętaj: 0 = południe w tym API
  4. API używa danych prognozy pogody, które mogą nie odzwierciedlać warunków lokalnych (pobliskie budynki, drzewa, tymczasowe zacienienie). Użyj współczynnika tłumienia w płatnym planie API do korekcji zacienienia
Energy 15–0h pokazuje niespodziewanie niskie wartości

To oczekiwane zachowanie. Urządzenie „15–0h" oblicza sumę dzienną minus skumulowaną produkcję o 15:00. Ponieważ produkcja PV efektywnie ustaje o zachodzie słońca, wartość ta reprezentuje produkcję od 15:00 do zachodu — nie do północy. W miesiącach zimowych z wczesnym zachodem wartość ta może być bardzo mała.

API Forecast.Solar przeprowadza konserwację kwartalną 1. dnia każdego miesiąca kwartału około północy UTC (styczeń, kwiecień, lipiec, październik). Podczas konserwacji API zwraca HTTP 503, a urządzenia będą tymczasowo wyświetlać błędy.

Dostępne urządzenia

Forecast.Solar Moduł
Atrybuty serwisowe
LokalizacjaNazwa lokalizacji rozwiązana przez API z przesłanych współrzędnych — potwierdza, że API poprawnie zidentyfikowało lokalizację
Strefa czasowaStrefa czasowa określona przez API dla skonfigurowanej lokalizacji — używana do prawidłowego wyrównania znaczników czasu
Zmienne niestandardowe
Latitude (numeric)Geographic latitude of the PV installation in decimal degrees (set during import)
Longitude (numeric)Geographic longitude of the PV installation in decimal degrees (set during import)
PV_declination (numeric)Tilt angle of the PV panels in degrees (0 = horizontal, 90 = vertical)
PV_azimuth (numeric)Compass orientation of the PV panels in degrees (0 = north, 180 = south)
PV_kWp (numeric)Installed peak power of the PV system in kilowatts

forecast.solar

Odczyt (moduł)
VAR response := SENDHTTPREQUEST("/estimate/" + Latitude + "/" + Longitude + "/" + PV_declination + "/" + PV_azimuth + "/" + PV_kWp, "GET", "", "Accept: application/json");
IF response.IsSuccess
    output := response.Content;
ELSE
    ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Atrybuty serwisowe
Place
PARSEJSON(output, "$.message.info.place")
Time zone
PARSEJSON(output, "$.message.info.timezone")
Energia 0–9h Zmienna Tylko do odczytu

Prognozowana energia PV od północy do 9:00 — skumulowane watogodziny przy znaczniku czasu 09:00

numeric Jednostka: Wh json_path

Energia 0–9h

Odczyt
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

PARSETEXT(tmp, date + " 09:00:00\":", ",");
Energia 9–12h Zmienna Tylko do odczytu

Prognozowana energia PV od 9:00 do 12:00 — różnica skumulowanych watogodzin między 12:00 a 09:00

numeric Jednostka: Wh json_path

Energia 9–12h

Odczyt
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var h9 := PARSETEXT(tmp, date + " 09:00:00\":", ",");
var h12 := PARSETEXT(tmp, date + " 12:00:00\":", ",");

h12 - h9
Energia 12–15h Zmienna Tylko do odczytu

Prognozowana energia PV od 12:00 do 15:00 — różnica skumulowanych watogodzin między 15:00 a 12:00

numeric Jednostka: Wh json_path

Energia 12–15h

Odczyt
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var h12 := PARSETEXT(tmp, date + " 12:00:00\":", ",");
var h15 := PARSETEXT(tmp, date + " 15:00:00\":", ",");

h15 - h12
Energia 15–0h Zmienna Tylko do odczytu

Prognozowana energia PV od 15:00 do końca dnia — suma dzienna minus skumulowane watogodziny o 15:00

numeric Jednostka: Wh json_path

Energia 15–0h

Odczyt
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var last := PARSEJSON(output, "$.result.watt_hours_day." + date);

var h15 := PARSETEXT(tmp, date + " 15:00:00\":", ",");

last - h15
Prognoza energii PV (dziś) Zmienna Tylko do odczytu

Całkowita prognozowana produkcja energii słonecznej na bieżący dzień w watogodzinach

numeric Jednostka: Wh json_path

Prognoza energii PV (dziś)

Odczyt
var date := tostring(NOW(), "yyyy-MM-dd");

PARSEJSON(output, "$.result.watt_hours_day." + date)
Prognoza energii PV (jutro) Zmienna Tylko do odczytu

Całkowita prognozowana produkcja energii słonecznej na następny dzień w watogodzinach

numeric Jednostka: Wh json_path

Prognoza energii PV (jutro)

Odczyt
var date := tostring(DATETIMEADD(NOW(), 0, 0, 1), "yyyy-MM-dd");

PARSEJSON(output, "$.result.watt_hours_day." + date)
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (9)
  • Instantaneous Power (watts) — Power average (W) per 15-min period — HA integration exposes this as 'Estimated Power Production — Now'
  • Energy per Period (watt_hours_period) — Energy produced in each 15-min period — alternative to cumulative watt_hours with delta calculation
  • Remaining Energy Today — Daily total minus current cumulative — HA exposes this, template could compute from existing data
  • Peak Production Time — Timestamp of highest watts value — requires iterating watts object, not trivially extractable with PARSEJSON
  • Multi-Plane Support (2-4 planes) — Paid tiers support 2-4 panel orientations per request — requires API key import parameter
  • Historic Production Data — Past production data for comparison — requires paid API key
  • Clear Sky Estimate — Theoretical maximum production without clouds — requires Professional tier API key
  • Damping Factor (shadow adjustment) — Adjusts morning/evening predictions for shadows, trees, buildings — could be added as import parameter
  • Inverter Power Limit — Limits peak prediction to inverter capacity — could be added as import parameter

Źródła