# Reporting API Overview

The **Butlr Reporting API** is a RESTful API designed to provide time-series occupancy data, making it ideal for analyzing historical trends in space utilization. This API is optimized for standardized reporting, enabling users to aggregate data across floors, rooms, or zones to manage and optimize physical spaces efficiently. Use this API to track occupancy patterns over time or analyze historical trends, enabling data-driven decisions that enhance space management strategies.

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

## **Best Practices for Using Reporting API v3**

When using the Reporting API v3, adhering to the recommended practices ensures data accuracy and provides meaningful insights. Proper configuration of parameters such as windowing functions, timezones, and filters directly impacts the granularity and relevance of your results.

***

{% 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.
   3. **Traffic Metrics:** Use the `sum` function to aggregate the total entries and exits over the defined period.
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. **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 %}

***

### **Example Query**

The following example demonstrates how to retrieve **traffic-based floor occupancy** data using the Reporting API.

**POST** `https://api.butlr.io/api/v3/reporting`

```json
// POST https://api.butlr.io/api/v3/reporting
{
    "window": {
        "every": "1h",
        "function": "max", 
        "timezone": "America/New_York", // Replace with your timezone
        "create_empty": true // Ensures days with no data point have zeros in the output 
    },
    "filter": {
        "start": "2024-01-01T04:00:00Z",
        "stop": "2024-01-02T04:00:00Z",
        "measurements": ["traffic_floor_occupancy"],
        "spaces": {
            "eq": ["space_2qfeX6pnfGCeD4r49CtSJqYqm5f"]
        },
        "value": { "gte": 0 } // Ensures zeros are included in the output
    },
    "group_by": {
      "order": ["time"]
    }
}
```

***

### **Key Parameters**

1. **Window Parameters:**
   * **`"every": "1h"`**: Specifies a 1-hour window size.
   * **`"function": "sum"`**: Aggregates the total entries and exits during each 1-hour window.
   * **`"timezone": "America/New_York"`**: Local timezone of the space.
   * **`"create_empty": true`**: When used with `"value": { "gte": 0 }`, this ensures periods with no data return 0 instead of being omitted.
2. **Filter Parameters:**
   * **`"start": "2024-01-01T04:00:00"`**: The start time of the query period in the specified timezone.
   * **`"stop": "2024-01-02T04:00:00"`**: The end time of the query period.
   * **`"measurements": ["traffic_floor_occupancy"]`**: Specifies the metric to retrieve.
   * **`"spaces": {"eq": ["space_XXXX"]}`**: Filters the query to the specific floor (replace `space_XXXX` with the floor ID).
   * **`"value": { "gte": 0 }`**: Ensures zero values are included in the results.
3. **Group By:**
   * **`"order": ["time"]`**: Groups and orders results by the specified time intervals.

***

### **Customizing Your Queries**

* **Window Size:**\
  Adjust `"every": "1h"` to smaller intervals like `"5m"` or `"1m"` for more granular data.
* **Aggregation Function:**
  * Use `"max"` for occupancy metrics to capture peak values within a time range.
  * Use `"mean"` for average occupancy within a time range.
  * Use `"sum"` for traffic metrics to calculate total flow within a time range.
* **Measurements:**\
  Replace `"traffic_floor_occupancy"` with other metrics, such as `"room_occupancy"` or `"zone_occupancy"`, depending on the desired level of granularity and deployed sensor mode.
* **Time Range:**\
  Modify `"start"` and `"stop"` to align with your analysis period.

{% hint style="info" %}
For real-time updates, subscribe to[ real-time webhooks](https://docs.butlr.io/real-time-occupancy/webhooks-overview) to receive instant notifications of changes to occupancy or traffic metrics. Real-time data complements historical queries by enabling live monitoring and immediate action.
{% endhint %}