Guide to API

1.0 What is an API

API stands for Application Programming Interface that can be used to access the data and features of other applications, services, or operating systems. This is a set of functions and procedures that allow for the 3rd party integration of applications.

The API provides access to data, so this data can be included in different applications. Instead of attempting to format a big file in a local application to extract a little bit of data, an API delivers the data you’re looking for.

APIs are reusable and can be infinitely remodeled to create new apps and services and they provide key insights into real-time possibilities for analytics delivery on the spot. Organic Response offers its API i.e. RESTful API based upon OR cloud-based Portal.

2.0 Authentication (or) Initial Setup

In OR API an authentication token is required to make API calls. To get an API token for your connected building please create a service desk request using this link Service Desk Customer Portal.

2.1. Authorisation Types

An API token can be used to authorise individually based upon the following parameters,

1. (By Default) For an entire building

2. To authorise for individual tenants within a building (click here to read more on tenants)

3. Token can be bound to one or a list of IP addresses with or without being assigned to tenants

Kindly share your project needs for a or multiple tokens to be generated with relevant authorisation needs through service desk. If no restrictions are shared the token will automatically assume the 1st option i.e. authenticated for the whole building. The token can then be used to generate JWT token with daily expiry to ensure further security.

2.2. When you have the Token

Once you receive the token you can use any third-party or your personalized custom API platform to access information or execute control commands.

Once you download any API platform you will be able to retrieve a range of data, implement lighting control commands, and a few other parameters available in the portal using the token you received from ORT. Such API platforms can serve as test platforms to help you set up for full API integration. It is always recommended to engage API developers at an early stage of the design and integration process for your customized API integration works according to your project requirements.

Please refer to this document to find all the different request types, resources, and associated parameters to retrieve the information you need http://or-cloud-api-docs.s3-website-ap-southeast-2.amazonaws.com/#tag-liveanalytics.

The Organic Response Portal is a sophisticated, standalone lighting control & analytics platform that captures data stored by the OR Portal and can be presented in 3rd party applications. The Portal is an AWS cloud-hosted platform that provides insights into building operations and occupancy. OR API utilizes the portal and hence requires the project to be a portal-connected installation.

Organic Response API is RESTful API and uses JavaScript Object Notation (JSON) to represent the structured data for interaction. OR cloud API can offer a detailed and secured system integrations option. For example, OR API enables,

• BMS integration with other systems

• 3rd party data analytics platform

• Building Specific smartphone applications

3.1 Building Resource or Primary data blocks

The building resources or primary data blocks include,

1. Building Information (Building name, location, etc.)

2. Floors

3. Tags

4. Sensor Nodes

3.1.1 Building Information

You can retrieve the following building-related information by sending the relevant requests from any 3rd party API platform by using the Organic Response API endpoint. Upon querying the building resource, it can provide you with valuable information from portal implementation such as,

Open

1. Building ID (This is generated by the Portal automatically once at the time of building creation)

2. Project / Building Name

3. Address of the building

4. Time zone of the building

5. Image of the building

6. Associated/ available API links to perform the following;

   1. Query the building information

   2. Get the thumbnail of the building photo as visible on the portal summary page

7. “List of Floors including the following information

   1. id” i.e. Floor IDs (This is generated by the portal automatically at the time of creating floors)

   2. “floorNumber” : Floor number identifier (usually represent sequence in which the floors are added in the building unless customized)

   3. “name” : Name assigned to the floor

   4. Floor plan (image of the floor as uploaded to the portal)

   5. Associated/ available API links to perform the following;

      1. Individually query the floor information

      2. Get the floor plan

8. List of the building's tags with information including

   1. “id” of the Tag

   2. “name” of the tag

   3. “colour” of the tag

   4. API links to Individually query the tag information

If you are testing using third party application you can quickly access the building ID and the floor ID found in the URL once you log in to the portal building. This is so that you can avoid performing all resource queries,

1. The building ID

2. Floor ID

Open

3.1.2 Floors

By sending the relevant request to access data related to the floor, you will have the below information included in the response,

1. Floor id (Portal generated)

2. Floor number

3. Name of the floor

4. Floor plan (image of the floor)

5. Associated/ available API links to perform the following;

   1. Individually query the floor information

   2. Get the floor plan

   3. Query the analytics data

   4. Implement a lighting control

6. List of sensor nodes installed on the floor which includes the following information;

   1. “id”: Sensor Node Portal ID

   2. “address”: Sensor nodes address (physical address)

   3. x & y coordinates on a floorplan

   4. API link to query the sensor node individually.

3.1.3 Tags

Tags are created in the portal to associate sensor nodes with an area. Once set up in the portal, you can request to access information related to each tag. When you perform a tag-based query by specifying the tag ID which was included in the response to the building query,

1. “id”: Sensor Node Portal ID

2. “name”: Name of the tag

3. “color”

4. Associated/ available API links to perform the following;

   1. Individually query the tag information

   2. Query the analytics data

   3. Implement a lighting control

5. List of sensor nodes with the tag which includes the following information ;

   1. “id” = Sensor Node Portal ID

   2. “address” = Sensor nodes address

   3. x & y coordinate on a floorplan

   4. API link to query the sensor node individually

3.1.4 Sensor Nodes

By sending the API request for any selected node in the building you will find the following information in the response

1. “id” : Sensor Node Portal ID

2. “address” : Sensor nodes address

3. x & y coordinate on a floorplan

4. Associated/ available API links to perform the following;

   1. Query the sensor node individually

   2. Query the analytics data

   3. Implement a lighting control

3.2 The operations

The operations which are available for the above resources include

1. Live Analytics (per node / aggregated)

2. Lighting Control

3. Analytics

3.2.1 Live Analytics

With the organic response API cloud, you can call for live analytics which could provide you data either by an aggregated query option or by an individual node option. Currently, you can get the status queries such as Auto,

3.2.2 Lighting Control

The following Lighting control can be implemented for individual nodes, individual floors, or for the whole building

• Dimming commands based on their dimming percentage

• Any scene ( scene 1-7)

• Reverting to the auto mode

3.2.3 Analytics

The analytics information of a building that is available in live and historical data can be retrieved by performing relevant API calls. The presence data can be requested by the month, week, day, and hour up to each 5-minute window. This information can be further filtered for a particular floor, a sensor node, or a tag by specifying the relevant ID of the resource,

The response will have the following information;

3.3 Status

Individual node status can be queried. The following information can be found in the response to a successful query;

• The fault state - Emergency inverter faults only

• The current dimming level

• The current scene