Floor Occupancy

Introduction

Floor occupancy refers to the measure of how many individuals are present in a given floor at a particular time. The floor_occupancy metric is a post-calculation derived from consolidating data from multiple presence sensors. It involves collecting information from each sensor, such as the number of people detected within their respective areas, and aggregating the data to determine the total occupancy of the floor. It's important to note that traffic sensors, which measure the flow of individuals entering and exiting a floor, are not included in the floor_occupancy calculation.

1 - Get Access Token

2 - Query occupancy for floor occupancy

Warning: When using the /reporting API, it's important to be cautious with the choice of windowing functions and window sizes. While the API offers several options such as min, max, and mean, we strongly recommend using a window size of 5m (5 minutes) with either max or mean functions. Using a window size that is too large, such as 1d (1 day), with a function like max, can lead to misleading results. In such cases, you will only receive a single point in time, rather than a comprehensive view of utilization throughout the day. To accurately monitor and analyze floor occupancy trends and patterns, it's crucial to select an appropriate window size that captures an adequate time interval. A smaller window size allows for more granular data, enabling a better understanding of how occupancy fluctuates over shorter periods. By choosing the appropriate window size and function, you can obtain meaningful insights into floor utilization and make informed decisions about space management, resource allocation, and other relevant considerations. Take care to adjust the window parameters according to your specific requirements, ensuring that the selected configuration aligns with your desired level of detail and analysis granularity.

curl --location --request POST 'https://api.butlr.io/api/v3/reporting' \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "window": {
        "every": "5m",
        "function": "max"
    },
    "filter": {
        "start": "-3h",
        "stop": "-1m",
        "measurements": ["floor_occupancy"]
    }
}'

Response

{
    "data": [{
            "field": "floor_occupancy",
            "measurement": "floor_occupancy",
            "time": "2023-05-17T16:41:01Z",
            "start": "2023-05-17T13:41:01Z",
            "stop": "2023-05-17T16:41:01Z",
            "value": 2,
            "timezone_offset": "",
            "building_id": "",
            "building_name": "",
            "hive_id": "",
            "hive_serial": "",
            "sensor_id": "",
            "space_id": "space_2Iy2j2DOmx",
            "space_name": "First Floor",
            "room_id": "",
            "room_name": "",
            "zone_id": "",
            "zone_name": "",
            "mac_address": ""
        },
        {
            "field": "floor_occupancy",
            "measurement": "floor_occupancy",
            "time": "2023-05-17T13:45:00Z",
            "start": "2023-05-17T13:41:01Z",
            "stop": "2023-05-17T16:41:01Z",
            "value": 2,
            "timezone_offset": "",
            "building_id": "",
            "building_name": "",
            "hive_id": "",
            "hive_serial": "",
            "sensor_id": "",
            "space_id": "space_2Iy2j2DOmx",
            "space_name": "First Floor",
            "room_id": "",
            "room_name": "",
            "zone_id": "",
            "zone_name": "",
            "mac_address": ""
        }
    ]
}

Closing Remarks

This example illustrates a basic method of extracting floor occupancy information. The response includes additional fields such as "mac_address" and "zone_id," but it's important to note that these fields will not be populated in this particular scenario. Regardless of the metric being queried, the response object remains the same. This example serves as a starting point for understanding how floor occupancy can be derived by consolidating data from presence sensors. Real-world implementations may involve more complex systems and considerations, such as integrating multiple sensor types, accounting for traffic patterns, and incorporating additional metadata. By customizing and expanding upon this basic example, organizations can develop comprehensive occupancy monitoring systems that cater to their specific needs, whether it be for optimizing space utilization, enhancing security measures, or improving resource allocation. It's essential to adapt this example to the particular context and requirements of your application, taking into account factors like sensor placement, data integration, and any additional functionalities needed to achieve accurate and meaningful floor occupancy insights. If you have any questions, please reach out to us at support@butlr.io.