For developers

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

If you host your APP yourself and the API key is not visible to your customers, please get in touch for an Enterprise account.

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.

• 200: ok
• 400: A malformed API key was provided or the URL is not correct build
• 401 or 403: An invalid API key was provided

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

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?id=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/

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