Differences

This shows you the differences between two versions of the page.


api [2019/12/30 16:22] – [URL] knutkohl
Line 1: Line 1:
 +====== API ======
 +
 +===== Request =====
 +
 +==== URL ====
 +
 +The base URL for all API calls against the latest API version is
 +
 +  https://api.forecast.solar/
 +
 +There is also a [[http://swagger.forecast.solar/?url=https://api.forecast.solar/swagger.yaml|Swagger Editor]] to inspect for 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 [[Damping|further explanations]].
 +===== Response =====
 +==== Content type ====
 +
 +The API can deliver responses in [[http://en.wikipedia.org/wiki/JSON|JSON]],  [[http://en.wikipedia.org/wiki/XML|XML]] or [[http://en.wikipedia.org/wiki/Comma-separated_values|CSV]] (with semicolon as value separator).
 +
 +The response format have to be defined by the ''Accept'' header like this:
 +
 +<code bash>
 +curl -H "Accept: application/json" https://api.forecast.solar/...
 +</code>
 +
 +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 [[api#rate_limits|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''
 +
 +<code>
 +{
 +    "result": {
 +        ...
 +    },
 +    "message": {
 +        "code": 0,
 +        "type": "success",
 +        "text": "",
 +        "ratelimit": {
 +            "limit": 86400,
 +            "remaining": 86397,
 +            "reset": 48075
 +        }
 +    }
 +}
 +</code>
 +
 +==== Invalid request ====
 +
 +The ''message'' -> ''code'' is here always ''> 0''
 +
 +<code>
 +{
 +    "result": null,
 +    "message": {
 +        "type": "error",
 +        "code": 1,
 +        "text": "A meaningful error message"
 +    }
 +}
 +</code>
 +
 +==== 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.                    |