SolarAnywhere REST API
API Usage
In order to consume data and PV simulation services through the SolarAnywhere® REST API, you will need to supply a username, password, and client key via HTTP Basic Authentication. All clients should design their requests as single threaded, noting the availability of batch requests. Clients are also subject to a request throttle per standard usage terms. Requests to the API are made to the following base URL:
https://service.solaranywhere.com/api/
API Onboarding
For licensed API access, please contact us. After replacing the CLIENT_KEY with your client key token, HTTP GET requests of this form can easily be tested by entering the URL into a browser. Some API methods require HTTP POST requests to pass in XML along with the request. A simple way to test this is to use a tool such as the Firefox Poster extension, or the Google Chrome Postman, or Advanced REST Client for Google Chrome.
API Versions
When Clean Power Research updates the API, new data fields and simulation tools are added so as not to disturb the existing schema. Client developers should write their code in such a way as to ignore unrecognized attributes or elements so that they don’t break when new fields are added.
The API version is indicated in the URL by appending to the base URL as in:
https://service.solaranywhere.com/api/v1/
If requirements change such that the schema must be changed fundamentally, new API versions will be created. At that point, client developers will be encouraged to use the latest API in order to take advantage of new functionality. Old clients will be able to continue to use older versions of the API without modification.
Site Management Service Endpoints
These SolarAnywhere API services allow the client to build, manage and update PV site lists.
| Operation | Method | Relative URL |
|---|---|---|
| Get Energy Site List | Get | /v1/EnergySites?key=CLIENT_KEY |
| Get Energy Site Details | Get | /v1/EnergySites/ENERGY_SITE_ID?key=CLIENT_KEY |
| Create Energy Site | POST | /v1/EnergySites?key=CLIENT_KEY |
| Update Energy Site | POST | /v1/EnergySites/ENERGY_SITE_ID?key=CLIENT_KEY |
Get Energy Site List
This request will return the list of existing energy sites accessible by unique CLIENT_KEY. If you have not created any energy sites, then this request will respond with an empty list indicating that no energy sites have been created. Sites are listed by their ENERGY_SITE_ID 64-bit public ID.
| URL | /v1/EnergySites?key=CLIENT_KEY |
| Method | GET |
| Query String Parameters | CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/EnergySites?key=CLIENT_KEY |
| Sample Request XML | None |
| Sample Response | https://service.solaranywhere.com/Services/Documentation/GetSiteListResponse.xml |
Get Energy Site Details
This request will return the specification of the energy site identified by the ENERGY_SITE_ID. If your ENERGY_SITE_ID does not match a created site or site accessible under your CLIENT_KEY, the service will respond with an error.
| URL | /v1/EnergySites/ENERGY_SITE_ID?key=CLIENT_KEY |
| Method | GET |
| Query String Parameters | ENERGY_SITE_ID – Unique site ID, returned to client from Create Energy Site operation. CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/EnergySites/YTRZBTt_ekW4NpTR1nL67w?key=CLIENT_KEY |
| Sample Request XML | None |
| Sample Response | https://service.solaranywhere.com/Services/Documentation/GetSiteResponse.xml |
Create Energy Site
This operation allows clients to build energy sites over the web service. The client posts a site request XML with specifications that define the location, site hardware and hardware orientation. The request will return an ENERGY_SITE_ID 64-bit public ID. The client should store and use the ENERGY_SITE_ID to get weather, irradiance or simulated PV power from the site.
| URL | /v1/EnergySites?key=CLIENT_KEY |
| Method | POST |
| Query String Parameters | CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/EnergySites?key=CLIENT_KEY |
| Sample Request XML | https://service.solaranywhere.com/Services/Documentation/CreateSiteRequest.xml |
| Sample Response | https://service.solaranywhere.com/Services/Documentation/CreateSiteResponse.xml |
Create Site Request XML Fields
The energy system structure allows client applications to specify multiple subsystems, each with separate lists of inverters and arrays, and separate system losses. Each array, in turn, can have its own module specifications, array orientation and solar obstructions. All of these factors are taken into account during the energy simulation.
The client defines each site by passing the information described below, then requests data about the site based on the fields defined in the Intermediate Result Field section. All site specifications have the parent <EnergySiteCreateRequest>.
| Site XML Element | Parent | Description | Required? | Typical Range | Default Value | Variable Type (units) |
|---|---|---|---|---|---|---|
| Name | EnergySite | Client custom site name. | Yes | n/a | n/a | String (none) |
| Description | EnergySite | Client custom site description. | Yes | n/a | n/a | String (none) |
| Latitude_Degrees | EnergySite / Location | Latitude of the site. | Latitude / Longitude or Postal Code | -60.0 to 60.0 | n/a | Long (degrees) |
| Longitude_Degrees | EnergySite / Location | Longitude of the site. | Latitude / Longitude or Postal Code | -180.00 to 180.00 | n/a | Long (degrees) |
| PostalCode | EnergySite / Location | Site postal code is available for U.S. locations only. The geometric centroid of the postal code is chosen for identifying latitude and longitude. | Latitude / Longitude or Postal Code | n/a | n/a | Short (postal code) |
| Albedo_Percent | EnergySite / PVSystems / PVSystem | Albedo or ground reflectance of the site. | No | 10 to 30 | 17 | Short (percentage) |
| GeneralDerate_Percent | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem | System hardware derate not caused by module or inverter losses (i.e., wiring or mismatch loss). | No | 80 to 100 | 85 | Short (percentage |
| Count | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / Inverters / Inverter | Number of inverters for the site and specified subsystem. | No | 0 to 32,767 | n/a | Short (number) |
| MaxPowerOutput_kWAC | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / Inverters / Inverter | Maximum kilowatt AC (kWAC) output of the specified subsystem inverter (available from the inverter manufacturer). | No | 0 to 2000 | n/a | Float (kWAC) |
| EfficiencyRating_Percent | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / Inverters / Inverter | Inverter efficiency rating when module output converted into AC (available from the inverter manufacturer). | No | 0 to 100 | n/a | Short (percentage) |
| Count | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / PVModules / PVModule | Number of PV modules wired to the inverter of the parent subsystem. | No | 0 to 32,767 | n/a | Short (number) |
| NameplateDCRating_kWDC | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / PVModules / PVModule | The kilowatt DC (kWDC) nameplate rated output of the PV module(s) wired to the inverter of the parent subsystem (available from the module manufacturer). | No | 0 to 1 | n/a | Short (kWDC) |
| PtcRating_kWAC | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / PVModules / PVModule | The kilowatt AC (kWAC) rated output of the PV module(s) wired to the inverter of the parent subsystem, based on Performance Test Conditions (PTC) (available from the module manufacturer). | No | 0 to 1 | n/a | Short (kWAC) |
| PowerTemperatureCoefficient_PercentPerDegreeC | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / PVModules / PVModule | The temperature derate of the PV module(s) wired to the inverter of the parent subsystem in percentage of power reduction per degree Celsius difference from PTC. (available from the module manufacturer). | No | 0.05 to 1 | 0.4 | Short (percentage per degree C) |
| Azimuth_Degrees | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / ArrayConfiguration | The azimuth orientation angle of the PV module(s) wired to the inverter of the parent subsystem. South reference is 180 degrees. | N, required for Plane of Array Irradiance, AC Power or AC Energy | 90 to 270 | n/a | Short (degrees) |
| Tilt_Degrees | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / ArrayConfiguration | The tilted angle from horizon of the PV module(s) wired to the inverter of the parent subsystem. | N, required for Plane of Array Irradiance, AC Power or AC Energy | 0 (flat) to 90 | n/a | Short (degrees) |
| Tracking | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / ArrayConfiguration | The tracking type of the PV module(s) wired to the inverter of the parent subsystem. | No | Fixed Array, Single-Axis Tracker, Dual-Axis Tracker | Fixed Array | String (tracking type) |
| TrackingRotationalLimit_Degrees | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / ArrayConfiguration | The tracking rotational limit of the PV module(s) wired to the inverter of the parent subsystem. Applies to Single-Axis Trackers only. Degrees indicate symmetric rotation around the vertical (i.e., 90 indicates rotation from -45 to +45 degrees relative to vertical). | No | 45 to 90 | 90 | Short (degrees) |
| Azimuth_Degrees | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / SolarObstructions / SolarObstruction | Absolute azimuth degree to the horizon at which irradiance obstructions are positioned for the PV module(s) wired to the inverter of the parent subsystem. South reference is 180 degrees. | No | 90 to 270 | n/a | Short (degrees) |
| Elevation_Degrees | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / SolarObstructions / SolarObstruction | Degrees above the horizon to which irradiance obstructions to solar irradiance rises for the PV module(s) wired to the inverter of the parent subsystem. | No | 0 to 90 | n/a | Short (degrees) |
| SolarAccess_Percent | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / MonthlyShadings / MonthlyShading | Solar access can be applied as an alternate shading model, where total AC power or AC energy numbers are derated based on month. Applied to the PV module(s) wired to the inverter of the parent subsystem. Redundant definition of SolarObstruction and MonthlyShading defaults to SolarObstruction inputs. Input value of 100 refers to the unshaded case. | No | 0 to 100 | n/a | Short (percent) |
| MonthNumber | EnergySite / PVSystems / PVSystem / PVSubsystems / PVSubsystem / PVArrays / PVArray / MonthlyShadings / MonthlyShading | Month associated with solar access in MonthlyShading. 1=January, 2=February, and so on. | No | 1 to 12 | n/a | Short (month number) |
Update Energy Site
This operation allows clients to update the specification of their energy sites. The client posts a site request XML with specifications that define the location, site hardware and hardware orientation, but specifies the ENERGY_SITE_ID in the URL request. The ENERGY_SITE_ID does not change when the specification of the site is updated.
| URL | /v1/EnergySites/ENERGY_SITE_ID?key=CLIENT_KEY |
| Method | POST |
| Query String Parameters | ENERGY_SITE_ID – Unique site ID, returned to client from Create Energy Site operation. CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/EnergySites/L75Iib44BUii4XGS61oysg?key=CLIENT_KEY |
| Sample Request XML | https://service.solaranywhere.com/Services/Documentation/UpdateSiteRequest.xml |
| Sample Response | None |
Irradiance, Weather and PV Power Simulation Operation Endpoints
These SolarAnywhere API operations allow the client to request irradiance, weather and simulated PV power data of sites.
| Operation | Method | Relative URL |
|---|---|---|
| Simulate Single Energy Site | Get | /v1/Simulate?EnergySiteId=ENERGY_SITE_ID&StartTime=START_TIME& EndTime=END_TIME&INTERMEDIATE_RESULT_ID&key=CLIENT_KEY |
| Bulk Simulate Multiple Sites | POST | /v1/BulkSimulate?key=CLIENT_KEY |
Simulate Single Energy Site
This method is useful for single or a small number of site data requests and simulations. Whenever designing data requests and simulations around a large number of sites, it is suggested to use the Bulk Simulate Multiple Sites operation. Depending on licensed access, multiple intermediate results identifiers may be inserted in the query string to identify additional desired data output. Refer to the Intermediate Result Fields section for a list and description of available intermediate data.
| URL | /v1/Simulate?EnergySiteId=ENERGY_SITE_ID&StartTime=START_TIME&EndTime=END_TIME&INTERMEDIATE_RESULT_ID&key=CLIENT_KEY |
| Method | GET |
| Query String Parameters | ENERGY_SITE_ID – Unique site ID, returned to client from Create Energy Site operation. START_TIME – Beginning time of data request in ISO 8601 combined date-time format. END_TIME – Ending time of data request in ISO 8601 combined date-time format. INTERMEDIATE_RESULT – Data field requested. See list below. CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/Simulate?EnergySiteId=EHmMWnHp-EqzKJx3McTWWg&StartTime=2011-01-01T09:00:00-08:00&EndTime=2011-01-01T11:00:00-08:00&PowerAC&AmbientTemperature&WindSpeed&key=CLIENT_KEY |
| Sample XML Request | None |
| Sample Response | https://service.solaranywhere.com/Services/Documentation/SimulateResponse.xml |
Bulk Simulate Multiple Sites
When simulating a large number of systems, you can optimize performance by being mindful of performance differences between historic and recent/forecast SolarAnywhere data. The boundary between historic and recent/forecast SolarAnywhere data varies, but is approximately two months in the past. For recent/forecast SolarAnywhere data simulations, it’s most efficient to send in one request for all sites, or for as many sites as possible. This way it’s possible to avoid request timeouts when simulating longer time ranges by sending in multiple requests containing all sites, but cutting down on the timespan between the simulation start and end date. For historic SolarAnywhere data, there can be performance advantages to requesting simulations with fewer sites but longer time ranges for the start and end simulation time.
| URL | /v1/BulkSimulate?key=CLIENT_KEY |
| Method | POST |
| Query String Parameters | CLIENT_KEY – Unique user token, issued per license. Contact us to request. |
| Sample URL | https://service.solaranywhere.com/api/v1/BulkSimulate?key=CLIENT_KEY |
| Sample XML Request | https://service.solaranywhere.com/Services/Documentation/BulkSimulateRequest.xml |
| Sample Response | https://service.solaranywhere.com/Services/Documentation/BulkSimulateResponse.xml |
Intermediate Result Fields
It is possible to request a number of data fields, based on licensed access, that are either inputs to—or calculated by—the simulation process using the IntermediateResults array. The IntermediateResults array may contain any or all of the data identifiers in the following table.
Click here for a full description of available data fields. Certain data fields are dependent on the client defining site elements, as listed in Site XML Element Dependence. For instance, Global Horizontal Irradiance (GHI) can be returned when the client provides either the combined latitude and longitude, or the postal code.
| Intermediate Result | Description | Model Basis | Possible URL String Options | Variable Type (units) | Site XML Element Dependence |
|---|---|---|---|---|---|
| AC Energy | Total AC energy modeled during the time between Start and End Timestamps | Perez Irradiance Model, Perez Transposition, CPR Shading Model, PVFORM | ‘EnergyAC’ | Long (kWh) | Location, Inverter, PVArray, ArrayConfiguration |
| AC Power | Average AC power modeled during the time between Start and End Timestamps | Perez Irradiance Model, Perez Transposition, CPR Shading Model, PVFORM | ‘PowerAC’ | Long (kW) | Location, Inverter, PVArray, ArrayConfiguration |
| Plane of Array Irradiance (POAI) | Average irradiance on the plane of array between Start and End Timestamps | Perez Irradiance Model, Perez Transposition | ‘PlaneOfArrayIrradiance’ | Long (W/m2) | Location, ArrayConfiguration |
| Global Horizontal Irradiance (GHI) | Average irradiance on a horizontal plane between Start and End Timestamps | Perez Irradiance Model | ‘GlobalHorizontal’ | Long (W/m2) | Location |
| Direct Normal Irradiance (DNI) | Average irradiance on a surface normal to the sun between Start and End Timestamps | Perez Irradiance Model | ‘DirectNormal’ | Long (W/m2) | Location |
| Diffuse Horizontal Irradiance (DIF) | Average irradiance on a horizontal plane not due to a direct path from the sun between Start and End Timestamps | Perez Irradiance Model | ‘DiffuseHorizontal’ | Long (W/m2) | Location |
| Wind Speed | Wind speed at 10-meter height | Numerical Model Sourced by Geography | ‘WindSpeed’ | Long (m/s) | Location |
| Ambient Temperature | Ambient air temperature at 2-meter height | Numerical Model Sourced by Geography | ‘AmbientTemperature’ | Long (degreesC) | Location |
| Snow Depth | Millimeters of compacted snow depth on the ground | CPR Snow and Precip Model | ‘SnowDepth’ | Long (mm) | Location |
| Solid Precipitation | Average kilograms per square meter of solid precipitation | CPR Snow and Precip Model | ‘SolidPrecipitation’ | Long (kg/m2/hour) | Location |
| Liquid Precipitation | Kilograms per square meter of liquid precipitation | CPR Snow and Precip Model | ‘LiquidPrecipitation’ | Long (kg/m2/hour) | Location |
| [SolarAnywhere Time-Series Version] | ‘SolarAnywhere2_2’, ‘SolarAnywhere2_3’, ‘SolarAnywhere2_4’ | N/a | N/a | ||
| [Typical Year Version] | ‘SolarAnywhereTGY2012’, ‘SolarAnywhereTDY2012’, ‘TMY3’ | N/a | N/a |