# 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/spatial-metrics#id-1.-traffic-mode) and [presence-based](https://docs.butlr.io/spatial-metrics#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). |