REST API Basics

Overview

The SolarAnywhere API adheres to the REST API architecture where 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 making requests for irradiance and weather data you will add either: WeatherData or WeatherDataResult/{WeatherRequestId}. The complete schema (summarized below) outlines the scenarios where you will use each of these URLs.

The irradiance and weather API uses the following asynchronous request structure:

  1. CreateWeatherDataRequest: The client asks the server to generate SolarAnywhere irradiance and weather data. The client’s request contains data specifications such as the SolarAnywhere WeatherDataSource, SpatialResolution_Degrees, TemporalResolution_Degrees, etc.
  2. CreateWeatherDataResponse: The server responds with a unique WeatherRequestId.
  3. GetWeatherDataResultsRequest: The client uses the unique WeatherRequestId to retrieve the data from the server.
  4. GetWeatherDataResultResponse: The server returns the data.

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

<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?