TapHome

Forecast.Solar

Packet Parser → HTTP
Submitted by
Last updated: 03. 2026
Forecast.Solar

Forecast.Solar is a free cloud API that provides solar PV energy production estimates based on location, panel orientation, and installed capacity. It combines EU Photovoltaic Geographical Information System (PVGIS) irradiation data with weather forecasts to predict how much energy a solar installation will produce.

TapHome connects to this service over HTTPS using a PacketParser HTTP template. The template polls the /estimate endpoint once per hour (within the free tier limit of 12 requests per hour) and provides six read-only energy sensors: four time-window breakdowns of the current day and daily totals for today and tomorrow. No authentication or API key is required.

Configuration

During template import, five parameters are required. These define the solar installation and are used to construct the API request URL:

  • Latitude — decimal latitude of the PV system location (e.g., 48.1778 for Bratislava). Range: -90 to 90, precision to 0.0001 (~10 m accuracy).
  • Longitude — decimal longitude of the PV system location (e.g., 17.1426 for Bratislava). Range: -180 to 180.
  • PV_declination — panel tilt angle in degrees. 0 = horizontal (flat roof), 90 = vertical (wall-mounted). Typical residential values: 20–45.
  • PV_azimuth — panel orientation relative to compass direction. -180 or 180 = north, -90 = east, 0 = south, 90 = west. For south-facing panels use 0.
  • PV_kWp — total installed PV power in kilowatts peak (e.g., 5 for a 5 kWp system).

All five parameters are stored as Module Variables in TapHome and can be changed after import without re-importing the template.

The Forecast.Solar API uses a different azimuth convention than some other tools. In this API, 0 = south and values increase clockwise (-90 = east, 90 = west, 180/-180 = north). If coming from Home Assistant (where 180 = south), subtract 180 from the HA value.

To find your coordinates, right-click your location in Google Maps and copy the latitude/longitude values.

How it works

The module sends a single HTTP request per poll cycle:

1
2

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

The API returns a JSON response containing cumulative watt-hours at each hour (watt_hours), energy per period (watt_hours_period), instantaneous power (watts), and daily totals (watt_hours_day). The template parses watt_hours and watt_hours_day to derive all six device values.

Two service attributes are read from the response metadata: Place (the resolved location name, e.g., “Bratislava, Slovakia”) and Time zone (e.g., “Europe/Bratislava”). These are visible in the module detail view and confirm that the API correctly identified the location.

Device capabilities

The template provides six read-only energy sensors. All values are in watt-hours (Wh) and represent forecasted PV energy production.

Time-window energy forecast

The day is split into four time windows. Each device shows the expected energy production for that period:

  • Energy 0–9h — forecasted production from midnight to 9:00. Reads the cumulative watt-hours value at the 09:00 timestamp. In most locations this covers sunrise through early morning.
  • Energy 9–12h — forecasted production from 9:00 to 12:00. Calculated as the difference between cumulative values at 12:00 and 09:00.
  • Energy 12–15h — forecasted production from 12:00 to 15:00. Calculated as the difference between cumulative values at 15:00 and 12:00. Typically the highest-output period.
  • Energy 15–0h — forecasted production from 15:00 to end of day. Calculated as the daily total minus the cumulative value at 15:00. In practice, this covers 15:00 until sunset since production drops to zero after dark.

This breakdown allows smart rules to target specific parts of the day — for example, scheduling battery charging during the 12–15h peak or deferring energy-intensive tasks to hours with the highest expected production.

Daily totals
  • PV Energy Forecast (Today) — total forecasted energy production for the current day. Reads the watt_hours_day value for today’s date directly.
  • PV Energy Forecast (Tomorrow) — total forecasted energy production for the next day. Uses tomorrow’s date from the same API response.

These totals are useful for daily planning — for instance, deciding whether to run the heat pump on PV power or grid power based on the expected solar output.

Additional capabilities

The Forecast.Solar API also provides instantaneous power estimates (watts per 15-minute period), energy-per-period data without cumulative calculation, and peak production time identification. Paid tiers add support for multiple panel orientations (2–4 planes), historical production data, clear-sky estimates, and damping factors for shadow adjustment. These can be added in a future template update.

