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.

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.



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

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

For real-time updates, subscribe to real-time webhooks to receive instant notifications of changes to occupancy or traffic metrics. Real-time data complements historical queries by enabling live monitoring and immediate action.

Last updated