Forecast.Solar

Restful API for Solar plant production and Weather forecast data

User Tools

Site Tools


for_developers

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.

APP integration

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 make sure to cache the API data for at least 15 min..

API key

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).

HTTP return codes

  • 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.

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

Location pre-check

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

Chart event

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));

InfluxDB


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 to send to database.

for_developers.txt · Last modified: 2023/05/03 14:32 by knutkohl