Table of Contents
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 datamessage
- 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. |