EnergySiteCreateRequest

Basic Asynchronous Request

Method: POST
URL: https://service.solaranywhere.com/api/v2/EnergySites?key=CLIENT_KEY

To create an energy site, specify energy site elements such as site name and location, as well as PV system elements like inverter and module specifications and array configuration details. The response to this Post request will contain a unique EnergySiteId associated with the system that can be used in a variety of operations including simulation requests.

Clean Power Research offers two solar simulation models for use in energy site simulation: pvlib and CprPVForm. Visit the introduction page to learn more about the power models available and determine the optimal way to define your energy sites. To learn more about the attributes specified in an EnergySiteCreateRequest, visit the terms & concepts page.

Energy Site Examples for Use with pvlib Power Model

If you plan to use the pvlib power model, use these XML samples to get started.

<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Basic fixed tilt utility-scale PV system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="86.00">
    <Inverters>
     <Inverter Count="12" MaxPowerOutputAC_kW="4166.7" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="16500" NameplateDCRating_kW="0.33" PtcRating_kW="0.3054" />
      </PvModules>
      <ArrayConfiguration Tracking="Fixed" Tilt_Degrees="25.00" Azimuth_Degrees="180.000"  RelativeRowSpacing="3" ModuleRowCount="25" />
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Basic fixed tilt utility-scale PV system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="86.00">
    <Inverters>
     <Inverter Count="12" MaxPowerOutputAC_kW="4166.7" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="16500" NameplateDCRating_kW="0.33" PtcRating_kW="0.3054" PowerTemperatureCoefficient_PercentPerDegreeC="0.4"/>
      </PvModules>
      <ArrayConfiguration Tracking="SingleAxis" TrackingRotationLimit_Degrees="60" Tilt_Degrees="0.00" Azimuth_Degrees="180.000" RelativeRowSpacing="3" ModuleRowCount="25" />
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Basic fixed tilt utility-scale PV system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="86.00">
    <Inverters>
     <Inverter Count="12" MaxPowerOutputAC_kW="4166.7" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="16500" NameplateDCRating_kW="0.33" PtcRating_kW="0.3054" PowerTemperatureCoefficient_PercentPerDegreeC="0.4"/>
      </PvModules>
      <ArrayConfiguration Tracking="SingleAxisWithBacktracking" TrackingRotationLimit_Degrees="60" Tilt_Degrees="0.00" Azimuth_Degrees="180.000" RelativeRowSpacing="3" ModuleRowCount="25"/>
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
Tracking Options
In addition to fixed tilt and single-axis tracking PV systems, the pvlib power model supports the modeling of single-axis systems with backtracking. Learn more about these tracking types and the different specification requirements for each one in the “Energy Sites” section of the terms & concepts page. To specify these different tracking types, use: Tracking=“Fixed”, Tracking=“SingleAxis” or Tracking=“SingleAxisWithBacktracking”.

Energy Site Examples for Use with CprPVForm Power Model

If you plan to use the CprPVForm power model, use these XML samples to get started.

