API

Request

URL

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

https://api.forecast.solar/

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

Query parameters

time

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

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

time_tz

Only for time=utc

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

no_sun

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.

damping

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

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

See this further explanations.

inverter

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

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

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

start

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

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

Possible values are any parsable expressions for PHP DateTime:

now
12:00

Response

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" https://api.forecast.solar/...

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:

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

But the “Accept” header is prefered …

Headers

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

See rate limit specification below.

Body

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
        }
    }
}

Invalid request

The message → code 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.

Table of Contents

API