Reading data out

Your system asks, Omaya answers. Read-only, on whatever schedule suits you.

The endpoints worth knowing

Endpoint	Gives you
GET /api/v1/spaces	Venues and their zones, with the UIDs everything else is addressed by
GET /api/v1/occupancy	How many people are in every zone right now, each with its source
GET /api/v1/occupancy/{zone_uid}	The same for one zone
GET /api/v1/occupancy/{zone_uid}/history	Hourly peak, mean and last reading over a period

Entities, admins, roles and users have their own endpoints too — the API reference is the full list.

A first call

GET /api/v1/occupancy
X-Tenant-ID: yourorg
X-Api-Key: <your key>

Each zone comes back with its count, the source that count came from, the tags seen regardless, its capacity and occupancy_pct if one is set, and a status of empty, normal, busy or over.

Three things to build in from the start

Read the source, not just the count. radar and sensor mean everyone in the room. tags means only people carrying one — a real number, answering a different question. external means another system reported it. A dashboard that shows all four as "occupancy" will mislead someone eventually.

Do not poll faster than the data changes. Live occupancy is cached for 30 seconds, so a request every second gets you the same answer thirty times. Once a minute is plenty for a wall display; a room-booking panel that needs to feel instant is the case for subscribing instead.

Ask the right endpoint about the right timeframe. Live endpoints are current to seconds. The history endpoint reads tables rebuilt every five minutes, and today's daily totals are provisional until the overnight rebuild. Neither is wrong; asking the second one about the last two minutes is.

Reading history

GET /api/v1/occupancy/{zone_uid}/history returns one row per hour, and each row carries three numbers that answer different questions:

Field	Means
peak	The busiest moment in that hour
mean	The average across the hour's readings
last	The final reading of the hour

Use peak for "was this room ever too small", mean for "how hard did it work". Summing last across hours is meaningless — they are levels, not totals.

When the answer is empty

An empty zone list usually means one of three things, in order of likelihood: the key belongs to a different organisation than the one in X-Tenant-ID; the zones exist but nothing in them counts anything; or the zones have not been drawn yet. The occupancy reference covers the middle case, which is the one that looks most like a bug and is not.