How to Authenticate and Make Requests From the Data API (Curl)

Overview

The Verdigris DataAPI allows for the fetching of data collected by your Verdigris system.

Authenticating with an OAuth Access Token

Open a command line interface and ensure you have the curl command installed. Run the following command, substituting "<client_id>" and "<client_secret>" with your values. If you don't have your API keys, see "How do I create or manage API keys?"

$ curl https://auth.verdigris.co/oauth/token -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&audience=https://api.verdigris.co/'

Your response should look something like this:

{
 "access_token":"<bearer_token>",
 "scope":
         "read:breakers 
          read:buildings 
          read:circuits 
          read:panels     
          read:energy 
          read:power_factor",
 "expires_in":3600,
 "token_type":"Bearer"
}

In the above, "<bearer_token>" is an alpha-numeric string that can then be used to perform other operations on the Verdigris API endpoints. It will expire after 3600 seconds (one hour).

Make Requests using Bearer Token

For example, if you wanted to get all information on all of the buildings from the buildings endpoint, you can do a GET request using the "/buildings/" endpoint. Use the bearer token from last step.

$ curl -X GET https://api.verdigris.co/core/v1/buildings/ -H "Accept: application/json" -H "Authorization: Bearer <bearer_token>"

Client Errors

1. Authentication Error: A valid access_token must be provided in the Authorization headers.HTTP/1.1 404 Not Found{"error":"Couldn't find ApiKey with access_token = "}

2. Resource Error: This error could be due to the fact that the resource requested is not accessible by the access_token specified. HTTP/1.1 404 Not Found {"error":"Couldn't find Circuit with id=<circuit_id> [WHERE "memberships"."user_id" = <user_id>]"}

Limits

The api is rate limited to 5 requests per second for any resource listed. Example error message: HTTP/1.1 429 Too Many Requests Retry Later
Each request for energy data is limited to a total of 1,500 data points across models. (i.e. 1 circuit and 1,500 data points is allowed, 2 circuits and 750 datapoints each is also allowed, and so on)Example error message: HTTP/1.1 400 Bad Request {"error":"Invalid parameter 'ids, start_time, end_time' value ["1,2", "2017-01-01T00:00:00.000Z", "2017-03-01T00:00:00.000Z"]: requested too many datapoints"}