How often occupants come to one building, and how long they stay on a day they come, as proportions of the occupants seen there over a range of dates.
For each occupant, frequency is the days they were present divided by the weeks they were present, with weeks running Sunday to Saturday. A week counts only if they came in it, and a week cut short by the start or end of the range counts as a whole one, so frequency is at least 1 and at most 7. Duration is the time they spent on their visits, summed for each day and averaged over the days they were present. Time spent away from the building between visits isn't counted.
Occupants are grouped by frequency into seven buckets, 1 day a week to 7 days a week. Each bucket includes its upper edge: 2 days a week holds frequencies above 1 and up to 2, so an occupant who came 3 days in 2 weeks (1.5) is in 2 days a week. Add buckets together for wider bands: for example, 2 days a week and 3 days a week together are 2 to 3 days a week.
Each bucket is then split by duration into bins bin_hours wide, starting at zero. A bin includes its lower edge and not its upper one, so an average of exactly 2 hours is in 2-3. bin_hours can be any whole number of hours from 1 to 24. The last bin is open and starts at the first multiple of bin_hours at or above 12 hours: 12+ for a width of 1 or 2, 15+ for 5, 14+ for 7. Every bucket and bin is returned, including empty ones at zero.
The response contains no counts or totals of any kind. Every figure is a proportion, rounded to two decimal places, so shares that should add up to 1 can be off by a few points: twelve equal duration bins are each 0.08, which add up to 0.96.
start and end are dates in the building's local time, and both are included. The range must cover at least two days and at most two years (731 days); frequency and duration are most meaningful over at least two weeks. days_of_week limits the days counted to those weekdays, and the range must include at least one of them.
The response has three parts:
data: one row per frequency bucket, with its label (bucket), itsshareof all the occupants in the response, and its duration bins (children), each with itsshare_withinthe bucket.applied: the parameters used, including any defaults you left out.coverage:window_days, the number of days fromstarttoend, andwindow_weeks, those days divided by 7.
Figures for the most recent days can change from one day to the next as more activity is taken into account. Figures for older dates are stable, so allow for this when comparing two requests that cover recent dates.
HTTP compression is enabled for responses larger than 500 bytes when the request includes "gzip" in the Accept-Encoding header.
The occupants endpoint is rate-limited to 60 requests per minute.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Bad request: no tenant ID could be determined from the request or the credentials, or both an Authorization header and an X-API-Key header were sent. Send one or the other.
Missing or invalid credentials: no token or key, an invalid or expired token, or an API key that isn't recognised or has been revoked (Invalid API key) or is past its expiration date (API key has expired).
The credentials are valid but don't grant this data: a tenant ID other than your organization's, or no access to the Analyze API or to occupancy data for any building. Contact Lambent to change what your credentials can access.
No building with that ID is available to your credentials. This is the same whether the building doesn't exist or your credentials don't include it.
Too many requests. The limit is 60 per minute; wait before retrying.
An unexpected error on our side. Retry, and contact Lambent if it persists.
The credentials couldn't be verified right now (Unable to verify token, Unable to verify access or Unable to verify API key). They may well be valid, so retry after the number of seconds in the Retry-After header rather than requesting new ones.