# Floor Occupancy

**Floor occupancy** refers to the number of people detected on a specific [**floor**](https://docs.butlr.io/asset-management/graphql-api-overview/floors) at a given time. There are two ways to measure **floor occupancy**: [**traffic-based**](https://docs.butlr.io/spatial-metrics#traffic-mode) or [**presence-based**](https://docs.butlr.io/spatial-metrics#presence-mode). Each method uses a different approach depending on the available sensor data and the type of insights required.

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

Below are sample queries for retrieving floor-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. **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:

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

{% endhint %}

### Traffic-based Floor 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-eee4ef395ce369edd35527c43df35cd3fc575b94%2Ftraffic%20mode.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

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.

Query the **peak hourly occupancy** of a floor with main entrance(s) [traffic](#traffic-mode) sensor installed:

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

Use the function: <mark style="color:purple;">**`max`**</mark>

Use `"calibrated": "true"`
{% endhint %}

<details>

<summary>Request</summary>

```json
// 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"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "aggregator_occupancy",
            "measurement": "aggregator_headcount",
            "time": "2024-01-01T04:00:00Z",
            "value": 1,
            "building_id": "building_lvgwdvaIWQaOY06dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2qfewAEoTVaIWQaOY0WZlD729pr",
            "space_name": "BURIPL-H2",
            ... // more fields
        }
    // ... more data
    ]
}
```

</details>

***

Query the **average hourly occupancy** of a floor with main entrance(s) [traffic](#traffic-mode) sensor installed:

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

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

Use **`"calibrated": "true"`**
{% endhint %}

<details>

<summary>Request</summary>

```json
// 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"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "aggregator_occupancy",
            "measurement": "aggregator_headcount",
            "time": "2024-01-01T04:00:00Z",
            "value": 1,
            "building_id": "building_lvgwdvaIWQaOY06dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2qfewAEoTVaIWQaOY0WZlD729pr",
            "space_name": "BURIPL-H2",
            ... // more fields
        }
    // ... more data
    ]
}
```

</details>

***

### 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.

<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-bf1dc1197b82f0100c4f4702abff0c1679812c64%2Fpresence%20mode.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>

Query the **peak or average hourly occupancy** of a floor with presence sensors installed:

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

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": ["floor_occupancy"],
        "spaces": {
            "eq": ["space_2qfew8mjwwek7JwLY1zS9cgyPo6"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "floor_occupancy",
            "measurement": "floor_occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 1,
            "building_id": "building_lvgwdvaIWQaOY06dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2qfewAEoTVaIWQaOY0WZlD729pr",
            "space_name": "BURIPL-H2",
            ... // more fields
        }
    // ... more data
    ]
}
```

</details>

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

{% hint style="info" %}
Use measurement: <mark style="color:purple;">**`floor_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-02T04:00:00Z",
        "measurements": ["floor_occupancy"],
        "spaces": {
            "eq": ["space_2qfew8mjwwek7JwLY1zS9cgyPo6"]
        }
    }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
    "data": [
        {
            "field": "floor_occupancy",
            "measurement": "floor_occupancy",
            "time": "2024-01-01T04:00:00Z",
            "value": 1,
            "building_id": "building_lvgwdvaIWQaOY06dvdrxpbe",
            "building_name": "Butlr HQ",
            "space_id": "space_2qfewAEoTVaIWQaOY0WZlD729pr",
            "space_name": "BURIPL-H2",
            ... // more fields
        }
    // ... more data
    ]
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.butlr.io/historical-occupancy/reporting-api-overview/floor-occupancy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.