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 and presence-based.

Request Schema

start required	string The start time of your time range. This can be any RFC3339 string.
stop required	string The start time of your time range. This can be any RFC3339 string.
items required	array An array of Butlr IDs to query for.
measurements required	array An array of supported measurements to query for.
filters	object Supported filters to apply on the data before aggregation.

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

Traffic-based measurements are using calibrated results (i.e. adjusted for traffic drift).

Request

// 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"
      }
    ]
  }
}

Response

{
  "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
    }
  }
}

Data Dictionary

Measurements are named in the following format.

{METRIC}_{AGG_FUNCTION}_{traffic/presence}

Measurement	Definition
occupancy_used_avg_presence	The average of all presence-based occupancy counts (excluding unoccupied periods) within the time range
occupancy_used_avg_traffic	The average of all traffic-based occupancy counts (excluding unoccupied periods) within the time range
occupancy_used_median_presence	The median of all presence-based occupancy counts (excluding unoccupied periods) within the time range
occupancy_used_median_traffic	The median of all traffic-based occupancy counts (excluding unoccupied periods) within the time range
occupancy_avg_presence	The average of all presence-based occupancy counts (including unoccupied periods) within the time range
occupancy_avg_traffic	The average of all traffic-based occupancy counts (including unoccupied periods) within the time range
occupancy_median_presence	The median of all presence-based occupancy counts (including unoccupied periods) within the time range
occupancy_median_traffic	The median of all traffic-based occupancy counts (including unoccupied periods) within the time range

The stats API supports two types of filters: exclude_days_of_week and time_ranges.

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