Mean and peak occupancy and utilization for all zones in a tenant within a time range from start (inclusive) to end (exclusive) using a provided resolution.

Results include only the zones in buildings your credentials have been granted occupancy access to.

Resolution can be set to 5m, 10m, 15m, 30m, 1h, 6h and 1d and determines the size of time intervals between the start and end (i.e., resolution set to 30m between 8:30 AM and 10:30 AM would produce occupancy estimates for intervals 8:30 AM, 9:00 AM, 9:30 AM, and 10:00 AM). Larger resolutions are preferred to reduce the size of the result set and the impact of outliers.

Result sets will include one row per interval per zone, and are ordered by the start_timestamp of the interval. Given a resolution of 15m and an interval timestamp of 3:00 PM, the mean_occupancy and peak_occupancy is the average and maximum occupancy from 3:00 PM (inclusive) to 3:15 PM (exclusive).

The mean_utilization and peak_utilization fields are derived from the respective occupancy values divided by the asset's capacity. Both fields are null when capacity is not configured for the asset. capacity and both utilization fields are also null on rows in buildings your credentials have not been granted capacity access to.

Currently all results are returned in a single page. The API rejects requests if the time range is too large for the selected resolution. Valid time ranges based on resolution are:

• 4 days at 5m
• 10 days at 10m
• 2 weeks at 15m
• 1 month at 30m
• 2 months at 1h
• 1 year at 6h
• 4 years at 1d

Intervals are aligned to a fixed grid rather than to start — to the Unix epoch in UTC by default, or to local midnight when bucket_timezone is given. start is floored to the interval boundary at or before it, so a request beginning at 8:00 AM with 1d resolution reports an interval stamped 12:00 AM. At the other end, the last interval reported is the last one ending at or before end; an interval that would run past end is dropped by default, with one exception described below. partial_buckets changes this: see that parameter.

Occupancy is aggregated only over data from start (inclusive) to end (exclusive). Combined with that alignment, this means the first interval of the series covers only the part of itself inside the requested range whenever start does not fall on an interval boundary. Such an interval is partial, and nothing in the row says so — start_timestamp, the occupancy and utilization fields, and the row shape are identical to a whole interval's. Treating one as representing its full labelled period, by averaging it in with whole intervals or reporting it as a whole day or hour, misstates the result. Compare start and end against the resolution to identify it, or pass partial_buckets=none to receive whole intervals only.

A time range narrower than the resolution is answered rather than rejected. Where the whole range falls inside a single interval — 1d resolution from 8:00 AM to 12:00 PM, or from 12:00 AM to 11:59:59 PM — the response is one row, stamped at that interval's start, aggregating only the hours requested (with partial_buckets=none it is an empty results array). It is the caller's responsibility to recognise that such a row does not cover the period its start_timestamp names. To obtain a whole interval instead, use a resolution no longer than the range, or move end past the next interval boundary — bearing in mind that an interval still in progress is itself partial until it closes, and that occupancy lags real time (see below).

In addition to the resolution/time range constraints, responses are limited to a maximum of 3 million rows. Response bodies larger than the row limit are truncated, dropping more recent data (based on ordering).

HTTP compression is enabled for responses larger than 500 bytes when the request includes "gzip" in the Accept-Encoding header.

Please note that Lambent Spaces does not produce occupancy in real time. Occupancies for a given time period may be delayed from 30 minutes to an hour, and this may be further increased due to ingestion lag or data availability from Wi-Fi source systems.

The zone occupancy endpoint is rate-limited to 60 requests per minute.