API

• The forecasts are updated at the earliest every 15 min. due to the weather data used, so it makes no sense to query more often than every 15 min.!
• If you get an 404 Page not found please always double check your URL. The API ist very strict configured to reject maleformed queries as early as possible to minimize server load!
• 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 base URL for all API calls against the latest API version is

https://api.forecast.solar/

Please see how to build the concrete URLs and the example.

There is also a Swagger Editor to inspect for proper request URLs.

If you test calls from a shell, please always escape the URL so that an & is not interpreted by the shell!

curl 'https://api.forecast.solar/...?param1=1&param2=2&...'

Type: string

  The returned times are always your local time unless you give ?time=utc !

With this parameter you can define in which format the timestamps will be returned.

https://api.forecast.solar/...?time=...

If not given, a simple parsable date time format is used: 2017-09-18 01:00:00

* Nanoseconds are helpful when data will be used for InfluxDB API.

Type: integer flag (0|1), only for time=utc

For ?time=utc&time_tz=0 timestamps are formated also as 2017-09-17 22:00:00

Type: integer flag (0|1)

By default the forecast is filled up to show the time from sunrise to sunset.

This will result in irregular timestamp offsets at the beginning and the end of the day but you have a full daylight forecast cycle.

https://api.forecast.solar/...?no_sun=1

This will suppress this logic and starts/ends with the first/last available dataset.

Type: string (comma-separated floats); -0.25 .. 5

With this parameter, you can add a factor to adjust the forecasted watts in the morning and the evening.

https://api.forecast.solar/...?damping=...
https://api.forecast.solar/...?damping_morning=...&damping_evening=...

If damping_morning and/or damping_evening is given, damping will be ignored!

Please note these further explanations.

Type: string, (comma-separated list of numerics)

https://api.forecast.solar/...?horizon=...

By default the PVGIS built-in horizon information is used.

Please see the detailed explanations here.

Example with shadows in the West with stepping of 30°:

?horizon=0,0,0,0,0,0,10,20,20,20,20,20

The finer the resolution, the better the result.

Make sure, that 360 / <your count of values> is an integer and less than 4 values will be ignored!

To suppress the horizon usage at all, also the inbuilt PVGIS, set the parameter to 0.

?horizon=0

Type: float, > 0

With this parameter, you can Forecast.Solar tell what is the maximal power of your inverter in kilowatts or kVA.

https://api.forecast.solar/...?inverter=...

If your inverter is (very) undersized, the maximum prediction power will be limited to this value.

Type: integer (1…8)

With this parameter, you can limit the response days.

https://api.forecast.solar/...?limit=...

1 means today only, 2 today and tomorrow and so on. (max. 8 for today plus 7 days in advance)

Type: string

With this parameter, you can define when the forecast should start, words only for the future, today and next days, never backwards.

https://api.forecast.solar/...?start=...

Possible values are any parsable expressions for PHP DateTime:

• now
• 12:00

Type: integer flag (0|1)

If this parameter is specified, an additional data line is inserted for the solar transit (midday).

https://api.forecast.solar/...?transit=...

In the watts result data, here at 11:57:

...
"2023-11-18 11:45:00": 1601,
"2023-11-18 11:57:00": 1793,
"2023-11-18 12:00:00": 1776,
...

Type: integer, minutes (15|30|60)

If you have an account which provides shorter periods than 1 h, you can request other result resolution.

With a “Professional Plus” account you will get by default a result resolution of 15 min., but you can request e.g. 1 h with

https://api.forecast.solar/...?resolution=60

Type: string, only key-value at the moment

Transforms the default response data format (timestamp: value) to

{
    "result": {
        "watts": [
            {
                "timestamp": "2024-09-19 06:53:38",
                "value": 0.0
            },
            {
                "timestamp": "2024-09-19 07:00:00",
                "value": 109.0
            },
            ...

(Not useful in combination requesting CSV data format)

https://api.forecast.solar/...?format=key-value

Type: float, >= 0

Actual production until until now, details.

  The returned times are always your local time unless you give ?time=utc !

• 200 OK - All fine
• 400 Bad Request - Somethig is wrong, check the error message.
• 422 Unprocessable Entity - In case of an invalid location or plane definition, check the error message.

The API can deliver responses in JSON, XML or CSV (with semicolon as value separator).

The response format have to be defined by the Accept header like this:

curl -H 'Accept: application/json' 'https://api.forecast.solar/...'

If no Accept header is defined, JSON will be delivered by default. These values are accepted for the Accept header:

JSON : application/json
XML  : application/xml, text/xml
CSV  : text/csv
YAML : application/yaml

For CSV an extra header can be set. X-Separator defines the field separator to be used instead of ;. To force a tab (\t) as separator please use X-Separator: TAB

If you have a limited device which can only do simple GETs, you can define the response content types other than JSON as file extension like this:

https://api.forecast.solar/.../1.xml
https://api.forecast.solar/.../1.csv

But the “Accept” header is prefered …

These are the most relevant headers returned from API.

See rate limit specification below.

Version: <API version>.<build>

Any JSON and XML response will contain these 2 sections

• result - In case of correct API call with requested data
• message - Useful in case of an error during the API call

The message –> code is here always 0

{
    "result": {
        ...
    },
    "message": {
        "code": 0,
        "type": "success",
        "text": "",
        "ratelimit": {
            "limit": 86400,
            "remaining": 86397
        }
    }
}

The “result” contains watts, watt_hours_period, watt_hours and watt_hours_day sections with the timestamp as key and the value.

Example of a valid response:

{
    "result": {
        "watts": {
            "2024-09-19 06:53:38": 0.0,
            "2024-09-19 07:00:00": 109.0,
            ...

The message → code is here always > 0

{
    "result": null,
    "message": {
        "type": "error",
        "code": 1,
        "text": "A meaningful error message"
    }
}

The rate limit is rolling, i.e. not per hour on the clock but per last 60 minutes.