Restful API for Solar plant production and Weather forecast data

User Tools

Site Tools



:!: Please note that 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.


Please check always if your location and plane parameters are valid before you go live! You can do this with the check route.


The base URL for all API calls against the latest API version is

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

Query parameters


Type: string

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

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

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

Parameter value Result format
seconds 1505685600
utc 2017-09-17T22:00:00+00:00
iso8601 2017-09-18T01:00:00+03:00
rfc2822 Mon, 18 Sep 2017 01:00:00 +0300
nanoseconds * 1505685600000000000

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


Type: integer (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 (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.

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


Type: string

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

:!: Please note these further explanations (also for damping_morning and damping_evening)


Type: string (comma-separated list of integers)

You can provide da for horizon information as described here.

The difference is that no file but simply a comma-separated list of values with each number representing the horizon height in degrees in a certain compass direction aroundyour location is used.

For instance, if you have 36 values, PVGIS assumes that the first point is due north, the next is 10 degrees east of north, and so on, until the last point, 10 degrees west of north.

Make sure, that 360 / <your count of values> is an integer.

Example with shadows in the West with stepping of 30°: horizon=0,0,0,0,0,0,10,20,20,20,20,20


Type: float, > 0

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

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


Type: string

With this parameter you can define when the forecast should start.

Possible values are any parsable expressions for PHP DateTime:

  • now
  • 12:00


Content type

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"

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

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

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:

But the “Accept” header is prefered …


These are the most relevant headers returned from API.

Header field Value
Content-Type application/json; charset=utf-8
Date Fri, 22 Sep 2017 08:08:38 GMT
Expires Fri, 22 Sep 2017 08:08:52 GMT
Last-Modified Fri, 22 Sep 2017 08:08:38 GMT
X-Ratelimit-Calls 323
X-Ratelimit-Limit 720
X-Ratelimit-Remaining 397
X-Ratelimit-Reset 48
X-Version v5.60.0.746

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

Valid request

The message –> code is here always 0

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

The “result” contains mostly watts, watt_hours and watt_hours_day sections.

Invalid request

The messagecode is here always > 0

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

Rate limits

Rate limits are defined by hour.

Calls Calls made this period.
Limit The maximum number of requests you're permitted to make per period.
Remaining The number of requests remaining in the current period.
Reset The number of seconds left in the current period.
api.txt · Last modified: 2022/11/21 12:52 by knutkohl