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.
Recommended Practices
Recommended Aggregation by Query Interval: To ensure accurate interpretation of occupancy data, we recommend different aggregation methods based on the query interval:
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.Larger Intervals (e.g. hourly, daily)
Use
mean
for average occupancy over the interval to help identify overall usage patterns.Use
max
for peak occupancy within the interval to understand the busiest times or capacity thresholds.
Traffic Metrics: Use the
sum
function to aggregate the total entries and exits over the defined period.
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.Timezone Configuration: Always provide a timezone when querying traffic-based occupancy
Include Zero Values in Output: To ensure zero values are included in the results, add the filter:
"window": { "create_empty": true } "filter": { "value": { "gte": 0 } }
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
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.
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 (replacespace_XXXX
with the floor ID)."value": { "gte": 0 }
: Ensures zero values are included in the results.
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.
Last updated