# 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="/files/GuJ6krabIIiGz7dvYKiU" 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?


---

# 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/presence-time.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.