REST API Basics

Requests

Overview

API requests should use the appropriate URL depending on the type of functionality. For utility rates and bill savings, use the following base URL:

 

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

 

APIs specifically for solar simulations and accessing irradiance and weather data will use a different URL. Visit SolarAnywhere.com, or Contact Us for more information.

 

Some of our APIs support HTTP GET such as the Rates method. Other API methods such as the BillSavings method only support HTTP POST, since the request can be quite large.

 

All Utility Rates & Bill Savings API methods support JSON (Javascript Object Notation) exclusively. Depending on the language and framework, when using POST, developers may need to explicitly specify the Content-Type request header to be “text/json”. 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 required when request payloads become too large. This is true for the Bill and BillSavings methods when using 15-minute, 30-minute or hourly interval data. When using compressed requests, developers should set Content-Encoding request header to “gzip.”

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 check the Retry-After header in the response to know how many seconds they need to wait until the next call can be made.
  • 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:

 

{"StatusCode":"BadRequest","Message":"Invalid energy measure type: <your_typo>."}
What’s Next?

Get an API Key