For developers

  Each quarter (1st of month around midnight UTC) there is a scheduled maintenance planned. You will get then a HTTP code 503 as response.

The smallest time window in which data can change is 15 min., mainly due to the frequency of change of most weather forecasts.

Therefore, make sure that the API data is cached in your APP for at least 15 min.

Please try to schedule your API calls so that they do not always occur on the hour (or minute 15, 30, 45).

At the moment, we have about double the API call volume in minute 0 of every hour than in other minutes.

The smallest time window in which data can change is 15 min., so you can configure your calls for simplification to the hour (or in 15 min. steps), but then a random delay of 0 … 900 sec. would be nice to distribute the load evenly over 15 minutes.

An example around a full hour:

Minute             Calls  Avg. response time [ms]
2024-03-29 15:58   2098   130
2024-03-29 15:59   1485   138
2024-03-29 16:00   4530   366
2024-03-29 16:01   3412   145
2024-03-29 16:02   3170   167
2024-03-29 16:03   3108   254
2024-03-29 16:04   2625   129

It is not necessary, but helpful for us, if your integrations or APPs or programs would send an User-Agent header.

Some tips for the integration of Forecast.Solar into your APP.

It is not allowed to share an API key with e.g. clients of your product! (It will also not work because of the rate limits for the API key.)

If you are developing an APP that will be delivered to customers in any way, the following setup is suggested:

• Deliver the APP with the use of the Public API by default.
• Provide an APP setting/configuration option where an API key can be entered.

Your customers can now decide whether they want to make a subscription themselves if they are interested in having more data.

This is for example the way, how the Home Assistant integration works.

Please keep in mind, that the result set for subscriptions have other time series steps and handle them properly.

In this case, all API calls are made from your central APP and your API key(s) are never visible to the customers.

Use one or more subscriptions for this purpose, but be sure to observe the rate limits.

For very many API requests, please check the Pay-per-use Plans.

The API key will always match this regular expression and should checked during configuration of an APP.

/[A-Za-z0-9]{16}/

If a API key was given by user, you can check if it is valid with

https://api.forecast.solar/:apikey/info

Returns HTTP status 200 on success with key information as payload, 400 otherwise.

The until date in the response payload is the last date where the key is valid (in timezone Europe/Berlin).

• 200 - ok
• 400 - A malformed API key was provided or the URL is not correct build or the location is invalid (mostly over water)
• 401 or 403 - An invalid API key was provided

See the message section of the response for error code and text.

In case of overload or internal error a generic 503 will be returned and you should try some minutes later again.

To check, if the given location is valid, you can use the check route.

When a chart is loaded, a custom event is fired: fs.chart.loaded on window

The event details hold in container the chart wrapper.

window.addEventListener('fs.chart.loaded', e => console.log(e.detail.container));

• Forecast collector (Docker & Ruby)

Script to convert API response to InfluxDB line format

#!/bin/bash

# set -x

# Settings

# Forecast.Solar API key; optional
# "demo-key" works ONLY with the demo location at lat. 51.15 and lon. 10.45 :-)
API_KEY=demo-key

# Location + plane parameters; required
# https://doc.forecast.solar/doku.php/api:estimate#url_parameters
# :lat/:lon/:dec/:az/:kwp
API_PARAMS=51.15/10.45/35/0/1

# Fields to use; required
FIELDS=watts,watt_hours

# InfluxDB measurement; required
# https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/
MEASUREMENT=forecast_solar

# ---------------------------------------------------------------------------
# DON'T CHANGE HERE
# ---------------------------------------------------------------------------

[ -z "$(which curl)" ] && echo "curl is needed!" && exit 1
[ -z "$API_PARAMS" ]   && echo "Forecast.Solar API_PARAMS= required!" && exit 2
[ -z "$MEASUREMENT" ]  && echo "InfluxDb MEASUREMENT= required!" && exit 3

[ "$API_KEY" ] && API_KEY="$API_KEY/"

# For CSV parsing
IFS=';'

# Fetch
curl -s -H 'Accept: text/csv' "https://api.forecast.solar/${API_KEY}estimate/${API_PARAMS}?time=nanoseconds" |
while read type timestamp value
do
    # Only defined fields
    grep -q $type <<<$FIELDS && echo "$MEASUREMENT,$type value=$value $timestamp"
done

Creates lines in InfluxDb format on STDOUT, ready to send to database.