CreateSimulationRequest

Basic Asynchronous Request

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

Use the example simulation requests below to make requests for irradiance, weather, energy, and power output data using an EnergySiteId. EnergySiteIds are returned in the EnergySiteCreateResponse returned after submitting an EnergySiteCreateRequest.

Clean Power Research offers two simulation models for use as the PowerModel in your simulation requests: pvlib and CprPVForm. The XML simulation request samples below are divided by model. Visit the introduction page to learn more about the simulation models and decide which is better suited to your needs.

Create a Simulation Request Using the pvlib Power Model

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

<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="D7RCV0GWVQ"> </EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="PvLib" 
  SnowLossModel="None"
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,PowerDC_kW,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,
  DirectNormalIrradiance_WattsPerMeterSquared,DiffuseHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType,
  AmbientTemperature_DegreesC,AmbientTemperatureObservationType,WindSpeed_MetersPerSecond,WindSpeedObservationType,
  PlaneOfArrayIrradiance_WattsPerMeterSquared,ClearSkyPowerAC_kW,ClearSkyEnergyAC_kWh,RelativeHumidity_Percent,SnowDepth_Meters,
  LiquidPrecipitation_KilogramsPerMeterSquared,SolidPrecipitation_KilogramsPerMeterSquared,Albedo_Unitless">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-02-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="D7RCV0GWVQ"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="PvLib"
  SnowLossModel="NREL"
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,PowerDC_kW,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,
  DirectNormalIrradiance_WattsPerMeterSquared,DiffuseHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType,AmbientTemperature_DegreesC,
  AmbientTemperatureObservationType,WindSpeed_MetersPerSecond,WindSpeedObservationType,PlaneOfArrayIrradiance_WattsPerMeterSquared,
  ClearSkyPowerAC_kW,ClearSkyEnergyAC_kWh,RelativeHumidity_Percent,SnowDepth_Meters,LiquidPrecipitation_KilogramsPerMeterSquared,
  SolidPrecipitation_KilogramsPerMeterSquared,Albedo_Unitless,SnowLossesDC_kW,SnowLossesDC_Percent">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-02-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
Snow Loss Modeling
The pvlib power model allows you to model snow losses using Bill Marion’s snow loss model. Learn more about this snow loss model in the “PV Simulation” section of the Terms & Concepts page. In order to model snow losses, specify SnowLossModel=”NREL” as a <SimulationOptions> element and include SnowLossesDC_kW and SnowLossesDC_Percent in the OutputFields list of your simulation request. If you do not want to model snow losses, specify SnowLossModel=”None” or remove it from the request completely.

Snow loss output fields can only be specified when requesting historical or real-time time series data. Real-time time series requests for snow loss output fields outside the Continental United States are limited to the trailing week rather than the current hour. These fields cannot specified when requesting a typical year or average year WeatherDataSource or when requesting forecasted time series data.

Create a Simulation Request Using the CprPVForm Power Model

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

