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 |
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. |
| occupancyState |
0 – Area unoccupied |
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 |
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 |
Get Detailed Fine-Grain Sensor Data
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 bits 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. If you prefer to verify a binary integer and if its value is less than 64 bits then add the required number of 0's to the start of the string. For example, the binary quivalent of the decimal value 422212465065984 would be 11000000 00000000 00000000 00000000 00000000 00000000 0. To make the string to 64 bits, add the required number of zeros 00000000 00000001 10000000 00000000 00000000 00000000 00000000 00000000. |
| 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": "1152860189653680128",
"temperature": "78",
"captureTime": "2021-09-28 13:00"
},
{
"id": "1377",
"power": "12.62",
"occupancy": "422212465065984",
"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"
}
…..
…..
…..
]
}