Floor Occupancy

Floor occupancy refers to the number of people detected on a specific floor at a given time. There are two ways to measure floor 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 floor-level occupancy data to analyze peak, and average within a selected time range.

Traffic-based Floor Occupancy

If traffic sensors are installed at the floor entrances, you can use the sample queries below to retrieve the estimated floor occupancy counts. This measurement aggregates the counts from all main-entrance traffic sensors on the floor.

Query the peak hourly occupancy of a floor with main entrance(s) traffic sensor installed:

Use measurement: traffic_floor_occupancy

Use the function: max

Use "calibrated": "true"

Request
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max",
        "timezone": "America/New_York"  //replace with your timezone
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic_floor_occupancy"],
        "calibrated": "true",
        "spaces": {
            "eq": ["space_2qfewAEoTVaIWQaOY0WZlD729pr"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}

Response
{
    "data": {
        // timestamp
        "2024-01-01T04:00:00Z": {
            "sum": 15204,
            "min": 9,
            "max": 2363,//peak
            "count": 17,
            "mean": 894.3529411764706,
            "median": 1373,
            "stddev": 727.0197781253734,
            "first": 9,
            "last": 408
    }
    // ... more data
  }
}

Query the average hourly occupancy of a floor with main entrance(s) traffic sensor installed:

Use measurement: traffic_floor_occupancy

Use function: mean

Use "calibrated": "true"

Request
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "mean",
        "timezone": "America/New_York"  //replace with your timezone 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic_floor_occupancy"],
        "calibrated": "true",
        "spaces": {
            "eq": ["space_2qfewAEoTVaIWQaOY0WZlD729pr"]
        }
    },
    "group_by": {
      "order": ["time"]
    }
}
Response
{
    "data": {
        "2024-01-01T04:00:00Z": {
            "sum": 15204,
            "min": 9,
            "max": 2363,
            "count": 17,
            "mean": 894.3529411764706, //Average
            "median": 1373,
            "stddev": 727.0197781253734,
            "first": 9,
            "last": 408
     }
    // ... more data
  }
}

Presence-based Floor Occupancy

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

Query the peak or average hourly occupancy of a floor with presence sensors installed:

Use measurement: floor_occupancy

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": ["floor_occupancy"],
        "spaces": {
            "eq": ["space_2qfew8mjwwek7JwLY1zS9cgyPo6"]
        }
    },
    "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,//peak
	 "count": 9,
	 "mean": 7,
	 "median": 7,
	 "stddev": 1.8856180831641267,
	 "first": 3,
	 "last": 6
       }
   }
}

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

Use measurement: floor_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": ["floor_occupancy"],
        "spaces": {
            "eq": ["space_2qfew8mjwwek7JwLY1zS9cgyPo6"]
        }
    },
    "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, //average
	"median": 7,
	"stddev": 1.8856180831641267,
	"first": 3,
	"last": 6
     }
  }
}

Last updated