<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="NZ3RTPHLJE"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="CprPVForm"
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,
    EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,DirectNormalIrradiance_WattsPerMeterSquared,
    DiffuseHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType,AmbientTemperature_DegreesC,
    AmbientTemperatureObservationType,WindSpeed_MetersPerSecond,WindSpeedObservationType,
    PlaneOfArrayIrradiance_WattsPerMeterSquared,CapacitySimulatedDC_Percent,CapacitySimulatedDC_kW,
    ClearSkyPowerAC_kW,ClearSkyEnergyAC_kWh,RelativeHumidity_Percent,SnowDepth_Meters,LiquidPrecipitation_KilogramsPerMeterSquared,
    SolidPrecipitation_KilogramsPerMeterSquared,Albedo_Unitless">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-02-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.1"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="NZ3RTPHLJE"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="CprPVForm"
  ShadingModel="ShadeSimulator" 
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,
    EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,DirectNormalIrradiance_WattsPerMeterSquared,
    DiffuseHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType,AmbientTemperature_DegreesC,
    AmbientTemperatureObservationType,WindSpeed_MetersPerSecond,WindSpeedObservationType,
    PlaneOfArrayIrradiance_WattsPerMeterSquared,CapacitySimulatedDC_Percent,CapacitySimulatedDC_kW,
    ClearSkyPowerAC_kW,ClearSkyEnergyAC_kWh,RelativeHumidity_Percent,SnowDepth_Meters,LiquidPrecipitation_KilogramsPerMeterSquared,
    SolidPrecipitation_KilogramsPerMeterSquared,Albedo_Unitless">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-02-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="NZ3RTPHLJE"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="CprPVForm"
  ShadingModel="MonthlyPercentSolarResource" 
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,
    EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,DirectNormalIrradiance_WattsPerMeterSquared,
    DiffuseHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType,AmbientTemperature_DegreesC,
    AmbientTemperatureObservationType,WindSpeed_MetersPerSecond,WindSpeedObservationType,
    PlaneOfArrayIrradiance_WattsPerMeterSquared,CapacitySimulatedDC_Percent,CapacitySimulatedDC_kW,
    ClearSkyPowerAC_kW,ClearSkyEnergyAC_kWh,RelativeHumidity_Percent,SnowDepth_Meters,LiquidPrecipitation_KilogramsPerMeterSquared,
    SolidPrecipitation_KilogramsPerMeterSquared,Albedo_Unitless">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-02-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
Shading Models

There are two shading models you can specify when using the CprPVForm power model. You will need to specify the shading model corresponding to the way shading was defined in the EnergySiteCreateRequest. Visit the “PV Simulation” section of the Terms & Concepts page to learn more about these shading models.

  • ShadeSimulator
  • MonthlyPercentSolarResource

Output Field Options

This the the list of output fields and summary output that can be requested. The list include both irradiance and weather data outputs and simulation outputs. For more information, see Irradiance and Weather Data – Options or Solar Simulations – Terms and Concepts.
 
Irradiance and Weather Data Output Fields:

  • StartTime
  • ObservationTime
  • EndTime
  • GlobalHorizontalIrradiance_WattsPerMeterSquared
  • DirectNormalIrradiance_WattsPerMeterSquared
  • DiffuseHorizontalIrradiance_WattsPerMeterSquared
  • IrradianceObservationType
  • AmbientTemperature_DegreesC
  • AmbientTemperatureObservationType
  • WindSpeed_MetersPerSecond
  • WindSpeedObservationType
  • ForecastLeadTime_Minutes
  • RelativeHumidity_Percent
  • SnowDepth_Meters1, 2
  • LiquidPrecipitation_KilogramsPerMeterSquared1, 2
  • SolidPrecipitation_KilogramsPerMeterSquared1, 2
  • SolarZenithAngle_Degrees
  • SolarAzimuthAngle_Degrees
  • Albedo_Unitless1
  • ParticulateMatter2.5_MicrogramsPerMeterCubed1
  • ParticulateMatter10_MicrogramsPerMeterCubed1

Simulation Output Fields:

  • PowerAC_kW
  • PowerDC_kW
  • EnergyAC_kWh
  • PlaneOfArrayIrradiance_WattsPerMeterSquared
  • PVModuleTemperature_DegreesC
  • ClearSkyPowerAC_kW
  • ClearSkyEnergyAC_kWh
  • SnowLossesDC_kW1, 2, 3
  • SnowLossesDC_Percent1, 2, 3

Irradiance and Weather Data Summary Output Fields:

  • TotalEnergy
  • TotalGlobalHorizontalIrradiance
  • TotalDirectNormalIrradiance
  • TotalLiquidPrecipitation1, 2
  • TotalSolidPrecipitation1, 2
  • AverageSnowDepth1, 2
  • AverageWindSpeed
  • AverageAmbientTemperature
  • AverageAlbedo1
  • AveragePm2.51
  • AveragePm101

Simulation Summary Output Fields:

  • TotalEnergy
  • TotalSnowLosses1, 2, 3
  • AveragePercentSnowLosses1, 2, 3

1 Not available for forecasted time periods.
2 Not available in requests for typical year WeatherDataSources.
3Field can only be requested when you have specified PowerModel=”PvLib” and SnowLossModel=”NREL”, and you are requesting historical or real-time time series data. Real-time time series requests for this field outside the Continental United States are limited to the trailing week rather than the current hour.

