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

{% hint style="success" %}
**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:

   <pre class="language-json"><code class="lang-json"><a data-footnote-ref href="#user-content-fn-1">"filter": { "value": { "gte": 0 } }</a>
   </code></pre>

{% endhint %}

{% hint style="info" %}
**NOTE:** Presence time data is available starting from **November 12, 2024**.\
This data is only available for spaces with presence mode sensors installed.
{% endhint %}

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.

<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-e7c659e783650d2255865907992489a7f4254de5%2Fimage%20(3)%20(1).png?alt=media" alt="" width="375"><figcaption><p>Presence time</p></figcaption></figure></div>

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

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

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

<details>

<summary>Request</summary>

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

</details>

<details>

<summary>Response</summary>

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

</details>

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

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

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

<details>

<summary>Request</summary>

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

</details>

<details>

<summary>Response</summary>

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

</details>

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

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

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

<details>

<summary>Request</summary>

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

</details>

<details>

<summary>Response</summary>

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

```

</details>

[^1]: remove?