Presence Time

Presence time refers to the total duration (in seconds) that people were detected within an area during a specified time range. This metric is derived from presence sensor data and provides valuable insights into how long spaces are occupied and used.

Below are guidelines for retrieving and analyzing presence time data for total duration within a selected time range.

Recommended Practices

1. Function Selection for Presence Time Metrics:

   • Use the sum function to capture total utilization within the specified time window.

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. Include Zero Values in Output: To ensure zero values are included in the results, add the filter:

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

NOTE: Presence time data is available starting from November 12, 2024. This data is only available for spaces with presence mode sensors installed.

Below are sample queries for retrieving presence time data for floors, rooms, or zones. These queries allow you to analyze the total duration within a specified time range.

Presence time

Floor Presence Time (Seconds)

Use the sample query below to retrieve the total presence time (in seconds) for areas covered by presence sensors on the floor. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire floor.

Query the total hourly presence time (seconds) of a floor with presence sensors installed:

Use measurement: floor_presence_time_secs

Use function: sum

Request

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

Response

// POST https://api.butlr.io/api/v3/reporting
{
  "data": {
      "2024-01-01T04:00:00Z": {
            "sum": 213,
            "min": 213,
            "max": 213,
            "count": 1,
            "mean": 213,
            "median": 213,
            "stddev": 0,
            "first": 213,
            "last": 213
        }
   }
}

Room Presence Time (Seconds)

Use the sample queries below to retrieve the total presence time (in seconds) for areas covered by presence sensors in the room. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire room.

Query the total hourly presence time (seconds) of a room with presence sensors installed:

Use measurement: room_presence_time_secs

Use function: sum

Request

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

Response

// POST https://api.butlr.io/api/v3/reporting
{
    "data": {
	"2024-01-01T04:00:00Z": {
            "sum": 12,
            "min": 12,
            "max": 12,
            "count": 1,
            "mean": 12,
            "median": 12,
            "stddev": 0,
            "first": 12,
            "last": 12
        }
    }
}

Zone Presence Time (Seconds)

Use the sample queries below to retrieve the total presence time (in seconds) for areas covered by presence sensors in the zone. Keep in mind that the sensor coverage area influences the measurement and may not represent the actual time spent across the entire zone.

Query the total hourly presence time (seconds) of a zone with presence sensors installed:

Use measurement: zone_presence_time_secs

Use function: sum

Request

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

Response

// Some code// POST https://api.butlr.io/api/v3/reporting
{
   "data": {
	"2024-01-01T04:00:00Z": {
            "sum": 3,
            "min": 3,
            "max": 3,
            "count": 1,
            "mean": 3,
            "median": 3,
            "stddev": 0,
            "first": 3,
            "last": 3
        }
   }
}