# Zone Occupancy

**Zone occupancy** refers to the number of people detected in a specific [**zone**](https://docs.butlr.io/asset-management/graphql-api-overview/zones) at a given time. It is calculated by consolidating data from multiple presence sensors within the zone.

<figure><img src="https://3289302098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe3YixUK5tCcflJxye0bT%2Fuploads%2Fgit-blob-93cf8ead2847349cd84e30636a3c2d41c8073579%2FPresence%20chart.png?alt=media" alt=""><figcaption></figcaption></figure>

Below are sample queries for retrieving zone-level occupancy data to analyze **peak**, and **average** within a selected time range.

{% hint style="success" %}
**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. **Include Zero Values in Output:** To ensure zero values are included in the results, add the filter:

   ```json
   "window": { "create_empty": true }
   "filter": { "value": { "gte": 0 } }
   ```

{% endhint %}

### Presence-based Zone Occupancy

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

<div align="left"><figure><img src="https://3289302098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe3YixUK5tCcflJxye0bT%2Fuploads%2Fgit-blob-7a6ab5256f13d5f26005196ff2d4b4b0b6a49db1%2Fpresence%20mode_room.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

Query the **peak hourly occupancy** of a room with presence sensors installed:

{% hint style="info" %}
Use measurement: <mark style="color:purple;">**`zone_occupancy`**</mark>

Use function: <mark style="color:purple;">**`max`**</mark>
{% endhint %}

<details>

<summary>Request</summary>

```json
// 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": ["zone_occupancy"],
        "zones": {
            "eq": ["zone_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "zone_occupancy",
            "measurement": "zone_occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 1,
            "building_id": "building_lvgwoC5RQwbdku6dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2SPCM4O6x9ZotfNWcLoC5RQdq1sx",
            "space_name": "BURIPL-First Floor",
            "room_id": "room_2oqxCp1hypEWta7oRPT1u21xwN",
            "room_name": "504 Open Area",
            "zone_id": "zone_2qfew7oRPTDPQ0f7X9ZotfoiI3w",
            "zone_name": "Hotdesk 1"
            // ... more fields
        }
        // ... more data
    ]
}

```

</details>

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

{% hint style="info" %}
Use measurement: <mark style="color:purple;">**`zone_occupancy`**</mark>

Use function: <mark style="color:purple;">**`mean`**</mark>
{% endhint %}

<details>

<summary>Request</summary>

```json
// 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-01T04:00:00Z",
        "measurements": ["zone_occupancy"],
        "zones": {
            "eq": ["zone_2qfew7oRPTDPQ0f7X9ZotfoiI3w"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "zone_occupancy",
            "measurement": "zone_occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 1.8,
            "building_id": "building_lvgwoC5RQwbdku6dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2SPCM4O6x9ZotfNWcLoC5RQdq1sx",
            "space_name": "BURIPL-First Floor",
            "room_id": "room_2oqxCp1hypEWta7oRPT1u21xwN",
            "room_name": "504 Open Area",
            "zone_id": "zone_2qfew7oRPTDPQ0f7X9ZotfoiI3w",
            "zone_name": "Hotdesk 1"
            // ... more fields
        }
        // ... more data
    ]
}
```

</details>