REST API Basics

Overview

The SolarAnywhere API adheres to the REST API architecture. Requests are managed through HTTP. The base URL for all SolarAnywhere API requests is: https://service.solaranywhere.com/api/v2/. To specify the type of request you are making, you will add to the end of this URL. When managing energy sites, you will add either: EnergySites or EnergySites/ENERGY_SITE_ID. When making energy simulation requests you will add either: Simulation or SimulationResult/{SimulationId}. The complete schema outlines the scenarios where you will use each of these URLs.

Solar Simulations API methods support JSON (JavaScript Object Notation) and XML (Extensible Markup Language). Follow the instructions below to specify one of these two options:

  • JSON: Include the header ‘content-type’: “application/json”. Some languages and frameworks will require that you also specify ‘Accept’: “application/json”.
  • XML: For languages and frameworks that support XML, you can specify the header ‘content-type’: “application/xml”, otherwise you will need to specify ‘content-type’: “text/xml”.

Authentication

All API methods require the use of either an API Key or Basic Authentication credentials where either a 64-character unique key or a username and password are sent in the Authorization request header. Visit our support center to learn how to generate an API key. Note that you should store 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 API keys or basic authentication credentials are sent securely. Requests using HTTP are not supported.

Compression

Compression is not currently supported for any Solar Simulation method.

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. The API key is invalid or the 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"<br> 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?

Get an API Key