Occupancy

Occupancy from desk and motion sensors, at spot, room, or floor level.

Measurement	Data keyed by	Sensor
spot_desk_occupancy	spot_id	Desk occupancy
room_desk_occupancy	room_id	Desk occupancy
floor_desk_occupancy	floor_id	Desk occupancy
spot_motion_occupancy	spot_id	Motion
room_motion_occupancy	room_id	Motion
floor_motion_occupancy	floor_id	Motion

Intervals: 1m, 15m, 30m, 1h, 1d. Max range: set by the interval; see Query Limits.

What occupancy counts

It depends on the sensor type and level:

Measurement	occupancy in each minute	presence_time_secs in each minute
spot_desk_occupancy, spot_motion_occupancy	1 if the spot's sensor detected presence, else 0	Seconds of presence (0–60)
room_desk_occupancy, floor_desk_occupancy	Number of occupied desk sensors in the room/floor	Sum across the desk sensors
room_motion_occupancy	1 if any motion sensor in the room was active, else 0	Maximum across the room's motion sensors
floor_motion_occupancy	Number of rooms on the floor with motion	Maximum across the floor's motion sensors

occupancy_mean is a 0–1 fraction only for spot measurements and room_motion_occupancy. For room_desk_occupancy and floor_desk_occupancy it is the average number of occupied desks; compare it with total_spots to get utilization. For floor_motion_occupancy it is the average number of rooms with motion.

Spot measurements include only sensors attached to a spot, and room measurements only sensors inside a room. See Spots & Sensor Placement.

Fields at 1m

Field	Description
occupancy	The per-minute value described above
presence_time_secs	The per-minute value described above
presence_time_secs_sum	Copy of presence_time_secs, so the same field name works at every interval. Only added when presence_time_secs is returned: with fields, list presence_time_secs at 1m.
total_spots	Desk measurements at room/floor level only: number of desk sensors counted

Fields at 15m, 30m, 1h, 1d

Statistics over the per-minute values in the window:

Field	Description
occupancy_min	Lowest per-minute value
occupancy_max	Highest per-minute value
occupancy_mean	Average of the per-minute values recorded in the window, rounded to 2 decimal places
occupancy_median	Median per-minute value at 15m. At 30m, 1h, and 1d it repeats occupancy_mean, because those windows are built from 15m windows and a true median cannot be computed. For a real median, request 15m.
occupancy_first	First per-minute value in the window
occupancy_last	Last per-minute value in the window
occupancy_sum	Sum of per-minute values
presence_time_secs_sum	Total presence seconds in the window
total_spots	Desk measurements at room/floor level only

Each point also carries location metadata.

Desk and motion measurements at the same level return the same field names and share a key. Request them separately; see Combining measurements.

Example: desk utilization per spot, every 15 minutes

curl -X POST https://api-integrations.butlr.io/api/v1/reporting \
  -H "Authorization: Bearer [insert access_token here]" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": ["spot_desk_occupancy"],
    "items": ["room_XXXX"],
    "start": "2026-09-14T13:00:00Z",
    "stop": "2026-09-14T14:00:00Z",
    "interval": "15m",
    "fields": ["spot_name", "occupancy_mean", "occupancy_median", "presence_time_secs_sum"]
  }'

{
  "data": {
    "spot_XXXX": [
      {
        "start": "2026-09-14T13:00:00Z",
        "stop": "2026-09-14T13:15:00Z",
        "spot_name": "Desk 3A",
        "occupancy_mean": 0.8,
        "occupancy_median": 1,
        "presence_time_secs_sum": 720
      },
      …
    ]
  }
}

For a room-level example, see the Quick start.