Query Occupancy by Tag

Tag Occupancy provides the total number of people across all tagged rooms or zones at a specific time. For instance, you can assign tags to these spaces if you want to track activity in meeting rooms, cafeterias, or lounge areas. This lets you filter or aggregate data by tag, helping uncover valuable insights about how these areas are used.

Note: Only data from presence-based rooms and zones is available via Tag Occupancy.

Tag Filtering

To filter occupancy by tag, include a list of tags in your query. This will allow you to retrieve only the floors, rooms, or zones associated with the specified tags.

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"],
        "tags": {
            "eq": ["tag_2qfewAEoTVaIWQaOY0WZlD729pr"] // This tag expands to a set of room_ids
        }
    },
    "group_by": {
      // Group results by room_id and then by time.
      "order": ["room_id", "time"]
    }
}

Response

{
    "data": {
        "room_2qfewEA4ZmpIxwAan4FeQADOvb7": {
            "2024-01-01T04:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            },
            "2024-01-01T05:00:00Z": {
                "sum": 3,
                "min": 3,
                "max": 3,
                "count": 1,
                "mean": 3,
                "median": 3,
                "stddev": 0,
                "first": 3,
                "last": 3
            },
            "2024-01-01T06:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            },
            "2024-01-01T07:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            },
            "2024-01-01T08:00:00Z": {
                "sum": 1,
                "min": 1,
                "max": 1,
                "count": 1,
                "mean": 1,
                "median": 1,
                "stddev": 0,
                "first": 1,
                "last": 1
            },
            "2024-01-01T09:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            },
            "2024-01-01T10:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            }
        }
    }
}

Tag Aggregation

To query data across multiple rooms and zones, aggregated by tag, you can use the tag_occupancymeasurement. This can provide peak occupancy data across all associated rooms and zones. It is highly recommended to group this data by tag_id.

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": ["tag_occupancy"],
        "tags": {
            "eq": ["tag_2qfewAEoTVaIWQaOY0WZlD729pr"]
        }
    },
    "group_by": {
      // Group results by tag_id and then by time.
      "order": ["tag_id", "time"]
    }
}

Response

{
    "data": {
        "tag_2otQaFeMwh6OdddfYSYTcIYXUWa": {
            "2024-01-01T04:00:00Z": {
                "sum": 4,
                "min": 4,
                "max": 4,
                "count": 1,
                "mean": 4,
                "median": 4,
                "stddev": 0,
                "first": 4,
                "last": 4
            },
            "2024-01-01T05:00:00Z": {
                "sum": 4,
                "min": 4,
                "max": 4,
                "count": 1,
                "mean": 4,
                "median": 4,
                "stddev": 0,
                "first": 4,
                "last": 4
            },
            "2024-01-01T06:00:00Z": {
                "sum": 4,
                "min": 4,
                "max": 4,
                "count": 1,
                "mean": 4,
                "median": 4,
                "stddev": 0,
                "first": 4,
                "last": 4
            },
            "2024-01-01T07:00:00Z": {
                "sum": 3,
                "min": 3,
                "max": 3,
                "count": 1,
                "mean": 3,
                "median": 3,
                "stddev": 0,
                "first": 3,
                "last": 3
            },
            "2024-01-01T08:00:00Z": {
                "sum": 4,
                "min": 4,
                "max": 4,
                "count": 1,
                "mean": 4,
                "median": 4,
                "stddev": 0,
                "first": 4,
                "last": 4
            },
            "2024-01-01T09:00:00Z": {
                "sum": 3,
                "min": 3,
                "max": 3,
                "count": 1,
                "mean": 3,
                "median": 3,
                "stddev": 0,
                "first": 3,
                "last": 3
            },
            "2024-01-01T10:00:00Z": {
                "sum": 3,
                "min": 3,
                "max": 3,
                "count": 1,
                "mean": 3,
                "median": 3,
                "stddev": 0,
                "first": 3,
                "last": 3
            },
            "2024-01-01T11:00:00Z": {
                "sum": 2,
                "min": 2,
                "max": 2,
                "count": 1,
                "mean": 2,
                "median": 2,
                "stddev": 0,
                "first": 2,
                "last": 2
            }
        }
    }
}

Tag History Not Supported: Our system currently does not retain a history of tag changes. For example, if Zones 1–5 are tagged as "Marketing" in September and updated to "Finance" in December, the original tag ("Marketing") will no longer be available for queries. Only the current tag assignment ("Finance") can be queried. Historical comparisons or analyses based on previous tags must be managed outside the system.