API Documentation

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 (zipped) 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 (zipped) 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 (zipped) CreateSiteRequest.xml
Sample Response (zipped) 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 (zipped) 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 (zipped) 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 (zipped) BulkSimulateRequest.xml
Sample Response (zipped) 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