Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
api [2017/10/09 07:29] – [Headers] knutkohlapi [2024/02/20 08:10] (current) – [time] 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://api.forecast.solar/   https://api.forecast.solar/
  
-There is also a [[http://swagger.forecast.solar/?url=https://api.forecast.solar/swagger.yaml|Swagger UI]] to build proper request URLs.+Please see how to build the concrete [[api:estimate#url_parameters|URLs]] and the [[api:estimate#example|example]].
  
-==== Parameters ====+There is also a [[http://swagger.forecast.solar/|Swagger Editor]] to inspect for proper request URLs. 
 +===== Query parameters =====
  
-=== time ===+:!: If you test calls from a shell, please **always escape the URL** so that an ''&'' is not interpreted by the shell! 
 + 
 +<code bash> 
 +curl 'https://api.forecast.solar/...?param1=1&param2=2&...' 
 +</code> 
 +==== time ===
 + 
 +//Type: string// 
 + 
 +:!:   The returned times are always your **local time** unless you give ''?time=utc'' !
  
 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://api.forecast.solar/...?time=...   https://api.forecast.solar/...?time=...
  
-If not given, a simple date time format is used: ''2017-09-18 01:00:00''+If not given, a simple parsable date time format is used: ''2017-09-18 01:00:00''
  
-^ Parameter value  ^ Result format                    ^ +^ Parameter value   ^ Result format                    ^ 
-| ''seconds''      | 1505685600                       | +| ''utc''           | 2017-09-17T22:00:00+00:00        | 
-| ''utc''          | 2017-09-18T01:00:00+03:00        | +| ''iso8601''       | 2017-09-18T01:00:00+03:00        | 
-| ''iso8601''        | 2017-09-18T01:00:00+03:00        | +| ''rfc2822''       | Mon, 18 Sep 2017 01:00:00 +0300  
-| ''rfc2822''      | Mon, 18 Sep 2017 01:00:00 +0300  |+| ''seconds''       | 1505685600                       | 
 +| ''milliseconds''  | 1505685600000 
 +| ''nanoseconds'' <fc #ff0000>*</fc> | 1505685600000000000 |
  
-=== damping ===+<fc #ff0000>*</fc> Nanoseconds are helpful when data will be used for [[https://docs.influxdata.com/influxdb/v2.4/write-data/developer-tools/api/|InfluxDB API]].
  
-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 ''time=utc''// 
 + 
 +For ''?time=utc&time_tz=0'' timestamps are formated also as ''2017-09-17 22:00:00'' 
 + 
 +==== 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://api.forecast.solar/...?no_sun=1 
 + 
 +This will suppress this logic and starts/ends with the first/last available dataset. 
 + 
 +==== damping ==== 
 + 
 +//Type: string (comma-separated floats)// 
 + 
 +With this parameteryou can add a factor to adjust the forecasted watts in the morning and the evening.
  
   https://api.forecast.solar/...?damping=...   https://api.forecast.solar/...?damping=...
  
-See this [[Damping|further explanations]].+Please note these [[Damping|further explanations]] (also for ''damping_morning'' and ''damping_evening''
 + 
 +==== horizon ==== 
 + 
 +//Type: string, (comma-separated list of numerics)// 
 + 
 +  https://api.forecast.solar/...?horizon=... 
 + 
 +**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°: 
 + 
 +  ?horizon=0,0,0,0,0,0,10,20,20,20,20,20 
 + 
 +:!: Make sure, that ''360 / <your count of values>'' is an integer and less than **4** values will be ignored! 
 + 
 +To suppress the horizon usage **at all**, set the parameter to ''0''
 + 
 +  ?horizon=0 
 + 
 +==== 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://api.forecast.solar/...?inverter=... 
 + 
 +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://api.forecast.solar/...?limit=... 
 + 
 +''1'' means today only, ''2'' today and tomorrow and so on. (max. ''8'' for today plus 7 days in advance) 
 + 
 +==== 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://api.forecast.solar/...?start=... 
 + 
 +Possible values are any parsable expressions for [[https://www.php.net/manual/en/datetime.construct.php|PHP DateTime]]: 
 +  * ''now'' 
 +  * ''12:00'' 
 + 
 +==== transit ==== 
 + 
 +//Type: integer flag (0|1)// 
 + 
 +If this parameter is specified, an additional data line is inserted for the solar transit (midday). 
 + 
 +  https://api.forecast.solar/...?transit=... 
 + 
 +In the ''watts'' result data, here at ''11:57'': 
 + 
 +  ... 
 +  "2023-11-18 11:45:00": 1601, 
 +  "2023-11-18 11:57:00": 1793, 
 +  "2023-11-18 12:00:00": 1776, 
 +  ... 
 + 
 +==== actual ==== 
 + 
 +//Type: float, >= 0// 
 + 
 +Actual production until until now, see details [[actual|here]].
 ===== Response ===== ===== Response =====
 +
 +==== HTTP codes ====
 +
 +  * ''200 OK'' - All fine
 +  * ''400 Bad Request'' - Somethig is wrong, check the error message.
 +  * ''422 Unprocessable Entity'' - In case of an invalid location or plane definition, check the error message.
 ==== Content type ==== ==== Content type ====
  
Line 42: Line 160:
  
 <code bash> <code bash>
-curl -H "Accept: application/jsonhttps://api.forecast.solar/...+curl -H 'Accept: application/json' 'https://api.forecast.solar/...'
 </code> </code>
  
-If no ''Accept'' header is defined, JSON will delivered by default. These values are accepted for the ''Accept'' header:+If no ''Accept'' header is defined, JSON will be delivered by default. These values are accepted for the ''Accept'' header:
  
   JSON : application/json   JSON : application/json
   XML  : application/xml, text/xml   XML  : application/xml, text/xml
   CSV  : text/csv   CSV  : text/csv
 +  YAML : application/yaml
  
 +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 ==== ==== Headers ====
  
Line 64: Line 191:
 | 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#rate_limits|below]]. See rate limit specification [[api#rate_limits|below]].
 +
 +Version: <API version>.<build>
 +
 ==== Body ==== ==== Body ====
  
 Any JSON and XML response will contain these 2 sections Any JSON and XML response will contain these 2 sections
  
-  * ''**result**''in case of correct API call with requested data +  * ''**result**''In case of correct API call with requested data 
-  * ''**message**''useful in case of an error during the API call+  * ''**message**''Useful in case of an error during the API call
  
 ==== Valid request ==== ==== Valid request ====
Line 77: Line 208:
 The ''message'' --> ''code'' is here always ''0'' The ''message'' --> ''code'' is here always ''0''
  
-<code> +  
-+      "result":
-    "result":+          ... 
-        ... +      }, 
-    }, +      "message":
-    "message":+          "code": 0, 
-        "code": 0, +          "type": "success", 
-        "type": "success", +          "text": "", 
-        "text": "", +          "ratelimit":
-        "ratelimit":+              "limit": 86400, 
-            "limit": 86400, +              "remaining": 86397 
-            "remaining": 86397+          
-            "reset": 48075 +      
-        +  
-    + 
-+The "result" contains mostly ''watts'', ''watt_hours'' and ''watt_hours_day'' sections.
-</code>+
  
 ==== Invalid request ==== ==== Invalid request ====
Line 99: Line 229:
 The ''message'' -> ''code'' is here always ''> 0'' The ''message'' -> ''code'' is here always ''> 0''
  
-<code> +  
-+      "result": null, 
-    "result": null, +      "message":
-    "message":+          "type": "error", 
-        "type": "error", +          "code": 1, 
-        "code": 1, +          "text": "A meaningful error message" 
-        "text": "A meaningful error message" +      
-    +  }
-} +
-</code>+
  
 ==== Rate limits ==== ==== Rate limits ====