Description
This article is designed to provide users with instructions on how to leverage CopperTree’s APIs to pull data out of Kaizen.
Notes:
The Building ID is the number found after “buildings/” in the URL:
https://kaizen.coppertreeanalytics.com/v3/#/clients/877/buildings/3691
In the above example 3691 is the Building ID
Get JWT Token
First, the identity of the user must be confirmed to ensure that site data is going into the right hands. This is done through the production of an Auth0 JWT token.Reach out to [email protected] and mention that you would like to work with the Insights API. You will receive a Client_ID and Client_Secret; use these parameters with the following cURL command to produce the token:
curl --request POST \
--url https://login-global.coppertreeanalytics.com/oauth/token \
--header "content-type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials" \
--data "client_id=<client_id>" \
--data "client_secret=<client_secret>" \
--data "audience=organize"
Once a user acquires a token, they can use it to pull data
Insights API
Get data from the Insights Log
To get a list of all Insights you can use this resource:https://kaizen.coppertreeanalytics.com/yana/rulestate/public-api/v1/insights/[building_id]
where the Building_ID can be found in the URL of any page in the Building.
This endpoint uses pagination. Each call returns 500 results.
To get the history for an active Insight you can use this resource:https://kaizen.coppertreeanalytics.com/yana/rulestate/public-api/v1/insight-history/[insight_id]
where the Insight_ID can be found in Insight’s Details.
Class IDs (class_id) can be specified to call a particular Insight type. The insight types and their corresponding class IDs are given below.
| Insight Type | class_id |
|---|---|
| Alarm | 1 |
| Notification | 2 |
| Fault Detection | 3 |
| Energy | 4 |
| Golden Standard | 7 |
| KPI | 8 |
| Report | 9 |
| 10 | |
| Infrastructure | 11 |
| Integrity KPI | 12 |
| Energy KPI | 13 |
| K-Link | 14 |
Example API call
cURL Example to get a list of all Insights:
curl --request GET \
--url https://kaizen.coppertreeanalytics.com/yana/rulestate/public-api/v1/insights/2914 \
--header "Authorization: Bearer <jwt access_token>"
Users can apply an optional filter on Insight State to get only Insights that are active or inactive.
?state='inactive'
cURL Output Example:
{
"_id": "2914.1000.AO4-Commissioned Output commanded to Manual",
"active_since": "Mon, 04 May 2020 17:31:40 GMT",
"device": 1000,
"insight_blt": "Sun, 13 Dec 2020 17:35:35 GMT",
"insight_class_id": 11,
"insight_class_name": "Infrastructure",
"insight_id": "2914.1000.AO4-Commissioned Output commanded to Manual",
"message": "AHU4B_MAD (1000.AO4) - Commissioned Output commanded to Manual",
"priority_id": 2,
"rule": "Commissioned Output commanded to Manual",
"state": "active",
"system_id": null,
"system_name": null,
"system_tags": null,
"threshold": "",
"value": "30 %"
}
Trend Log API
To get trend data:
https://kaizen.coppertreeanalytics.com/public_api/api/get_tl_data_start_end?api_key=<api_key>&tl=<tl_ref>&start=<start_date>&end=<end_date>&format=json&data=<raw or align>
where:
- api_key is the user’s Kaizen Key. Your API key is: 8b4c2b51408a4269 (from the User Profile page)
- tl_ref is the full reference for the trend log, in the format ..TL
- Example: 123.TL45 from the following building: https://kaizen.coppertreeanalytics.com/v3/#/clients/551/buildings/2914 would be 2914.123.TL45. This will also be displayed in the URL when viewing this TL in the Vault.
- start_date and end_date is the desired period start/end dates in the format YYYY-MM-DDThh:mm:ss e.g. 2018-01-01T00:00:00
- &data will determine if data’s timestamps should be normalized or left in raw format
- raw will give the time-stamps and data exactly as they are read from the BAS
- align will normalize the time-stamps to be aligned to 5-minute intervals. This must be defined to replicate the behavior of the BP API for point data.
Curl Example:
curl “https://kaizen.coppertreeanalytics.com/public_api/api/get_tl_data_start_end?api_key=<api_key>&tl=<tl_ref>&start=<start_date>&end=<end_date>&format=json&data=raw”
To get a list of trend logs for a building:
https://kaizen.coppertreeanalytics.com/api/v3/trend_log_objects/?building=<building_id>
where:
- is the id for the building.
- Make sure to add an authorization header:
- “Authorization token ” where is the user’s Kaizen Key
- Pagination:
- Add “&page=” where page_number is the page you want to view.
Curl Example:
curl -H "Authorization: token <api_key>” “https://kaizen.coppertreeanalytics.com/api/v3/trend_log_objects/?building=<building_id>&page=1”
API Call to get data from a Rule
The Application Programming Interface (API) is used to get CopperTree data from the cloud, for use outside of Kaizen. This API can be used to power dashboards, provide data to program BACnet controls, and run third-party reports.
Every Insight that you create through templates can be used to gather data for another use. In order to collect those data, you will use the Kaizen API to return data in either XML or JSON format. The data is drawn from logic flows. The API runs a rule Insight over a date range and returns the values of specified logic blocks. There is another API to directly get TL data. For example, if there is a simple fault detection created in a logic flow and you need to display some specific data, the API could be used. The API would refer to an instance (an actual Insight) with proper trend log inputs and reference the given blocks. In this specific case, your Insight checks if your VAV is running correctly. Your Insight compares the temperature to its set point and returns the difference. Your goal is to use this difference for another purpose. You will ask the API to run this Insight and draw the data create by the given block. The API returns the value/timestamp pairs of specified blocks within a logic flow, over a specified time range.
API parameters
The API consists of a central source and a list of parameters. In order to run the right Insight and to draw the needed data, you will set parameters up. The parameters are of the form “¶meter=field”, where the “parameter” is what the URL is referencing (&Start means start time, for example), and the “field” is the entered value (such as ‘2014-03-24T16:43:57’ for the start time).
| Parameter | Description | Example |
|---|---|---|
| api_key | This is the “Kaizen Key” key found within a user’s profile in Kaizen. It is security to protect your data. | 1234567890abcde |
| type | This specifies the location of the logic flow. Please keep this as “rule”. | rule |
| instance_id | This is the instance ID found under the Working Rule. The inputs to this instance will be the data analyzed in the logic flow. | 5555 |
| series_ids | This is a list of the blocks that you want to retrieve data. | 1,2,3,5,8,13,21 |
| start | the start date of your time range using this format “YYYY-MM-DDTHH:MM:SS” | 2014-03-14T16:43:57 |
| end | the end date of your time range using this format “YYYY-MM-DDTHH:MM:SS” | 2014-03-24T16:43:57 |
| interval | The interval is the aggregating period that it will use if you set up our blocks to ‘request’ aggregating intervals. | Daily |
| format | The API will return value with a specific format. You can choose between the three following formats: Enteleviz, Logi, Xml | enteliviz |
API Sample:
The API is always shown as a URL: In this example – use the values provided as examples above
https://kaizen.coppertreeanalytics.com/public_api/api/get_instance_values?&api_key=1234567890abcde&type=rule&instance_id=5555&series_ids=1,2,3,5,8,13,21&start=2014-01-13T00:00:00&end=2014-03-30T23:59:59&interval=Daily&format=enteliviz
API Parameters definition:
api_key
This is the “Kaizen Key” key found within a user’s profile in Kaizen. To navigate to the user’s profile:
- from any Kaizen page, click on your name in the top line.
- Click Profile from the drop-down menu.
- Select and copy the ‘Kaizen Key’ which is about halfway down the page.
type
This specifies the location of the logic flow. Please keep this as a “rule”.
instance_id
The instance ID, otherwise known as the Insight ID on Kaizen, is found in the Working Rule Insight View. There will be two numbers separated by a period. Take the number after the period, as it refers to the actual instance. The first number refers to the template ID and is not used here.
Note: that the inputs to the chosen Insight will be the data analyzed in the logic flow.
series_id
This is used to refer to the logic blocks to draw data. Each block is a logic flow that has a number below the title, surrounded by a bracket. This is the “logic series ID”, and is unique for each block in a logic flow. In the picture below, there are several logic series IDs highlighted.
The series_ids parameter consists of a list of these numbers, separated by commas. Each number passed to the API will produce a unique value and timestamp, specific to the logic block.
Note: that there should be no comma following the last number.
Example: 2,4,3,5,6 The above example refers to blocks 2, 3, 4, 5, and 6 within the logic flow.
start/end
The start and end parameters define the time range the API is referring to. The API runs the instance over the time range specified here, where “start” is the beginning of the range, and “end” is the end of it. The date range is formatted as year-month-day hour:minute:second
Example: 2014-01-01T00:00:00 The above example refers to April 1st, 2014 at midnight.
interval
The interval refers to the aggregating interval for the logic blocks using this parameter. Your interval could be daily, weekly, monthly, or yearly. But, you will not be able to overwrite the aggregating interval of a logic block if this block has a constant aggregating interval. You will be able to define this interval only if the logic block is set up to request under the aggregating field.
To avoid confusion, be sure all the final aggregation intervals in the logic flow are the same. Otherwise, if one aggregation series is set to custom – hourly, and the other to request, both values will only have the same timestamps if this “interval” parameter is set to hourly. Even if the interval is set to weekly, the hourly value will still pull every hour.
format
The Kaizen API provides three formats for you output.
- enteliVIZ
- Logi
- Xml
Examples:
| Enteleviz |
|---|
| [ { “Timestamp”: “2014-03-01T00:00:00”, “Value3”: 31.3427734375, “Value2”: 111.7119140625, “Value1”: 0 },] |
| Logi |
|---|
| [ { “Timestamp”: “2014-03-01T00:00:00”, “DataSeriesId_13”: 0, “DataSeriesId_14”: 111.7119140625, “DataSeriesId_15”: 31.3427734375 }, ] |
| Xml |
|---|
| <DocumentElement> <values> <Timestamp>2014-03-01 00:00:00</Timestamp> 0.0 111.71 31.34 </values> </DocumentElement> |
The Enteleviz format returns the data as a JSON array, displaying data in the same order the series were entered into the series_ids parameter. The Logi format returns the data as a JSON array, displaying the data according to the numerical series ids entered into the series_ids parameter. The XML format returns the data in Extensible Markup Language (XML) format, displaying data in the same order the series were entered into the series_ids parameter.
