REST API Basics

Requests

Overview

API requests should use the appropriate URL depending on the type of functionality. For solar simulations with EnergySiteIds, use the following base URL:

 

https://service.solaranywhere.com/api/v1/

 

For solar simulations without EnergySiteIds, use the following base URL:

 

https://service.solaranywhere.com/api/v2/

 

APIs specifically used to access irradiance and weather data will use a different URL. See Irradiance and Weather Data, or Contact Us for more information.

 

Some of our APIs support HTTP GET such as the EnergySites and Simulate methods. Other API methods such as the BulkSimulation and Simulation methods only support HTTP POST, since the request can be quite large.

 

All Solar Simulation API methods support XML (Extensible Markup Language) exclusively. Depending on the language and framework, when using POST, developers may need to explicitly specify the Content-Type request header to be “text/xml”. Other API methods may support XML, and in that case, the content type will be “application/xml”.

Authentication

All API methods require the use of Basic Authentication where a username and password are sent in the Authorization request header. Clean Power Research will provide these credentials to developers. Note that you should keep these credentials in a safe and secure place, and in general, it’s safer to call the Clean Power Research APIs from the server side.

Encryption

All requests should use HTTPS to ensure that basic authentication credentials are shared securely. Requests using HTTP are not supported.

Compression

Compression is not currently supported for any Solar Simulation method.

Responses

Overview

Currently, response payloads use the same data format used in the request. Reference the Complete Schema documentation to learn more about the response payloads and the information returned.

Errors

When a response is received, developers should first check the HTTP status code:

 

  • 200 – The request was processed successfully and a response was returned.
  • 429 – Too many requests. Caller will be throttled. Clients can Contact Us to increase their throttle or impose an exponential back off strategy.
  • 400 – Bad request. The request may be formatted incorrectly, required parameters may be missing or an invalid name or value may have been used.
  • 401 – Unauthorized. User name or password may be incorrect.
  • 500 – Internal error. Oops, this may be our fault.

 

Clean Power Research APIs also return detailed error information in the response payload when an error occurs while processing the request. This information can be useful during development to troubleshoot failures.
 
Here’s an example of what a response may look like when a call fails due to an invalid element in the request:

<GetSimulationResultResponse SimulationId="1Y4ACW8" Status="Done"
RequestId="4KRDGLNPL" xmlns="http://service.solaranywhere.com/api/v2">  <SimulationResults>   <SimulationResult Status="Failure">    <ErrorMessages>     <ErrorMessage StatusCode="BadRequest" Message="Module Count must be specified"/>    </ErrorMessages>   </SimulationResult>  </SimulationResults> </GetSimulationResultResponse>

What’s Next?