Get Area Occupancy

The sensors capture and stream occupancy data to Manage. The Get Area Occupancy API returns the current occupancy status of the area. The occupancy status is provided only when the sensors are enabled as zone sensors to report occupancy data. Refer to the article Enable Zonal Sensors.

For the sensors to start reporting occupancy data to Manage, you will need licenses based on the number of sensors and areas configured in the system. You will need the IoT sensor license and Real-time Area Occupancy API license (API-RTO-AREA) to get occupancy for an area. 

After you have purchased and uploaded the API License file in Manage, enable the sensors in the area as zone sensors before using the API to report area occupancy status. 

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/area/v1/occ/{area_id}

Parameters

Request 
em_ip_address or hostname   Manage’s IP address or hostname
area_id Area Identifier. Use the Get all Areas API, or in Manage, select Facility > Floor > Area in the left panel, and click the Settings tab to get the Area ID.
Response 
occupancyState 0 – Area unoccupied
1 – Area occupied
-1 – Sensors are not reporting occupancy
-2 – Zone sensor license is not available. Sensors monitoring the occupancy status of the zone are disabled.
-3 – Unknown area

Sample Code

Let's assume that the floor has two areas: The Hardware area with ID ‘9’ and the Software area with ID ‘27’. To find out the area occupancy in the Hardware area, specify Area ID ‘9’ in the API command. The API call returned the occupancy state '0' for the Hardware area. The occupancy state '0' represents the area is unoccupied.

Get https://192.80.3.2/ems/api/org/area/v1/occ/9

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT
{
  “occupancyStatus”:
    {"occupancyState": "0"}
}

Get Area Occupancy for a Floor

The Get Area Occupancy for a Floor returns the current occupancy status of all areas on a floor. The occupancy status is provided only when the area sensors are enabled as zone sensors to report occupancy data.

You will need the IoT sensor license and additional Real-time Area Occupancy (API-RTO-AREA) license to get occupancy for a floor or area. Read Request License to purchase licenses as needed.

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/facility/v1/getOccupancyStateOfFloorAreas/
{floor_id}

Parameters

Request 

em_ip_address or hostname Manage’s IP address or hostname
floor_id Floor identifier. Use the Floor ID returned in the Get All Floors API, or in Manage, select Facility > Floor > in the left panel, and click the Settings tab to obtain the Floor ID.
Response 
Id Area identifier
name Area name as described in Manage
description Area description as described in Manage. The field will be empty if there is no description entered in Manage.
zonesensorenable

The area has been activated as a zone sensor area. The area starts reporting consolidated occupancy status. Note that the zone sensor license must be purchased and available for the sensors to report occupancy information. Otherwise, occupancy data is not reported by the sensors.

true – Sensors in the area are enabled as zone sensors.
false – Sensors in the area are disabled as zone sensors.

occupancyState

0 – Area unoccupied
1 – Area occupied
-1 – Fault. Sensors are not reporting occupancy.

Note: For this API, you will always get an additional area. Its ID field will ALWAYS be "0". Its name will always be "Unassigned". The value of occupancyState will be "1" if ANY sensor on that floor is NOT in an area, but its current state is "occupied". If all such sensors are "vacant", then this value will be "0".  

Sample Code

Send a request to return the occupancy state for all areas on Floor 1. For example, Floor 1 in the Main building has two areas: Hardware and Software. The details of the areas and their corresponding Area IDs and occupancy state for all areas on Floor 1 are returned.

Get https://{192.80.3.2}/ems/api/org/facility/v1/getOccupancyStateOfFloorAreas/1

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/JSON
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT
{
  "id": "9",  ** Area ID**
  "name": "Hardware",
  "description": "hw eng",
  "zonesensorenable": "true"
  “occupancyState”: “1”,
},
{
  "id": "27", **Area ID**
  "name": "Software",
  "description": "sw eng",
  "zonesensorenable": "false",
  “occupancyState”: “1”,
},
{

"id": "0", **Area ID**
  "name": "Unassigned",
  "description": "Unassigned area",
  “occupancyState”: “1”,
}

Recommended articles:

Get Real-time Desk Occupancy for a Floor

This API returns the desk occupancy for all desk sensors on a floor.

You will need the IoT sensor license and Real-time Desk Occupancy API License (API-RTO-DSK) to get real-time desk occupancy for a floor. Read Request License to purchase licenses if you have not, and assign 'Desk Sensor' Fixture Type to sensors before using this API call. Refer to the article Enable Desk Sensors that describes how to assign 'Desk Sensor' Fixture Type to sensors. 

Request

GET https://{em_ip_address_or_hostname}/ems/api/org/sensor/v1/getDeskOccupancyState/list/floor/{floor_id}

Parameters

Request 

em_ip_address or hostname