<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Sample residential rooftop system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="85.00">
    <Inverters>
     <Inverter Count="1" MaxPowerOutputAC_kW="4.470000" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="20" NameplateDCRating_kW="0.22000" PtcRating_kW="0.19760" PowerTemperatureCoefficient_PercentPerDegreeC="0.4" />
      </PvModules>
      <ArrayConfiguration Tracking="Fixed" Tilt_Degrees="25.000" Azimuth_Degrees="177.000" RelativeRowSpacing="3"/>
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Sample residential rooftop system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="85.00">
    <Inverters>
     <Inverter Count="1" MaxPowerOutputAC_kW="4.470000" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="20" NameplateDCRating_kW="0.22000" PtcRating_kW="0.19760" PowerTemperatureCoefficient_PercentPerDegreeC="0.4" />
      </PvModules>
      <ArrayConfiguration Tracking="SingleAxis" TrackingRotationLimit_Degrees="60" Tilt_Degrees="0.00" Azimuth_Degrees="180.000" RelativeRowSpacing="3" ModuleRowCount="25"/>
      <SolarObstructions>
       <SolarObstruction Opacity_Percent="80.0" Azimuth_Degrees="90.000" Elevation_Degrees="33.000" />
       <SolarObstruction Opacity_Percent="100.0" Azimuth_Degrees="120.000" Elevation_Degrees="50.000" />
       <SolarObstruction Opacity_Percent="100.0" Azimuth_Degrees="150.000" Elevation_Degrees="22.000" />
       <SolarObstruction Opacity_Percent="100.0" Azimuth_Degrees="180.000" Elevation_Degrees="3.000" />
       <SolarObstruction Opacity_Percent="100.0" Azimuth_Degrees="210.000" Elevation_Degrees="1.000" />
       <SolarObstruction Opacity_Percent="100.0" Azimuth_Degrees="240.000" Elevation_Degrees="2.000" />
       <SolarObstruction Opacity_Percent="70.0" Azimuth_Degrees="270.000" Elevation_Degrees="4.000" />
      </SolarObstructions>
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
<EnergySiteCreateRequest xmlns="http://service.solaranywhere.com/api/v2">
 <EnergySite Name="Sample Site" Description="Sample residential rooftop system">
  <Location Latitude="34.65" Longitude="-119.10" />
  <PvSystems>
   <PvSystem Albedo_Percent="17" GeneralDerate_Percent="85.00">
    <Inverters>
     <Inverter Count="1" MaxPowerOutputAC_kW="4.470000" EfficiencyRating_Percent="97.000000" />
    </Inverters>
    <PvArrays>
     <PvArray>
      <PvModules>
       <PvModule Count="20" NameplateDCRating_kW="0.22000" PtcRating_kW="0.19760" PowerTemperatureCoefficient_PercentPerDegreeC="0.4" />
      </PvModules>
      <ArrayConfiguration Tracking="SingleAxis" TrackingRotationLimit_Degrees="60" Tilt_Degrees="0.00" Azimuth_Degrees="180.000" RelativeRowSpacing="3" ModuleRowCount="25"/>
      <MonthlyShadings>
       <MonthlyShading MonthNumber="1" SolarAccess_Percent="77.0" />
       <MonthlyShading MonthNumber="2" SolarAccess_Percent="87.0" />
       <MonthlyShading MonthNumber="3" SolarAccess_Percent="98.0" />
       <MonthlyShading MonthNumber="4" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="5" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="6" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="7" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="8" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="9" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="10" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="11" SolarAccess_Percent="100.0" />
       <MonthlyShading MonthNumber="12" SolarAccess_Percent="91.0" />
      </MonthlyShadings>
     </PvArray>
    </PvArrays>
   </PvSystem>
  </PvSystems>
 </EnergySite>
</EnergySiteCreateRequest>
Shading Options
If you would like to model shading on your system, you can do this in one of two ways when defining your energy site. If you have near object shading specifics for your PV sytem (i.e. the elevation, altitude, and opacity of surrounding objects), start with the “azimuthal shading” code sample. If you don’t have these specifics but would like to derate the simulated output based on the month, start with the “monthly solar access” sample. When creating the simulation request for the site, you will select the shading model that corresponds to the way you specified shading:

  • Azimuthal Shading = ShadeSimulator
  • Monthly Solar Access = MonthlyPercentSolarResource

The shading models are discussed in more detail in the “PV Simulation” section of the terms & concepts page.

Tracking Options
The CprPVForm power model supports fixed tilt as well as single-axis and dual-axis tracking PV systems. Learn more about these tracking types and the different specification requirements for each one in the “Energy Sites” section of the terms & concepts page. To specify these different tracking types, use: Tracking=“Fixed”, Tracking=“SingleAxis”, or Tracking=“DualAxis”.

Attributes Required for Energy Site Creation

When creating an energy site for use with either power model, the attributes listed below are required, meaning they must be present in the EnergySiteCreateRequest to successfully create a site. While it is recommended to fill out as many of the energy site specifics as possible, the fields not in this list can be removed from the request if the information is not available.

  • Latitude
  • Longitude
  • Inverter Count
  • Inverter MaxPowerOutputAC_kW
  • Inverter EfficiencyRating_Percent
  • Module Count
  • Module NameplateDCRating_kW
  • PtcRating_kW
  • Array Azimuth_Degrees
  • Array Tilt_Degrees

Optional: Provide aCustomerSiteId when specifying EnergySite. This can be used to keep track of the mapping between client and Clean Power Research systems.