REST API Basics

Requests

Overview

API requests should use the appropriate URL depending on the type of functionality. For Irradiance and Weather Data requests, use the following base URL:

 

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

 

APIs specifically for performing solar simulations use a different URL. See Solar Simulations, or Contact Us for more information.

 

The API method used to request irradiance and weather data, WeatherData, supports HTTP POST since the request can be quite large. The data request is processed asynchronously, and HTTP GET is then used to retrieve data.

 

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

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 Irradiance and Weather Data 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, may have required parameters missing, or may use an invalid name or value.
  • 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:

<GetWeatherDataResultResponse WeatherRequestId="D1BVM14" Status="Done" RequestId="PKEH7YMTW" xmlns="http://service.solaranywhere.com/api/v2">
 <WeatherdataResults>
  <WeatherDataResult SiteName="Los Angeles" Status="Failure">
   <ErrorMessages>
    <ErrorMessage StatusCode="InvalidLocation" Message="Tile is outside of our coverage area (Latitude = 34.00, Longitude = -128.40)"/>
   </ErrorMessages>
  </WeatherDataResult>
 </WeatherdataResults>
</GetWeatherDataResultResponse>

What’s Next?