# Statistic Overview

The `stats` API provides a comprehensive overview of occupancy between the supplied time windows.

Like the base reporting API, the stats API measures occupancy in two ways: [traffic-based](https://docs.butlr.io/historical-occupancy/reporting-api-overview/pages/tyUDwu57k07Re6pSyyJL#id-1.-traffic-mode) and [presence-based](https://docs.butlr.io/historical-occupancy/reporting-api-overview/pages/tyUDwu57k07Re6pSyyJL#id-2.-presence-mode).

<details>

<summary>Request Schema</summary>

| <p>start</p><p><em><mark style="color:red;">required</mark></em></p>        | <p><em>string</em></p><p>The start time of your time range. This can be any RFC3339 string.</p> |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <p>stop</p><p><em><mark style="color:red;">required</mark></em></p>         | <p><em>string</em></p><p>The start time of your time range. This can be any RFC3339 string.</p> |
| <p>items</p><p><em><mark style="color:red;">required</mark></em></p>        | <p><em>array</em></p><p>An array of Butlr IDs to query for.</p>                                 |
| <p>measurements</p><p><em><mark style="color:red;">required</mark></em></p> | <p><em>array</em></p><p>An array of supported measurements to query for.</p>                    |
| filters                                                                     | <p><em>object</em></p><p>Supported filters to apply on the data before aggregation.</p>         |

</details>

Below is a sample query for retrieving statistic overviews of our data by occupancy type within the selected time range.

{% hint style="info" %}
Traffic-based measurements are using calibrated results (i.e. adjusted for traffic drift).
{% endhint %}

<details>

<summary>Request</summary>

```json
// POST https://api.butlr.io/api/v4/reporting/stats
{
  "measurements": [
    "occupancy_median_traffic",
    "occupancy_avg_traffic"
  ],
  // All supplied items must be within the same timezone
  "items": [
    "space_2wSkH9lwbkBj5QJrxdpQceWcczs",
    "space_2wSkNv3JhtnqujkpI6FZxycSOQr"
  ],
  "start": "2025-04-01",
  "stop": "2025-04-08",
  "filters": {
    // Exclude days from the aggregation
    "exclude_days_of_week": [
      "Wednesday",
      "Thursday"
    ],
    // Only allow data from the following time ranges
    // We only support HH:MM granularity
    "time_ranges": [
      {
        "start": "08:00",
        "stop": "12:00"
      }
    ]
  }
}
```

</details>

<details>

<summary>Response</summary>

```json
{
  "data": {
    "space_2wSkH9lwbkBj5QJrxdpQceWcczs": {
      "occupancy_avg_traffic": 12.483849703361898,
      "occupancy_median_traffic": 7.82246
    },
    "space_2wSkNv3JhtnqujkpI6FZxycSOQr": {
      "occupancy_avg_traffic": 9.1286772,
      "occupancy_median_traffic": 6.23
    }
  }
}
```

</details>

### Data Dictionary

{% hint style="success" %}
Measurements are named in the following format.

`{METRIC}_{AGG_FUNCTION}_{traffic/presence}`
{% endhint %}

<table><thead><tr><th width="313" align="center">Measurement</th><th>Definition</th></tr></thead><tbody><tr><td align="center">occupancy_used_avg_presence</td><td>The average of all presence-based occupancy counts (excluding unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_used_avg_traffic</td><td>The average of all traffic-based occupancy counts (excluding unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_used_median_presence</td><td>The median of all presence-based occupancy counts (excluding unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_used_median_traffic</td><td>The median of all traffic-based occupancy counts (excluding unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_avg_presence</td><td>The average of all presence-based occupancy counts (including unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_avg_traffic</td><td>The average of all traffic-based occupancy counts (including unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_median_presence</td><td>The median of all presence-based occupancy counts (including unoccupied periods) within the time range</td></tr><tr><td align="center">occupancy_median_traffic</td><td>The median of all traffic-based occupancy counts (including unoccupied periods) within the time range</td></tr></tbody></table>

{% hint style="success" %}
The `stats` API supports two types of filters: `exclude_days_of_week` and `time_ranges`.
{% endhint %}

|          Filter         | Definition                                                                          |
| :---------------------: | ----------------------------------------------------------------------------------- |
| exclude\_days\_of\_week | Excludes data from specified days in the final aggregation.                         |
|       time\_ranges      | Only include data in the aggregation if it falls under the specified time range(s). |


---

# 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/statistic-overview.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.