SolarFarmer Web API Release Notes
These are the different releases of the SolarFarmer web API and notes (breaking changes, web API class changes, enhancements, bug fixes).
The web API is usually released at the same time as a new release of the SolarFarmer desktop application, but may not always be.
Note
3D API Private Preview
The 3D API is available on a Private Preview basis to existing customers who want to road test the API whilst we continue to work on API management and scalability.
Whilst in Private Preview, the 3D API is available at no additional charge, although we are currently limiting maximum project size to 50MW and we are running on a relatively small cloud cluster – which means that you may experience resource contention at busy times.
Request access by clicking this button and filling and submitting the form:
You can see if you have access when you log into the Web Service website (https://solarfarmer.dnv.com) - your services are listed on the home page.
API v2 (build 2.0.2) (7 September 2023)
[SF-Core 0.2.245.0]
API calculation updates
Calculation features
- API Versioning introduced
- We now support two concurrent versions of the API to help give you a bit of time to accommodate any new changes.
- See SolarFarmer API Versions for more information on how this works.
- Allow albedo as column in met data
- Use of an optional
Albedo
column in the TSV import for met-data. - When provided, this albedo value is used per time-step in the API calculation instead of the monthly or yearly value (see A TSV File)
- Use of an optional
- Updated PV technology band-gap values - and it is overridable
- The band-gap energy values used for different module cell technologies have been updated and brought into line with industry standards. These differences may slightly change calculation results to a very small degree. See Effective Band-Gap for the latest values.
- Using the new PanFileSupplements.BandGapOverride property you can override the built-in band-gap values for specific module specifications if you wish.
- PVsyst-format result columns updated
- '
AlbInc
' has been renamed 'Alb_Inc
' (the reflected irradiance in plane of array on the module front site. - See "PVsystFormatResults.txt" for the full list of PVsyst variable names in the output file.
- '
- Toggle slope-aware backtracking
- Slope-aware backtracking for the tracker calculations was previously always turned on.
- You can turn it off using the new TrackerSystem.UseSlopeAwareBacktracking property.
- Support half-cell modules with 30 cells in series
- This module configuration is now supported.
- Extended API validation functionality
- New validation rules have been added to try and catch erroneous JSON input files
and configurations. These include:
- Horizon is specified but no horizon data.
- If the metadata in .DAT met files indicates coordinates that exceed 150km from the coordinates of the site.
- If the project is single-axis trackers (and you're not using the 3 legacy properties in the MountingTypeSpecification) there should be TrackerSystem objects defined.
- If rack height is smaller than module dimensions.
- The full list is here: API Validation Service
- New validation rules have been added to try and catch erroneous JSON input files
and configurations. These include:
- Scaling/queuing for 2D API
- Additional support has been added for the 2D API to allow queuing and scaling to better support multiple concurrent 2D API calls.
- Update to .NET 7
- The API calculation code has been updated to .NET 7 which provides increased performance and new coding features.
- Latest security updates for API and website
- We continuously monitor our API and website code and update it with the latest security updates and best practices.
Calculation bugs fixed
- Incorrect scaling of irradiance in sunrise/sunset in DetailedTimeSeries results
- Setting soiling loss to 100% causes issues
- Lower validation range for Altitude needs lowering
- RackHeight upper validation is too small
- Temperature missing doesn't skip timestamp and crashes
- Missing data values, 9999 and -9999 both acceptable for missing data
- OutOfMemoryExceptions sometimes thrown for 3D API calculations
- Layout with monofacial and bifacial fails - validation rule now added
- SolveDiodeEquation: Failed to converge when searching for MPP
- Beam shading not calculated as expected in 3D for trackers (was an issue with the desktop app)
Documentation additions
- Web-API class references have been added.
- These will be make it easier to find classes and properties for those users that create their own input JSON files for use with the API. Before they were only visible in the Docs tab on the API website, which is more difficult to use and can't be referenced easily.
- ModelChain Endpoint Tutorial has been updated to read TSV files
- API Validation Service has been added that details all the validation steps that happen when an API call is submitted.
Web API class changes
- TrackerSystem class
- New UseSlopeAwareBacktracking property added, allowing you turn off slope-aware backtracking (defaults to true if not set).
- PanFileSupplements class
- New BandGapOverride allowing you to override the default band-gap value for the technology of the module (see Effective Band-Gap) and use your own value for this module.
- IamModelTypeOverride property is now of a new enum type IAMModelTypeForOverride. This just has the two allowable fields that you can use with the property.
API calculation breaking changes
- None in this release. Though the new validation rules may find issues in your inputs.
API Website
- Export to CSV/TSV button added on Model Chain page to export the currently
filtered model chain runs:
- Refresh of the styling in the website.
API v1 (build 0.2.254) (11 April 2023)
[SF-Core 0.2.227.0]
Important
For API users who generate their own JSON configuration inputs, this update removes some previously deprecated API inputs, which will cause API calls of bifacial projects to fail unless you have already updated your code to support the revised bifacial inputs.
Please see the API calculation breaking changes section below for more info.
API calculation updates
Calculation features
- Improved validation functionality for the API
- Improved validation when the
ModelChain
andModelChainAsync
endpoints are called - A ProblemDetails structure now returned from API on failure (rather than 'Model chain failed') which contains one or more errors that occurred
- WARNING: Invalid inputs that were previously working may now fail. So please check.
- See Handling errors for more details and some examples
- Improved validation when the
- POA-only solar records now supported in TSV file
- See A TSV file for more details
- This was already supported if running a calculation directly from the desktop application, but not if you supplied the TSV file directly to the API. It is now.
- Up to 50 PAN and OND files supported with each calculation
- Use the
ondFiles
andpanFiles
values in the HTTP Post request now instead of the old (panFile1
,panFile2
, etc.) - See ModelChain Endpoint Definition for more details
- Use the
- Option to use Fresnel coefficients for incidence angle
- To override the IAM setting in the PAN file you are using, in the PanFileSupplements object, set the
new
IamModelTypeOverride
property to be eitherFresnelNormal
orFresnelAR
. - See the IAM Pointwise section for parameter details
- To override the IAM setting in the PAN file you are using, in the PanFileSupplements object, set the
new
- Add whether the trackers are backtracking to the output files
- In the Detailed Time-Series Results File there is
an additional
TrackerCaseNBacktrackingState
column per tracker case which states if the tracker was backtracking for that time-step or not
- In the Detailed Time-Series Results File there is
an additional
- Remove obsolete bifacial properties in Layout class. See the breaking changes below.
- Remove the 'Number of strings is not a multiple of the rack height' limitation for the ModelChain endpoint
Calculation bugs fixed
- Positive bias of backside irradiance compared to measured data
- Inverter losses for maximum power show discrepancies in PVsyst-format output
- Incorrect scaling of irradiance for time periods including sunrise/sunset
- .tsv solar files used with API need a lower-case extension
Important
Changes in calculation results between this release and the previous release of the API
This new version of the API includes a review of the model affecting the inter-row shading. Specifically, the ground reflected irradiance (via the view factor of ground surface to the sky, which represents the proportion of the ground exposed to the sky dome).
This change affects both bifacial and monofacial systems, as the ground between rows is also observed by any rack/trackers (excluding those in the first row).
The practical consequences of this:
- In the effects (losses/gains):
NearShadingIrradiance
may be slightly higher- Other effects (like
Temperature
,Irradiance
) can also be minimally affected as a result of different irradiance levels - Effects related to bifacial losses (e.g.
BackIrradianceGain
) may also change
- In the energy yield results:
GlobalEffectiveIrradiance
may be slightly lower as a result of increased near shading- This lower irradiance is proportionally carried through the modelling pipeline affecting variables such as
ModelPower
,ModelPowerAtSTC
,NominalEnergy
,PDC
,PAC
,PerformanceRatio
,NetEnergy
, andEnergyYield
- We have observed power, energy, and Performance Ratio changes of up to -1.5% in our test suite compared to the previous version
API calculation breaking changes
Layout class properties removed (used in 2D calculations with the
ModelChain
endpoint)- The deprecated bifacial properties in the
Layout class
(TransmissionFactor
,BifacialShadeLossFactor
, andBifacialMismatchLossFactor
) have been removed. Use the equivalents in the MountingTypeSpecification class instead.- The practical impact of this change is that if you are modelling bifacial projects using the API you will experience validation errors unless you have already switched away from using the deprecated inputs.
- The new inputs were added in the 23 August 2021 release so if you were not using the API before this date then your code is likely already using the proper methods to specify these bifacial inputs and no changes are needed.
- If you are unsure, we recommend that you evaluate any code that is generating JSON configuration data for API calls to be sure that the inputs are being specified in the MountingTypeSpecification, and not in Layout.
- The deprecated bifacial properties in the
The new validation that is run on the inputs to the ModelChain and ModelChainAsync endpoints may fail invalid inputs that were previously working
- This is a good thing (as you may have been using incorrect properties/values before and not knowing) but may break your workflow until the validation issues are fixed
This includes using string values for enumerable types rather than integer if you weren’t already. The main changes being:
TransformerSpecification
class. The value used forModelType
must now be a string if not already:Old integer value String value to be used 0 "SimpleLossFactor" 1 "NoLoadAndOhmic" EnergyCalculationOptions class. The value used for
DiffuseModel
must now be a string if not already:Old integer value String value to be used 0 "Isotropic" 1 "Hay" 2 "Perez"
Please check the ProblemDetails results that are returned from the API call to help you understand where the validation issues are (see Handling errors for more details and some examples)
Web API class changes
- PanFileSupplements class
- Addition of the
IamModelTypeOverride
property. Use this to override the IAM model in the PAN file with one of the new Fresnel options. See below.
- Addition of the
IAMModelType
enumerationFresnelNormal
(Fresnel Normal Glass) andFresnelAR
(Fresnel Anti-reflective Glass) IAM models added- See the IAM Pointwise section for parameter details
- Use these in the PanFileSupplements object for the new
IamModelTypeOverride
property if you wish to override the IAM model in the PAN file with one of these options.
Website
No significant development on the API website this release
API 0.2.249 (22 November 2022)
[SF-Core 0.2.215.0]
Added support for shading objects and POA-only met data in the 3D API
Calculation
Calculation features
- Added support for shading objects in 3D API (when provided)
- Shading regions and 3D shading objects are now used for beam and diffuse shading for 3D racks
- Shading regions and 3D shading objects are now used for diffuse shading for 3D trackers (only row-to-row shading is currently used for beam shading for trackers (like the local calculation))
- Added support for POA-only (Plane Of Array) solar resources
- API handles met data transfer files (compressed files currently sent from the desktop app)
Calculation bugs fixed
- Fixed issue when requesting detailed time series results for 3D calculations
- Module Quality Factor validation range too strict (lower end now changed to -40%)
Website
Website features
- None of significance
Website bugs fixed
- Can't cancel regenerate token dialog on home page
Breaking changes
- Layout class (used in 2D calculations with the
ModelChain
endpoint)- 3 properties (
TransmissionFactor
,BifacialShadeLossFactor
, andBifacialMismatchLossFactor
) relating to bifacial modules have now been marked as Obsolete. They have been commented as 'deprecated' for the last few releases. - These 3 properties will still work in the calculation, but you should now use the equivalent properties in the MountingTypeSpecification class instead.
- These 3 properties will be removed from the Layout class in the next release of the API in early 2023, so change any code now to use the equivalents in the MountingTypeSpecification instead.
- 3 properties (
Web API class changes
- PVPlant class
- Addition of
ShadingObjects
andSimpleTerrain
properties
- Addition of
IndexedObject3D
class added to describe a 3D shading objectSimpleTerrainDto
,MiniSimpleTerrainDto
,TerrainRowDto
andTerrainRowStartEndColumnsDto
classes added to describe a simple terrain object used for shadingMeteorologicalCondition
classGhi
property is now optional (if not set,Poa
property must be set)Poa
optional property added
- EnergyCalculationOptions class
SolarMeasurementPlaneAzimuth
andSolarMeasurementPlaneTilt
properties added. Used to define the solar measurement plane used when POA met data is used.
- Layout class (used in 2D calculations with the
ModelChain
endpoint)- As explained in the Breaking changes section above, 3 properties (
TransmissionFactor
,BifacialShadeLossFactor
, andBifacialMismatchLossFactor
) relating to bifacial modules have now been marked as Obsolete. They have been commented as 'deprecated' for the last few releases. - These 3 properties will still work in the calculation, but you should now use the equivalent properties in the MountingTypeSpecification class instead.
- These 3 properties will be removed from the Layout class in the next release of the API in early 2023, so change any code now to use the equivalents in the MountingTypeSpecification instead.
- As explained in the Breaking changes section above, 3 properties (
API 0.2.242 (28 July 2022)
[SF-Core 0.2.208.0]
3D API private preview ready for use!
The ModelChainAsync
endpoint (that is used to run 3D calculations) is now available for users in private preview.
- See ModelChainAsync Endpoint for details on the endpoint
- See ModelChainAsync Endpoint Tutorial for a tutorial on how to use it
- See Generating API input files from the SolarFarmer desktop application for how to generate some input files from the SolarFarmer desktop application to use with the endpoint
The TerminateModelChainAsync
endpoint is also available to terminate unwanted ModelChainAsync
calculations
- See TerminateModelChainAsync Endpoint for details on this endpoint
- See TerminateModelChainAsync Endpoint Tutorial for a tutorial on how to use it
Calculation
Calculation features
- Improved efficiency of 3D tracker calculation with multiple layout regions
Renaming of some variables in the PVsyst output file to avoid confusion between existing PVsyst variable names and similar (but different) SolarFarmer variables (see the whole list in Cloud Time-Series Results Files):
Old header New header GlobIAM GlobHrzIAM GlobSlg GlobHrzSlg ShdLoss ShdLossTotal ShdDLss ShdDLssTotal ShdALss ShdALssTotal ShdBLss ShdBLssTotal GlobShd GlobShdTotal GlobEff GlobEffTotal GlobGnd GlobGndShd
Calculation bugs fixed
- Unexpected record count reported
- Air pressure validation is too strict
- PVsyst calculation output variable names are confusing
- "BackShd" in PVsyst output file is incorrect
- Incorrect tracker rotation causing shading when forcing to horizontal in 2D calculation
- Tracker min/max rotation not correctly considered for sites with side slope
- Including tare loss in efficiency model causes problems for some inverters
- Problem with solar resource data with just night values in one month
- Transformer no-load losses not included in PVsyst output
Website
Security enhancements
- General tightening up of security around the API and website
- Allow users to regenerate their own API tokens
- Multi Factor Authentication added to the website for added security
- API tokens now not shown in the Web UI - only allow them to be copied to the clipboard
- Improved website experience if your API token has expired or your account is disabled
Website features
- Add pagination and filtering to model chain runs table
- Add 'Calculation Status' column to model chain runs table
Website bugs fixed
- Blank Name and Email columns in Model chain run table for non-admin users
- Website holds onto local cache even after logging out
Breaking changes
- The renaming of some of the variables in the PVsyst output file - see above for details.
- The
saveDetails
parameter has been removed from theModelChain
andModelChainAsync
endpoints so calculation inputs and outputs can no longer be stored (and then accessed via the website). We need to think through how users' data is stored and for how long (and if it is still useful) before this is enabled again.
Web API class changes
None of significance.
API 0.2.223 (3 March 2022)
[SF-Core 0.2.197.0]
2D model chain calculation bug fixes. Ongoing preparation for 3D calculations.
Breaking changes
ProjectID
(a string) is now used as a parameter to the ModelChain endpoint instead ofProjectNumber
(which was an integer) If you continue to useProjectNumber
it will be ignored and theProjectId
value will be empty
Enhancements
saveDetails
property (boolean) has been added to theModelChain
endpoint. Set totrue
to save the inputs and outputs of the calculation in the cloud.- New options for requesting the time-series results when running calculations in the cloud (the
returnPvSystFormatTimeSeriesResults
,returnDetailedTimeSeriesResults
andreturnLossTreeTimeSeriesResults
properties in the EnergyCalculationOptions class. - Separate ability to run 2D and 3D calculations in the cloud and provide UI and support for managing this
- Provide system attributes file from cloud calculations (location, AC and DC capacity, is 3D, racks/trackers, library versions)
- Improved UI in web API website - order tables by values in columns, clearer home page
- General speed up improvements
Bug fixes
- User-defined module parameters are not considered in cloud calculation
- Cloud time-series files are saved even when empty
- 'RackHeight' in cloud JSON doesn't take frame into account
- API always generates selected time-series files even when not asked
- Cloud status not correct when not successful
- Website being cached and not showing latest version
- DC ohmic losses are different in 2D and 3D calculations
- Electrical mismatch effects are reported incorrectly
- Grid Energy does not consider night-time tare losses
- Beam shading for trackers in cloud differs from local calculation
- Cloud calculation failing when used with irregular met data
- Unexpected overpower shutdown losses
- ShdLoss is given in W instead of W/m² in PVsyst time-series results when run in cloud
Web API class changes
These changes relate to 2D calculations.
You may notice a few classes and properties relating to 3D calculations. These are for internal use only at the moment and are for developing the 3D calculation (coming soon!). So please ignore them for now.
ModuleSpecification class
NameplatePower
property added- The nameplate power (nominal power) of the module measured at STC and corresponds to the PNom property in the PAN file. In Watts.
EnergyCalculationOptions class
ReturnPvSystFormatTimeSeriesResults
property added- Generate and return PVsyst-format time-series results (defaults to true)
ReturnDetailedTimeSeriesResults
property added- Generate and return detailed time-series results (defaults to false)
ReturnLossTreeTimeSeriesResults
property added- Generate and return detailed loss tree time-series results (defaults to false)
ModelChainResponse class
TotalModuleArea
property added- The total active module area (in m²) considered by the energy calculation.
SystemAttributes
property added- Of type
SystemAttributes
- details some of the system attributes (e.g. location, AC capacity, DC capacity, is 3D, mounting type, SF-Core and SF-API versions used)
- Of type
LossTree
property added- A list of
LossTreeResultForMonth
objects. Additional loss tree objects (for each month). Mainly used for more in-depth studies.
- A list of
API 0.2.64 (23 August 2021)
[SF-Core 0.2.172.0]
2D model chain calculation improvements. Ongoing preparation for 3D calculations.
Breaking changes
No breaking changes
Enhancements
- Support slopes in 2D. No longer fixed to be horizontal only.
- Automatically used when calling from the SolarFarmer desktop application
- Set the slope using the new
TerrainAzimuth
andTerrainSlope
properties of the Layout class
- Web API documentation added to the online SolarFarmer documentation (https://dnvgldocs.azureedge.net/SolarFarmer_Latest/index.html), including some tutorials to help get you started.
- Allow user to configure resolution of IV curve
- Output the irradiance on the ground
- Breakup ground into shade and unshaded regions
- Add SF-Core version to PVsyst formatted CSV output
- Add option flag to use diffuse on most shaded cell
Bug fixes
- Results from 2D tracker sites slightly different each time you run it
- Calculation fails 'Voltage requested was not within known IV curve range'
- Bad .hor file doesn't lead to useful error message
- Time series .tsv file entries in wrong columns sometimes
Web API class changes
These changes relate to 2D calculations.
You may notice a few classes and properties relating to 3D calculations. These are for internal use only at the moment and are for developing the 3D calculation (coming soon!). So please ignore them for now.
EnergyCalculationInputs class
SolarPositions
property added (optional)- Allows you to specify your own solar positions. Usually left empty so that the calculation automatically calculates them.
PVPlant class
TrackerSystems
property added (required now for tracker plants)Important
This is the new way to define tracker systems and should be used going forward. Please change any existing code you have and start to use TrackerSystems for tracker plants.
Layout class
TransmissionFactor
,BifacialShadeLossFactor
,BifacialMismatchLossFactor
deprecated properties- These will be deprecated from the Layout class.
- They have been moved to the MountingTypeSpecification class.
- Please change code to use them there.
- For this release they are in both places (the MountingTypeSpecification property, if set, will take precedence), but in future releases they will only be present in the MountingTypeSpecification class.
TrackerSystemID
property added (required for tracker plants)- Used to reference the TrackerSystem to use (if trackers) for the Layout
- Please use this property for tracker plants from now on
TerrainAzimuth
andTerrainSlope
properties added (both optional and default to 0)- Defining these you can set the slope of the layout. Set them both to 0 for a horizontal layout.
TrackerSystem class
- New class! Please use this now to define tracker systems.
- Add them to the
PVPlant.TrackerSystems
dictionary (keyed by the trackerSystemID). Then reference them using theLayout.TrackerSystemID
property.
MountingTypeSpecification class
IsBackTracking
,MinRotation
,MaxRotation
deprecated properties- These will be deprecated from the MountingTypeSpecification class.
- They have been moved to the TrackerSystem class.
- Please change code to use them there.
- For this release they are usable in both places (the TrackerSystem property, if set, will take precedence), but in future releases they will only be present in the TrackerSystem class.
HeightOfTrackerCenterFromGround
property added (optional)- Use to set the height of the tracker center from the ground (if specifying a tracker)
TransmissionFactor
,BifacialShadeLossFactor
,BifacialMismatchLossFactor
properties added- These have been moved from the Layout class
EnergyCalculationOptions class
ModelBackRowSeparately
property added (relevant for bifacial plants only) (defaults to true)- If set to true, the back-irradiance for bifacial of the back row of the array will be treated separately. There will be no near-shading loss applied to the back-irradiance of the back row.
- If set to false, the back row will get the same back-irradiance as any other row in the array.
ModuleMismatchBinWidth
property added (optional: defaults to 0.000001)- The bin width to use for module mismatch (defaults to 0.000001)
ConnectorResistanceBinWidth
property added (optional)- The bin width to use for the connector resistance (optional: defaults to 0.000001)
- This is required because the connector resistance is defined per layout, so if we are considering whether two modules from different layout are in-fact in equivalent operating conditions we need to compare the connector resistance.
IrradianceBinWidth
property added (optional: defaults to 1 W/m²)- The bin width to use for irradiance
TemperatureBinWidth
property added (optional: defaults to 0.1°C)- The bin width to use for temperature
IvCurveSize
property added (optional: defaults to 500)- The number of points in the IV curve that is calculated
SolarPositions class
- New class. Use with the
EnergyCalculationInputs.SolarPositions
property if you want to specify your own solar positions for the timestamps. Usually letting the calculation calculate the solar position is recommended, unless you wish to try alternative algorithms.
EnumTechnology enum
HIT
option added (Panasonic Heterojunction with Intrinsic Thin-layer technology)
API 0.2.51 (2 June 2021)
[SF-Core 0.2.148.0]
The first release of the web API! Support for 2D energy calculations.
The SolarFarmer desktop application can use the ModelChain endpoint of the web API to run 2D calculations for sites.
The ModelChain endpoint is available to be used from other applications and scripts too.