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
Last revisionBoth sides next revision
api:estimate [2019/12/30 14:50] – [Personal] knutkohlapi:estimate [2024/02/15 12:07] – [Example] knutkohl
Line 1: Line 1:
-Examples here use the ''estimate'' mode, you can replace it with ''history'' for historic data or with ''clearsky'' for theoretic results for clear sky weather. 
- 
 ===== Solar production estimate ===== ===== Solar production estimate =====
  
Line 11: Line 9:
 ===== Clear sky solar production ===== ===== Clear sky solar production =====
  
-If there were no clouds it would be a clear sky. `clearsky` thus calculates the theoretically possible production.+If there were no clouds it would be a clear sky. ''clearsky'' thus calculates the theoretically possible production. 
 + 
 +===== URL parameters ===== 
 + 
 +:!:   Please check **always** if your **location and plane parameters are valid** before you go live! You can do this with the [[api:misc|check route]]. 
 + 
 +  * **'':apikey''** - personal **API key** for registered users; string 
 +  * **'':lat''** - **latitude** of location, ''-90'' (south) ... ''90'' (north); handeled with a precission of 0.0001 or abt. 10 m 
 +  * **'':lon''** - **longitude** of location, ''-180'' (west) ... ''180'' (east); handeled with a precission of 0.0001 or abt. 10 m 
 +  * **'':dec''** - plane **declination**, ''0'' (horizontal) ... ''90'' (vertical) - always in relation to the earth's surface; integer 
 +  * **'':az''** - plane **azimuth**, ''-180'' ... ''180'' (-180 = north, -90 = east, 0 = south, 90 = west, 180 = north); integer 
 +  * **'':kwp''** - installed **modules power** in ''kilo watt''; float 
 + 
 +Please see the examples below. 
 + 
 +**'':lat''** and **'':lon''** can also be given as  
 +  * ''<degrees>,<arc minutes>,<arc seconds>(N|S|W|E)'', e.g. ''12,10,34N'' == 12.17611   
 +  * ''<degrees>°<arc minutes>'<arc seconds>”(N|S|W|E)'', e.g. ''12°10'34”N'' == 12.17611 
 + 
 +**Azimuth** 
 + 
 +:!:   Please note that e.g. Home Assistant uses internal a ''0° ... 360°'' logic, so make sure to translate for direct API calls ... 
 + 
 +{{:api:windrose.png?240|}} 
 + 
 +For the lazy ones, if you have an exact ''NE'', ''E'', ''SE'', ''S'', ''SW'', ''W'', ''NW'' or ''N'' azimuth, you can also use their identifiers ... 
 + 
 +You can poke around with the [[http://swagger.forecast.solar/|Swagger Editor]] to build proper request URLs. 
 + 
 +To find your azimuth, please refer to these [[:Find your azimuth|instructions]]. 
 + 
 +====== Account models ====== 
 + 
 +(Documentation here use the ''estimate'' mode, you can replace it with ''history'' for historic data or with ''clearsky'' for theoretic results for clear sky conditions.)
  
 ===== Public ===== ===== Public =====
  
-  * One plane can be accessed by an API call+  * **1** plane can be accessed by an API call
   * only ''estimate'' data available   * only ''estimate'' data available
  
   https://api.forecast.solar/estimate/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/estimate/:lat/:lon/:dec/:az/:kwp
  
-===== Personal =====+===== Personal / Personal Plus =====
  
-  * One plane can be accessed by an API call+  * **1** (Personal) or combined data of **2** (Personal Plus) planes can be accessed by an API call
   * ''estimate'' and ''history'' data are available   * ''estimate'' and ''history'' data are available
  
   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec/:az/:kwp
 +  https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2
 +===== Professional / Professional Plus =====
  
-===== Professional ===== +  * Combined data of up to **3** (Professional) or **4** (Professional Plus) planes can be accessed by one API call
- +
-  * Combined data of up to 3 planes can be accessed by one API call+
   * ''estimate'', ''history'' and ''clearsky'' data are available   * ''estimate'', ''history'' and ''clearsky'' data are available
  
Line 35: Line 66:
   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2
   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2/:dec3/:az3/:kwp3   https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2/:dec3/:az3/:kwp3
 +  https://api.forecast.solar/:apikey/estimate/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2/:dec3/:az3/:kwp3/:dec4/:az4/:kwp4
  
-===== URL parameters =====+====== Responses ======
  
-  * **''apikey''** - personal **API key** for registered users +===== Watts, Watt hours over day, Watt hours per period, Watt hours per day =====
-  * **''lat''** - **latitude** of location, ''-90'' (south) ... ''90'' (north) +
-  * **''lon''** - **longitude** of location, ''-180'' (west) ... ''180'' (east) +
-  * **''dec''** - plane **declination**, ''0'' (horizontal) ... ''90'' (vertical) +
-  * **''az ''**  - plane **azimuth**, ''-180'' ... ''180'' (-180 = north, -90 = east, 0 = south, 90 = west, 180 = north) +
-  * **''kwp''** - installed **modules power** in ''kilo watt''+
  
-You can poke around with the [[http://swagger.forecast.solar/?url=https://api.forecast.solar/swagger.yaml|Swagger UI]] to build proper request URLs. +There are also routes available to query only the watts, watt hours, watt hours per period or watt hours per day.
-===== Watts, Watt hours, Watt hours day ===== +
- +
-There are also routes available to query only the watts, watt hours or watt hours per day.+
  
   https://api.forecast.solar/estimate/watts/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/estimate/watts/:lat/:lon/:dec/:az/:kwp
   https://api.forecast.solar/estimate/watthours/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/estimate/watthours/:lat/:lon/:dec/:az/:kwp
 +  https://api.forecast.solar/estimate/watthours/period/:lat/:lon/:dec/:az/:kwp
   https://api.forecast.solar/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp
  
Line 58: Line 83:
   https://api.forecast.solar/:apikey/estimate/watts/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/:apikey/estimate/watts/:lat/:lon/:dec/:az/:kwp
   https://api.forecast.solar/:apikey/estimate/watthours/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/:apikey/estimate/watthours/:lat/:lon/:dec/:az/:kwp
 +  https://api.forecast.solar/:apikey/estimate/watthours/period/:lat/:lon/:dec/:az/:kwp
   https://api.forecast.solar/:apikey/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp   https://api.forecast.solar/:apikey/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp
  
-Here you can query with a Professional account also up to 3 planes at once. +===== Content ===== 
-===== Example =====+ 
 +The response have in the ''result'' section 4 entries: 
 + 
 +  * ''watts'' - Watts (power) average for the period 
 +  * ''watt_hours_period'' - Watt hours (energy) for the period 
 +  * ''watt_hours'' - Watt hours (energy) **summarized over the day** 
 +  * ''watt_hours_day'' - Watt hours (energy) summarized for each day 
 + 
 +:!:   For ''watts'' and ''watt_hours_period'' the value is always for the **period** from **last timestamp to the timsestamp in the key**. 
 + 
 +====== Example ======
  
 Get solar production estimate per day as [[:api#Response content type|CSV]] for 52° north, 12° east, for a installation with a declination of 37° looking south (0°) with 5.67 kWp Get solar production estimate per day as [[:api#Response content type|CSV]] for 52° north, 12° east, for a installation with a declination of 37° looking south (0°) with 5.67 kWp
  
 <code bash> <code bash>
-curl -H "Accept: text/csv" https://api.forecast.solar/<APIkey>/estimate/watthours/day/52/12/37/0/5.67+curl -H 'Accept: text/csv' 'https://api.forecast.solar/estimate/watthours/day/52/12/37/0/5.67'
 </code> </code>
  
Line 83: Line 119:
  
 <code bash> <code bash>
-curl https://api.forecast.solar/<APIkey>/estimate/watthours/52/12/37/0/5.67+curl https://api.forecast.solar/estimate/watthours/52/12/37/0/5.67
 </code> </code>
  
Line 89: Line 125:
 { {
     "result": {     "result": {
-        "2016-02-08 07:20:00": 0, +        "watts": { 
-        "2016-02-08 07:38:00": 17, +            "2022-10-12 07:29:00": 0, 
-        "2016-02-08 08:15:00": 195, +            "2022-10-12 08:00:00": 1570, 
-        ... +            ... 
-        "2016-02-08 15:45:00": 3599, +            "2022-10-12 18:00:00": 521, 
-        "2016-02-08 17:14:00": 3680, +            "2022-10-12 18:27:00": 0, 
-        "2016-02-08 17:32:00": 3680, +            "2022-10-13 07:31:00": 0, 
-        "2016-02-09 07:18:00": 0, +            "2022-10-13 08:00:00": 894, 
-        "2016-02-09 07:36:00": 66, +            ... 
-        "2016-02-09 08:15:00": 785, +            "2022-10-13 18:00:00": 133, 
-        ... +            "2022-10-13 18:24:00": 0 
-        "2016-02-09 15:45:00": 13472, +        }, 
-        "2016-02-09 17:16:00": 13545, +        "watt_hours": { 
-        "2016-02-09 17:34:00": 13545, +            "2022-10-12 07:29:00": 0, 
-        "2016-02-10 07:17:00": 0, +            "2022-10-12 08:00:00": 406, 
-        "2016-02-10 07:35:00": 26, +            ... 
-        "2016-02-10 08:15:00": 314, +            "2022-10-12 18:00:00": 33248, 
-        ... +            "2022-10-12 18:27:00": 33365, 
-        "2016-02-10 15:45:00": 8268, +            "2022-10-13 07:31:00": 0, 
-        "2016-02-10 17:18:00": 8347, +            "2022-10-13 08:00:00": 216, 
-        "2016-02-10 17:36:00": 8347, +            ... 
-        "2016-02-11 07:15:00": 0, +            "2022-10-13 18:00:00": 11881, 
-        "2016-02-11 07:33:00": 18, +            "2022-10-13 18:24:00": 11907 
-        "2016-02-11 08:15:00": 231, +        }, 
-        ... +        "watt_hours_period": { 
-        "2016-02-11 15:45:00": 3791, +            "2022-10-12 07:29:00": 0, 
-        "2016-02-11 17:20:00": 3873, +            "2022-10-12 08:00:00": 406, 
-        "2016-02-11 17:38:00": 3873, +            ... 
-        "2016-02-12 07:13:00": 0, +            "2022-10-12 18:00:00": 993, 
-        "2016-02-12 07:31:00": 97, +            "2022-10-12 18:27:00": 117, 
-        "2016-02-12 08:15:00": 1284, +            "2022-10-13 07:31:00": 0, 
-        ... +            "2022-10-13 08:00:00": 216, 
-        "2016-02-12 15:45:00": 18674, +            ... 
-        "2016-02-12 17:22:00": 18763, +            "2022-10-13 18:00:00": 173, 
-        "2016-02-12 17:39:00": 18763, +            "2022-10-13 18:24:00": 27 
-        "2016-02-13 07:11:00": 0, +        }, 
-        "2016-02-13 07:29:00": 19, +        "watt_hours_day": { 
-        "2016-02-13 08:15:00": 263, +            "2022-10-12": 33365, 
-        ... +            "2022-10-13": 11907 
-        "2016-02-13 15:45:00": 3933, +        }
-        "2016-02-13 17:23:00": 4022, +
-        "2016-02-13 17:41:00": 4022, +
-        "2016-02-14 07:10:00": 0, +
-        "2016-02-14 07:27:00": 19, +
-        "2016-02-14 08:15:00": 282, +
-        ... +
-        "2016-02-14 15:45:00": 4169, +
-        "2016-02-14 17:25:00": 4298, +
-        "2016-02-14 17:43:00": 4298, +
-        "2016-02-15 07:08:00": 0, +
-        "2016-02-15 07:25:00": 20, +
-        "2016-02-15 08:15:00": 312, +
-        ...+
     },     },
     "message": {     "message": {
         "code": 0,         "code": 0,
         "type": "success",         "type": "success",
-        "text": ""+        "text": "", 
 +        "info": { 
 +            "latitude": 52, 
 +            "longitude": 12, 
 +            "distance": 0, 
 +            "place": "L 51, Schora, Moritz, Zerbst/Anhalt, Anhalt-Bitterfeld, Sachsen-Anhalt, 39264, Deutschland", 
 +            "timezone": "Europe/Berlin", 
 +            "time": "2022-10-12T14:25:10+02:00", 
 +            "time_utc": "2022-10-12T12:25:10+00:00" 
 +        }, 
 +        "ratelimit": { 
 +            "period": 3600, 
 +            "limit": 12, 
 +            "remaining": 10 
 +        }
     }     }
 } }
 </code> </code>
  
-The ''watt_hours'' data will **reset to 0 at day change**!+The ''watt_hours'' data will simulate a daily electricity meter and therefor **resets to 0 at day change**!