Manage’s IP address or hostname

floor_id

Floor identifier. Use the Floor ID returned in the Get All Floors API, or in Manage, select Facility > Floor in the left panel, and click the Settings tab to see the Floor ID.

Response 

id

The fixture or sensor identifier. 

name

Sensor name.

occupancyState

0 – Desk Unoccupied

1 – Desk Occupied

-1 – Fault. Sensors are not reporting occupancy

 

Sample Code

For example, if Floor 1 has three desk sensors, send a request to return the Desk occupancy for all desk sensors on the floor. The occupancy status for all desk sensors on Floor 1 is returned.

Get https://192.80.3.1/ems/api/org/sensor/v1/getDeskOccupancyState/list/floor/1

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/xml
Content-Length: 7582
Date: Sat, 21 Jul 2015 17:06:51 GMT
{
    "deskSensor": [
        {
            "id": "70",
            "name": "Sensor71bd6a",
            "occupancyState": "0"
        },
        {
            "id": "71",
            "name": "Sensor71af2a",
            "occupancyState": "0"
        },
        {
            "id": "72",
            "name": "Sensor71b13e",
            "occupancyState": "1"
        }
    ]
}

Get Detailed Fine-Grain Sensor Data

Get Detailed Fine-grain Sensor Data API

Returns sensor data for all sensors on a particular floor every five minutes for the specified time period. The data is returned every five minutes between the given time period. For example, for the interval from 10:00 (hh:mm) to 10:10 (hh:mm), the data is returned every five minutes, which will be 10:05 and 10:10. The time range can span a maximum of one hour for a given API call.

You will need the IoT sensor software license and Fine-grain Motion API License (API-MB-SU) to get fine-grain sensor data. Read Request License to purchase licenses if you have not, and make sure to enable sensors to provide motion-bit data via API. 

GET https://{em_ip_address_or_hostname}/ems/api/org/sensor/stats/floor/{floor_id}/{from date}/{to date}

Parameters

Request
em_ip_address or hostname Manage IP address or hostname
floor_id A unique identifier for the floor (returned in Get All Floors API)
from_date Display energy consumption data for the start time period  
Format: (yyyyMMddHHmm) year/month/day/hour/minutes
to_date Display energy consumption data for the end time period  
Format: (yyyyMMddHHmm) year/month/day/hour/minutes
Response
id A unique identifier for the fixture
power The average load of the fixture in watts during the last five-minute interval
occupancy The value is in decimal format and needs to be converted to binary format. The binary is 64-bit integer value with each bit corresponding to 5 sec. in the last 5-minute interval. Out of 64 bits, the first four most significant bits are not used. The remaining subsequent 60 bits represent the recent 5 sec. periods.  
For example, the value in decimal 1152860189653680128 converted into a binary would be 00001111 1111111111001000 00111011 11111111 11111111 01000000 00000000. The first 4 bits (0000) are not used. The remaining string of subsequent 60 bits represents the occupied state for a five-minute interval, with each bit representing the recent five-second period.
1: Occupied
0: Unoccupied
temperature Temperature in Fahrenheit
captureTime Five-minute time duration (YYYY-MM-dd hh:mm) year/month/day/hour/minutes

Sample Code

The example below shows getting data from Floor 2 from 10 hours 05 minutes to 10 hours 10 minutes. The API returns fine-grain data such as the Fixture ID, power in watts, occupancy status, temperature, time from all the sensors on Floor 2 for the specified duration, returning data at a 5-minute interval.

GET https://192.80.3.2/ems/api/org/sensor/stats/floor/2/202009281300/202009281400
HTTP/1.1 200 OK

Server: Apache-Coyote/1.1 Content-Type: application/xml Content-Length: 7582
Date: Sat, 25 Feb 2012 17:06:51 GMT
}{
  "sensor": [
    {
      "id": "1327",
      "power": "27.98",
      "occupancy": "216185976353980608",
      "temperature": "78",
     "captureTime": "2021-09-28 13:00"
    },
    {
      "id": "1377",
      "power": "12.62",
      "occupancy": "1705651772329615",
      "temperature": "74",
     "captureTime": "2021-09-28 13:00"
    },
    {
      "id": "367",
      "power": "70.81",
      "occupancy": "188658598246027468",
      "temperature": "70",
    "captureTime": "2021-09-28 13:00"
    },  
    {
      "id": "354",
      "power": "69.10",
      "occupancy": "1024568984031723712",
      "temperature": "74",
     "captureTime": "2021-09-28 13:00"
    },
    {
      "id": "483",
      "power": "68.12",
      "occupancy": "1148417902826749951",
      "temperature": "72",
     "captureTime": "2021-09-28 13:00"
    }
    …..
    …..
    …..
  ]
}