Room Occupancy

Room occupancy refers to the number of people detected in a specific room at a given time. There are two ways to measure room occupancy: traffic-based or presence-based. Each method uses a different approach depending on the available sensor data and the type of insights required.

Below are sample queries for retrieving room-level occupancy data to analyze peak, and average within a selected time range.

Traffic-based Room Occupancy

If traffic sensors are installed at the room entrance(s), you can use the sample queries below to retrieve the estimated room occupancy counts.

Query the peak hourly occupancy of a room with traffic sensor installed:

Use measurement: traffic_room_occupancy

Use function: max

Use "calibrated": "true"

Request
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max",
        "timezone": "Europe/Amsterdam" 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic_room_occupancy"],
        "calibrated": "true",
        "rooms": {
            "eq": ["room_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}

Response
// POST https://api.butlr.io/api/v3/reporting
{
    "data": {
        "2024-01-01T04:00:00Z": {
           "sum": 18,
           "min": 1,
           "max": 2,//peak
	   "count": 10,
       	   "mean": 1.8, 
	   "median": 2,
	   "stddev": 0.4000000000000001,
	   "first": 1,
	   "last": 2
        }
    }
} 

Query the average hourly occupancy of a room with traffic sensor installed:

Use measurement: traffic_room_occupancy

Use function: mean

Use "calibrated": "true"

Request
{
    "window": {
        "every": "1h",
        "function": "mean",
        "timezone": "Europe/Amsterdam" 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",//start of the day
        "stop": "2024-01-02T04:00:00Z",//current time
        "measurements": ["traffic_room_occupancy"],
        "calibrated": "true",
        "rooms": {
            "eq": ["room_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}
Response
{
    "data": {
        "2024-01-01T04:00:00Z": {
           "sum": 18,
           "min": 1,
           "max": 2,
           "count": 10,
           "mean": 1.8, //average
           "median": 2,
           "stddev": 0.4000000000000001,
           "first": 1,
           "last": 2
        }
    }
} 


Presence-based Room Occupancy

Use the sample queries below to retrieve the total occupancy for areas covered by presence sensors in the room. Keep in mind that the sensor coverage area influences the count and may not represent the room's actual occupancy.

Query the peak hourly occupancy of a room with presence sensors installed:

Use measurement: room_occupancy

Use function: max

Request
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max",
        "timezone": "Europe/Amsterdam"
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["room_occupancy"],
        "rooms": {
            "eq": ["room_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}

Response
// POST https://api.butlr.io/api/v3/reporting
{
 "data": {
     "2024-01-01T04:00:00Z": {
        "sum": 63,
        "min": 3,
        "max": 10,
        "count": 9,
        "mean": 7,//mean
        "median": 7,
        "stddev": 1.8856180831641267,
        "first": 3,
        "last": 6
     }
  }
}

Query the average hourly occupancy of a room with presence sensors installed:

Use measurement: room_occupancy

Use function: mean

Request
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "mean",
        "timezone": "Europe/Amsterdam"
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["room_occupancy"],
        "rooms": {
            "eq": ["room_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}
Response
// POST https://api.butlr.io/api/v3/reporting
{
    "data": {
	"2024-01-01T04:00:00Z": {
	  "sum": 63,
	  "min": 3,
	  "max": 10,
	  "count": 9,
	  "mean": 7,//mean
	  "median": 7,
	  "stddev": 1.8856180831641267,
	  "first": 3,
	  "last": 6
        }
    }
}

Last updated