Differences

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


Previous revision
api:estimate [2024/02/15 12:09] (current) – [Example] knutkohl
Line 1: Line 1:
 +===== Solar production estimate =====
 +
 +Get solar production estimate for specific location (defined by **latitude** and **longitude**) and a specific plane orientation (defined by **declination** and **azimuth**) for an installed **module power**.
 +
 +===== Historic solar production =====
 +
 +''historic'' means here that the average of all years of the available weather data on that day is considered, the current weather is thus **not** included in the calculation.
 +
 +===== Clear sky solar 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 =====
 +
 +  * **1** plane can be accessed by an API call
 +  * only ''estimate'' data available
 +
 +  https://api.forecast.solar/estimate/:lat/:lon/:dec/:az/:kwp
 +
 +===== Personal / Personal Plus =====
 +
 +  * **1** (Personal) or combined data of **2** (Personal Plus) planes can be accessed by an API call
 +  * ''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/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2
 +===== Professional / Professional Plus =====
 +
 +  * Combined data of up to **3** (Professional) or **4** (Professional Plus) planes can be accessed by one API call
 +  * ''estimate'', ''history'' and ''clearsky'' data are available
 +
 +  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
 +  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
 +
 +====== Responses ======
 +
 +===== Watts, Watt hours over day, Watt hours per period, Watt hours per day =====
 +
 +There are also routes available to query only the watts, watt hours, watt hours per period or watt hours per day.
 +
 +  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/period/:lat/:lon/:dec/:az/:kwp
 +  https://api.forecast.solar/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp
 +
 +The same for Personal and Professional accounts with API key
 +
 +  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/period/:lat/:lon/:dec/:az/:kwp
 +  https://api.forecast.solar/:apikey/estimate/watthours/day/:lat/:lon/:dec/:az/:kwp
 +
 +===== Content =====
 +
 +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 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>
 +curl -H 'Accept: text/csv' 'https://api.forecast.solar/estimate/watthours/day/52/12/37/0/5.67'
 +</code>
 +
 +<code csv>
 +2016-02-08;3680
 +2016-02-09;13545
 +2016-02-10;8347
 +2016-02-11;3873
 +2016-02-12;18763
 +2016-02-13;4022
 +2016-02-14;4298
 +2016-02-15;3395
 +</code>
 +
 +Get solar production estimate as [[:api#Response content type|JSON]] for 52° north, 12° east, for a installation with a declination of 37° looking south (0°) with 5.67 kWp
 +
 +<code bash>
 +curl https://api.forecast.solar/estimate/watthours/52/12/37/0/5.67
 +</code>
 +
 +<code json>
 +{
 +    "result": {
 +        "watts": {
 +            "2022-10-12 07:29:00": 0,
 +            "2022-10-12 08:00:00": 1570,
 +            ...
 +            "2022-10-12 18:00:00": 521,
 +            "2022-10-12 18:27:00": 0,
 +            "2022-10-13 07:31:00": 0,
 +            "2022-10-13 08:00:00": 894,
 +            ...
 +            "2022-10-13 18:00:00": 133,
 +            "2022-10-13 18:24:00": 0
 +        },
 +        "watt_hours": {
 +            "2022-10-12 07:29:00": 0,
 +            "2022-10-12 08:00:00": 406,
 +            ...
 +            "2022-10-12 18:00:00": 33248,
 +            "2022-10-12 18:27:00": 33365,
 +            "2022-10-13 07:31:00": 0,
 +            "2022-10-13 08:00:00": 216,
 +            ...
 +            "2022-10-13 18:00:00": 11881,
 +            "2022-10-13 18:24:00": 11907
 +        },
 +        "watt_hours_period": {
 +            "2022-10-12 07:29:00": 0,
 +            "2022-10-12 08:00:00": 406,
 +            ...
 +            "2022-10-12 18:00:00": 993,
 +            "2022-10-12 18:27:00": 117,
 +            "2022-10-13 07:31:00": 0,
 +            "2022-10-13 08:00:00": 216,
 +            ...
 +            "2022-10-13 18:00:00": 173,
 +            "2022-10-13 18:24:00": 27
 +        },
 +        "watt_hours_day": {
 +            "2022-10-12": 33365,
 +            "2022-10-13": 11907
 +        }
 +    },
 +    "message": {
 +        "code": 0,
 +        "type": "success",
 +        "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>
 +
 +The ''watt_hours'' data will simulate a daily electricity meter and therefor **resets to 0 at day change**!