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
  • 1. Traffic Mode
  • How It Works
  • Use Cases
  • Limitations
  • Available Metrics for Traffic Mode
  • 2. Presence Mode
  • How It Works
  • Use Cases
  • Limitations
  • Available Metrics for Presence Mode

Spatial Metrics

PreviousWhat is ButlrNextGetting Started

Last updated 2 months ago

Spatial metrics provide insights into how people interact with and move through physical spaces. This includes occupancy, movement trends, and potentially human behavior-related metrics. These metrics can be aggregated over various periods and filtered by , , or to offer actionable insights. The availability of metrics for a given space depends on the sensor mode deployed in that area.

1. Traffic Mode

Traffic Mode provides aggregated totals of ‘in’ and ‘out’ movements based on a sensor’s orientation, a user-defined door line, and the direction of entry. For optimal performance, sensors should be mounted above entrances using either a Wall Mount or Ceiling Mount. Occupancy is calculated based on the flow of people in and out.

How It Works

  • Tracks the number of people entering (Ins) and exiting (Outs) a space.

  • Data can be aggregated or filtered by floors, rooms, or zones for tailored insights.

  • Resets occupancy counts to zero daily at midnight, based on the site’s time zone, to prevent drift caused by missed entries or exits.

Use Cases

  • Workplace: Track entries and exits in lobbies, cafeterias, floors, or large spaces like conference rooms and auditoriums.

  • Senior Living: Monitor overall site activity at main entrances.

  • Retail: Measure customer flow at store or mall entrances and across floors.

Limitations

  • Does not capture real-time activity across all areas of a space.

  • Missing entries or exits can lead to inaccuracies (drift) over time.

Available Metrics for Traffic Mode

Traffic Count (Ins/Outs): Tracks the number of people entering and exiting at the floor or individual room level.

Ways to access the traffic data:

Traffic-Based Occupancy: Estimates occupancy at the floor, room, or zone level by aggregating entry and exit data. This provides a high-level occupancy estimate but may not capture detailed floor usage.

Ways to access the traffic-based occupancy data:

  • Real-time updates are not yet available via webhook subscription.


2. Presence Mode

Presence Mode provides the number and coordinates of individuals within its coverage area. For best results, sensors should be mounted in open areas and meeting rooms using a Ceiling Mount. Occupancy is determined based on real-time detections.

How It Works

  • Detects activity within a defined coverage area, providing granular insights into movement patterns and usage.

  • Offers precise occupancy data for specific zones.

Use Cases

  • Workplace: Monitor occupancy in meeting rooms, offices, workstations, or hot desking zones in open work areas.

  • Senior Living: Track activity in resident apartments to detect risks such as falls or prolonged inactivity.

  • Retail: Analyze customer engagement at product displays or checkout counters.

Limitations

  • Only detects individuals within the sensor’s defined coverage area, potentially undercounting those outside this range.

  • Counts may fluctuate slightly when individuals move between sensors in quick succession.

Available Metrics for Presence Mode

Presence-Based Occupancy: Occupancy counts at floor, room, or zone levels based on presence sensor detections.

Ways to access the presence-based occupancy data:

Detection Coordinates: the coordinates of person detected within the sensor’s coverage area.

Ways to access the detection coordinates data:


Why do Traffic and Presence Counts Differ on the Same Floor?

  1. Limited Coverage by Presence Sensors: When presence sensors cover only a small portion of the floor (e.g., 20%), they count only individuals within their coverage area. In contrast, traffic sensors track all entries and exits at the floor's main entrances, resulting in higher traffic counts compared to presence-based occupancy.

  2. High Coverage Floors: On floors with 90% or greater area coverage by presence sensors, the counts from traffic and presence metrics tend to align more closely. However, discrepancies can still occur due to:

    • Movement Between Coverage Areas: Minor fluctuations caused by people moving between areas covered by presence sensors

    • Missed Traffic Events: Inaccuracies caused by traffic sensors occasionally failing to detect entries or exits.

  3. Drift in Traffic Counts: Traffic-based counts can drift over time due to missed entries or exits, leading to compounding inaccuracies. To address this, traffic counts are reset to zero daily at midnight, ensuring consistency for the next day.

Query the 's measurement for traffic data.

Subscribe to the for real-time entry and exit count updates.

Query the 's or measurement for traffic-based occupancy data.

Query the 's , , or measurement for presence-based occupancy data.

Subscribe to the , , or for real-time occupancy count updates.

Subscribe to the for real-time coordinates updates.

Reporting API
traffic
traffic webhook
floor occupancy
room occupancy
zone occupancy webhooks
detections webhook
floors
rooms
zones
Reporting API
Reporting API
traffic_room_occupancy
room_occupancy
traffic_floor_occupancy
floor_occupancy
zone_occupancy