Butlr Developer Docs
  • Welcome
  • What is Butlr
  • Spatial Metrics
  • Getting Started
    • Authentication
    • Making your first query
    • Mint Client Credentials
  • Changelog
  • Asset Management
    • GraphQL API Overview
      • Sites
      • Buildings
      • Floors
      • Rooms
      • Zones
      • Hives
      • Sensors
      • Asset Tags
    • GraphQL API Introsepction
  • Historical Occupancy
    • Reporting API Overview
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Query Occupancy by Tag
      • Traffic
      • Presence Time
      • Statistic Overview
    • FAQs
  • Real-time occupancy
    • Webhooks Overview
      • Area Detections
      • Entryway Traffic
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Motion Detection
      • No Motion Detection
    • Manage Webhooks
      • Create Webhooks
      • Update Webhooks
      • Delete Webhooks
      • List Webhooks
  • LINKS
    • Butlr Postman Collection
    • Butlr Website
    • Status
    • Support
    • Log In
Powered by GitBook
On this page
  • Traffic-based Floor Occupancy
  • Presence-based Floor Occupancy
  1. Historical Occupancy
  2. Reporting API Overview

Floor Occupancy

PreviousReporting API OverviewNextRoom Occupancy

Last updated 1 month ago

Floor occupancy refers to the number of people detected on a specific at a given time. There are two ways to measure floor occupancy: or . 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.

Recommended Practices

  1. Recommended Aggregation by Query Interval: To ensure accurate interpretation of occupancy data, we recommend different aggregation methods based on the query interval:

    1. 1-Minute Interval (we recommend query for <24h time ranges only due to performance)

      Use median : this smooths out short-term fluctuations (e.g. quick in-and-outs) and best reflects actual occupancy minute-to-minute.

    2. Larger Intervals (e.g. hourly, daily)

      1. Use mean for average occupancy over the interval to help identify overall usage patterns.

      2. Use max for peak occupancy within the interval to understand the busiest times or capacity thresholds.

  2. Avoid Relative Time Queries: Do not use relative time functionality (e.g., -5m) as it may result in missing data depending on query timing. Always specify absolute start and stop times.

  3. Timezone Configuration: Always provide a timezone when querying traffic-based occupancy

  4. To mitigate traffic drift due to miscounts, we recommend adding the filter: "calibrated": "true"

  5. Include Zero Values in Output: To ensure zero values are included in the results, add the filter:

    "filter": { "value": { "gte": 0 } }

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.

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
  }
}

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
     }
  }
}

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

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

traffic
traffic
floor
traffic-based
presence-based