API

This is an old revision of the document!


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 UI to build proper request URLs.

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 date time format is used: 2017-09-18 01:00:00

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

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.

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

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