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:estimate [2019/12/30 16:22] – [URL parameters] knutkohlapi:estimate [2024/02/15 12:09] (current) – [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 Editor]] 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 a location 52° north, 12° east, for an plane with a declination of 37° looking south (0°) and panels with 5.67 kWp installed.
  
 <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**!