Weather Data Options

WeatherDataOptions attributes specify the source of weather data used in the Simulation request. For more detailed information, see Irradiance and Weather Data Options. The specific WeatherDataSource selected is license and application dependent.

Simulation Requests with Summary Output Fields

Below are some additional example simulation requests that include summary output fields. Summary output fields will request results aggregated by month and year. These can be requested alongside time series, typical year, or average year data.

<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="D7RCV0GWVQ"> </EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="PvLib"
  SnowLossModel="NREL"
  OutputFields="StartTime,ObservationTime,EndTime,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,
  DirectNormalIrradiance_WattsPerMeterSquared,AmbientTemperature_DegreesC,WindSpeed_MetersPerSecond,SnowDepth_Meters,
  Albedo_Unitless,SnowLossesDC_kW,SnowLossesDC_Percent"
  SummaryOutputFields="TotalEnergy,TotalGlobalHorizontalIrradiance,TotalDirectNormalIrradiance,AverageWindSpeed,
  AverageAmbientTemperature,AverageSnowDepth,AverageAlbedo,TotalSnowLosses,AveragePercentSnowLosses">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2021-01-01T00:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="D7RCV0GWVQ"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="PvLib"
  SnowLossModel="None"
  OutputFields="StartTime,ObservationTime,EndTime,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,
  DirectNormalIrradiance_WattsPerMeterSquared,AmbientTemperature_DegreesC,WindSpeed_MetersPerSecond,Albedo_Unitless"
  SummaryOutputFields="TotalEnergy,TotalGlobalHorizontalIrradiance,TotalDirectNormalIrradiance,AverageWindSpeed,
  AverageAmbientTemperature,AverageAlbedo">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhereTGY2020"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>

Bulk Simulation Requests

Below are some additional example simulation requests that include multiple energy sites. The GetSimulationResultResponse will contain the results for each energy site specified. When using the pvlib simulation model, you can make a request containing up to 5 energy sites. When using the CprPVForm simulation model, you can include an unlimited number of energy sites.

<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="D7RCV0GWVQ"></EnergySite>
    <EnergySite EnergySiteId="3MA0Z5H564"></EnergySite>
    <EnergySite EnergySiteId="DYQX7DUVWG"></EnergySite>
    <EnergySite EnergySiteId="L26ZDBF9P8"></EnergySite>
    <EnergySite EnergySiteId="M8OGEJN1QI"></EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="PvLib" 
SnowLossModel="None"
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,PowerDC_kW,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-01-01T15:00:00-08:00"
    SpatialResolution_Degrees="0.01"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>
<CreateSimulationRequest xmlns="http://service.solaranywhere.com/api/v2">
  <EnergySites>
    <EnergySite EnergySiteId="NZ3RTPHLJE"></EnergySite>
    <EnergySite EnergySiteId="6N0QX6E2U9"></EnergySite>
    <EnergySite EnergySiteId="NBGTY7NBK2"></EnergySite>
    <EnergySite EnergySiteId="FCDVD4A2CQ"></EnergySite>
    <EnergySite EnergySiteId="6FTJ1WT0PM"></EnergySite>
    <EnergySite EnergySiteId="XA70N15TNW"></EnergySite>
    </EnergySite>
  </EnergySites>
  <SimulationOptions
  PowerModel="CprPVForm"
  OutputFields="StartTime,ObservationTime,EndTime,PowerAC_kW,PowerDC_kW,EnergyAC_kWh,GlobalHorizontalIrradiance_WattsPerMeterSquared,IrradianceObservationType">
    <WeatherDataOptions
    WeatherDataSource="SolarAnywhere3_5"
    WeatherDataPreference = "Auto"
    PerformTimeShifting = "true"
    StartTime="2020-01-01T00:00:00-08:00"
    EndTime="2020-01-01T15:00:00-08:00"
    SpatialResolution_Degrees="0.1"
    TimeResolution_Minutes="60"/>
  </SimulationOptions>
</CreateSimulationRequest>