Overview

The Verdigris API allows for fetching of data collected by buds in the Verdigris ecosystem.

Authentication

The only way to authenticate with the API is to pass in an Authorization http header as shown in the example below:

$ curl -i https://app.verdigris.co/api/v3/circuits/1765/ -H "Authorization: Token token=<access 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 = <invalid 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

  1. 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
  2. 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"}


Access Token

To request an access token, email support@verdigris.co.

Resources

Breakers

Resource Description
GET /api/v3/breakers List breakers
GET /api/v3/breakers/:id Show a breaker
GET /api/v3/breakers/energy Energy data for breakers

Buildings

Resource Description
GET /api/v3/buildings List buildings
GET /api/v3/buildings/:id Show a building
GET /api/v3/buildings/energy Energy data for buildings
GET /api/v3/buildings/:building_id/forecast Forecasted data for buildings

Circuits

Resource Description
GET /api/v3/circuits List circuits
GET /api/v3/circuits/:id Show a circuit
GET /api/v3/circuits/energy Energy data for circuits
GET /api/v3/circuits/:circuit_id/disag Show disaggregation data for a circuit

Panels

Resource Description
GET /api/v3/panels List panels
GET /api/v3/panels/:id Show a panel
GET /api/v3/panels/energy Energy data for panels