Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
api [2017/10/09 07:29] – [Headers] knutkohl | api [2024/03/30 14:03] (current) – [horizon] knutkohl | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== API ====== | ====== API ====== | ||
- | ===== Request | + | ===== Please note ===== |
- | ==== URL ==== | + | * 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. | ||
+ | |||
+ | ===== Request ===== | ||
The base URL for all API calls against the latest API version is | The base URL for all API calls against the latest API version is | ||
Line 9: | Line 13: | ||
https:// | https:// | ||
- | There is also a [[http:// | + | Please see how to build the concrete |
- | ==== Parameters | + | There is also a [[http:// |
+ | ===== Query parameters ===== | ||
- | === time === | + | :!: If you test calls from a shell, please **always escape the URL** so that an ''&'' |
+ | |||
+ | <code bash> | ||
+ | curl ' | ||
+ | </ | ||
+ | ==== time ==== | ||
+ | |||
+ | //Type: string// | ||
+ | |||
+ | :!: The returned times are always your **local time** unless you give ''? | ||
With this parameter you can define in which format the timestamps will be returned. | With this parameter you can define in which format the timestamps will be returned. | ||
Line 19: | Line 33: | ||
https:// | https:// | ||
- | If not given, a simple date time format is used: '' | + | If not given, a simple |
- | ^ Parameter value ^ Result format | + | ^ Parameter value |
- | | '' | + | | '' |
- | | '' | + | | '' |
- | | '' | + | | '' |
- | | '' | + | | '' |
+ | | '' | ||
+ | | '' | ||
- | === damping === | + | <fc # |
- | With this parameter you can add a factor to adjust the forecasted watts in the morning and the evening. | + | ==== time_tz ==== |
+ | |||
+ | //Type: integer flag (0|1), **only** for '' | ||
+ | |||
+ | For ''? | ||
+ | |||
+ | ==== no_sun ==== | ||
+ | |||
+ | //Type: integer flag (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. | ||
+ | |||
+ | https:// | ||
+ | |||
+ | This will suppress this logic and starts/ends with the first/last available dataset. | ||
+ | |||
+ | ==== damping ==== | ||
+ | |||
+ | //Type: string (comma-separated floats)// | ||
+ | |||
+ | With this parameter, you can add a factor to adjust the forecasted watts in the morning and the evening. | ||
https:// | https:// | ||
- | See this [[Damping|further explanations]]. | + | Please note these [[Damping|further explanations]] (also for '' |
+ | |||
+ | ==== horizon ==== | ||
+ | |||
+ | //Type: string, (comma-separated list of numerics)// | ||
+ | |||
+ | https:// | ||
+ | |||
+ | **By default** the PVGIS built-in horizon information is used. | ||
+ | |||
+ | Please see the detailed explanations [[horizon|here]]. | ||
+ | |||
+ | Example with shadows in the West with stepping of 30°: | ||
+ | |||
+ | ? | ||
+ | |||
+ | The finer the resolution, the better the result. | ||
+ | |||
+ | :!: Make sure, that '' | ||
+ | |||
+ | To suppress the horizon usage **at all**, also the inbuilt PVGIS, set the parameter to '' | ||
+ | |||
+ | ? | ||
+ | |||
+ | ==== inverter ==== | ||
+ | |||
+ | //Type: float, > 0// | ||
+ | |||
+ | With this parameter, you can Forecast.Solar tell what is the maximal power of your inverter in **kilowatts** or **kVA**. | ||
+ | |||
+ | https:// | ||
+ | |||
+ | If your inverter is (very) undersized, the maximum prediction power will be limited to this value. | ||
+ | |||
+ | ==== limit ==== | ||
+ | |||
+ | //Type: integer (1…8)// | ||
+ | |||
+ | With this parameter, you can limit the response days. | ||
+ | |||
+ | https:// | ||
+ | |||
+ | '' | ||
+ | |||
+ | ==== start ==== | ||
+ | |||
+ | //Type: string// | ||
+ | |||
+ | With this parameter, you can define when the forecast should start, words only for the **future**, today and next days, never **backwards**. | ||
+ | |||
+ | https:// | ||
+ | |||
+ | Possible values are any parsable expressions for [[https:// | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | ==== transit ==== | ||
+ | |||
+ | //Type: integer flag (0|1)// | ||
+ | |||
+ | If this parameter is specified, an additional data line is inserted for the solar transit (midday). | ||
+ | |||
+ | https:// | ||
+ | |||
+ | In the '' | ||
+ | |||
+ | ... | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | ... | ||
+ | |||
+ | ==== actual ==== | ||
+ | |||
+ | //Type: float, >= 0// | ||
+ | |||
+ | Actual production until until now, see details [[actual|here]]. | ||
===== Response ===== | ===== Response ===== | ||
+ | |||
+ | ==== HTTP codes ==== | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
==== Content type ==== | ==== Content type ==== | ||
Line 42: | Line 162: | ||
<code bash> | <code bash> | ||
- | curl -H "Accept: application/ | + | curl -H 'Accept: application/ |
</ | </ | ||
- | If no '' | + | If no '' |
JSON : application/ | JSON : application/ | ||
XML : application/ | XML : application/ | ||
CSV : text/csv | CSV : text/csv | ||
+ | YAML : application/ | ||
+ | For CSV an extra header can be set. '' | ||
+ | |||
+ | 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:// | ||
+ | https:// | ||
+ | |||
+ | But the " | ||
==== Headers ==== | ==== Headers ==== | ||
Line 64: | Line 193: | ||
| X-Ratelimit-Remaining | 397 | | | X-Ratelimit-Remaining | 397 | | ||
| X-Ratelimit-Reset | 48 | | | X-Ratelimit-Reset | 48 | | ||
+ | | X-Version | v5.60.0.746 | | ||
See rate limit specification [[api# | See rate limit specification [[api# | ||
+ | |||
+ | Version: <API version> | ||
+ | |||
==== Body ==== | ==== Body ==== | ||
Any JSON and XML response will contain these 2 sections | Any JSON and XML response will contain these 2 sections | ||
- | * '' | + | * '' |
- | * '' | + | * '' |
==== Valid request ==== | ==== Valid request ==== | ||
Line 77: | Line 210: | ||
The '' | The '' | ||
- | < | + | |
- | { | + | " |
- | " | + | ... |
- | ... | + | }, |
- | }, | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | } |
- | " | + | } |
- | } | + | } |
- | } | + | |
- | } | + | The " |
- | </ | + | |
==== Invalid request ==== | ==== Invalid request ==== | ||
Line 99: | Line 231: | ||
The '' | The '' | ||
- | < | + | |
- | { | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | " |
- | " | + | } |
- | } | + | } |
- | } | + | |
- | </ | + | |
==== Rate limits ==== | ==== Rate limits ==== |