Automation examples

Battery charging based on forecast

Use the PV Energy Forecast (Today) device in a smart rule:

  • Condition: PV Energy Forecast (Today) > 15000 (Wh = 15 kWh)
  • Action: Set battery to “charge from PV only” mode

On cloudy days with low forecast, switch to grid charging during cheap tariff hours instead.

Schedule energy-intensive tasks

Use the time-window devices to identify the best period for high-consumption tasks:

  • Condition: Energy 12–15h > 3000 (Wh)
  • Action: Start pool pump, water heater, or EV charging at 12:00

Troubleshooting

All devices show zero or NaN
  1. Verify internet connectivity on TapHome Core — the template requires outbound HTTPS access to api.forecast.solar
  2. Check whether the API is responding — open https://api.forecast.solar/estimate/48.1778/17.1426/45/0/5 in a browser (replace with your parameters)
  3. If the error contains a status code (e.g., “429”), the rate limit has been exceeded. The free tier allows 12 requests per hour — wait for the rolling window to reset
  4. Status code 400 typically means invalid coordinates (latitude/longitude may be swapped or the location is over water)
Forecast values seem too high or too low
  1. Verify the PV_kWp parameter matches the actual installed capacity — this directly scales all forecast values
  2. Check PV_declination — a horizontal panel (0) produces less than an optimally tilted panel (30–40 in Central Europe)
  3. Check PV_azimuth — verify the orientation matches reality. Remember: 0 = south in this API
  4. The API uses weather forecast data that may not reflect local conditions (nearby buildings, trees, temporary shading). Use the damping factor via paid API tier for shadow adjustment
Energy 15–0h shows unexpectedly low values

This is expected behavior. The “15–0h” device calculates the daily total minus cumulative production at 15:00. Since PV production effectively stops at sunset, this value represents production from 15:00 until sunset — not until midnight. In winter months with early sunset, this value may be very small.

The Forecast.Solar API performs quarterly maintenance on the 1st of each quarter month around midnight UTC (January, April, July, October). During maintenance, the API returns HTTP 503 and devices will show errors temporarily.

Available devices

Forecast.Solar Module
Service Attributes
PlaceLocation name resolved by the API from the submitted coordinates — confirms the API identified the correct location
Time zoneTime zone determined by the API for the configured location — used for correct timestamp alignment
Custom Variables
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

Read (module)
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
Service Attributes
Place
PARSEJSON(output, "$.message.info.place")
Time zone
PARSEJSON(output, "$.message.info.timezone")
Energy 0–9h Variable Read-only

Forecasted PV energy from midnight to 9:00 — cumulative watt-hours at the 09:00 timestamp

numeric Unit: Wh json_path

Energy 0–9h

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

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

PARSETEXT(tmp, date + " 09:00:00\":", ",");
Energy 9–12h Variable Read-only

Forecasted PV energy from 9:00 to 12:00 — difference between cumulative watt-hours at 12:00 and 09:00

numeric Unit: Wh json_path

Energy 9–12h

Read
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
Energy 12–15h Variable Read-only

Forecasted PV energy from 12:00 to 15:00 — difference between cumulative watt-hours at 15:00 and 12:00

numeric Unit: Wh json_path

Energy 12–15h

Read
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
Energy 15–0h Variable Read-only

Forecasted PV energy from 15:00 to end of day — daily total minus cumulative watt-hours at 15:00

numeric Unit: Wh json_path

Energy 15–0h

Read
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
PV Energy Forecast (Today) Variable Read-only

Total forecasted solar energy production for the current day in watt-hours

numeric Unit: Wh json_path

PV Energy Forecast (Today)

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

PARSEJSON(output, "$.result.watt_hours_day." + date)
PV Energy Forecast (Tomorrow) Variable Read-only

Total forecasted solar energy production for the next day in watt-hours

numeric Unit: Wh json_path

PV Energy Forecast (Tomorrow)

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

PARSEJSON(output, "$.result.watt_hours_day." + date)
Connection: Packet Parser → HTTP
Possible improvements (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

Sources