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
Next revisionBoth sides next revision
api [2017/10/09 07:29] – [Headers] knutkohlapi [2024/02/20 08:10] – [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 parameter, you 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/json" https://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 ====