One of the best ways to access your Verdigris data is through the API. This might sound intimidating to some non-engineers, but it's probably easier than you think and can be done successfully without an engineering degree.
These instructions are for beginners with little or no coding skills using popular free software. If you're more advanced, feel free to use whatever tools or techniques you prefer.
- Download an API client app (this will be the easiest method for most people). Postman offers a popular free client that allows you to save queries or share with colleagues. https://www.getpostman.com/product/api-client. Insomnia is another option: https://insomnia.rest/. (Verdigris has no interest in or affiliation with either of these companies or products.)
- In your browser go to Verdigris API docs (app.verdigris.co/docs) and select the resource you're interested in, for example: Breakers > Energy.
- In the "Example Request" box for the resource, copy the string that begins with
- Open the API client app that you just installed (Postman or other).
- Click the "New" or "+" button to create a new query.
- Beneath "Untitled Request" and to the left of the "Send" button, make sure it's set to "Get" from the dropdown list (this basically means "read" data, so that you don't change or delete anything).
- Paste the string from the API docs in the field that says "Enter request URL".
- Depending on the client you are using this may automatically populate the Query Params, but you will have to edit the Keys and Values to replace example data or cURL formatting:
- Check the Verdigris API docs to make sure all required parameters ("Params") are identified in the "Key" list for your client app, e.g.
- Update the "Value" for each Key based on what you want to query. Make sure your values match the approved formats specified in the docs. (See below.)
- Create an authorization header to enable your secure access to your data. If your client has one, click the Headers tab;
- For Key enter
- For Value enter
Token token=[your API key]where your key is the alphanumeric code generated from the Admin Console (e.g.
- When you're done, click the blue "Send" button to run your query. You can also save your query for future use.
- If your query was successful you will see the results in the "Body" section of your client app, displayed in the format shown in the Verdigris API docs.
- If your query was unsuccessful you will receive an error code. Check all of your Keys and Values to make sure everything complies with the formatting guidelines in the Docs.
- Once you have a successful query you can copy or export the data to a spreadsheet or other data analysis tool to do your own analysis or build your own visualizations.
- You may need to start with a couple of queries to find the Panel, Breaker, or Circuit IDs for your building. See the Verdigris API Docs for details on these queries. app.verdigris.co/docs
- The default timestamp for the API will be in unix epoch format. You can change the format but you will also need to account for UTC offset (e.g. "-8") and timezone to get the timestamp in your correct local time.
- The "energy" resource returns units in watt-hours. You can easily convert this resource to other formats like kWh or kW if you prefer:
- To convert to kWh, divide by 1000.
- To convert to "power" (watts), multiply by the unit of time to get 60 minutes. I.e. if you queried
minutelydata, multiply by 60. If you queried
15-minutelymultiply by 4.
If you need more help with the API, please contact us by clicking the chat bubble on the right, or emailing firstname.lastname@example.org.