Build a room occupancy display with Density’s health-aware API

A room display needs three states: occupied, vacant and unknown. When a measurement is missing, the display should say so. Turning a failed request or an omitted room into “vacant” gives people an answer the system did not observe.

Density's public beta API includes health-aware presence. The accompanying Python example turns its documented response into those three display states. It runs offline with illustrative fixtures, so a developer can inspect the behavior before connecting an authorized Density account.

Read the Python source or read the illustrative fixture as plain text. These are the same source and fixture bytes included in the download.

Run the example with illustrative rooms

The example contains a standard-library Python CLI, one JSON fixture, behavior tests and source notes. It requires no package installation. The fixture describes an empty healthy room, an occupied healthy room and an offline room. A fourth requested room is deliberately absent from the response.

Download the Python example and fixtures. Extract the archive, then enter its density-occupancy-display-example folder:

curl --fail --location --output density-occupancy-display-example.zip https://cdn.prod.website-files.com/5f49c40736fbe713860f9203/6ae5b005da84eca692145157_density-occupancy-display-example-v3.zip
unzip density-occupancy-display-example.zip
cd density-occupancy-display-example
python3 occupancy_display.py --fixture fixtures/illustrative.json --space spc_empty --space spc_busy --space spc_unhealthy --space spc_missing

Run the CLI with the fixture path and repeat --space for each room. The expected results are vacant, occupied, unknown and unknown. Inspecting an omitted room beside a genuinely empty room makes the distinction concrete: only the latter supplies a healthy measurement saying nobody is present.

The example uses a conservative rule. A healthy response with a literal true becomes occupied; healthy with false becomes vacant. Degraded, offline, unknown, missing or malformed measurements become unknown. Failed requests do, too. That treatment of degraded data is the example's display policy, rather than a claim that Density requires every application to use it.

Follow the documented response, including what it leaves out

The server sends an explicit list of configured space IDs to POST /v3/analytics/presence-health. The documented response has a data object keyed by space ID. Each room's fields are presence and space_health_status. The schema does not require either field, so the example handles their absence rather than assuming every successful request contains a usable reading.

This REST response does not document an observation timestamp. The example's processed_at records when the adapter produced its output. It cannot establish when a sensor last observed the room. Likewise, transport_ok describes the HTTP request, not the validity or freshness of every measurement.

There is no background service or cache in the example. The application using its output must decide when old results expire and show unknown when updates stop. Agree that rule for the actual display; polling more often does not prove that a new physical observation occurred.

Keep the provider connection on the server

The optional live mode reads a bearer token from the server environment and makes one request to the fixed Density endpoint. It does not accept a caller-supplied destination, follow redirects or print upstream error bodies. Keep credentials off the webpage and out of shared command output.

Density's Quick Start describes account requirements, Owner access and machine-to-machine credentials. Confirm entitlement, supported spaces and actual response behavior with Density before deployment. The presence endpoint family documents Open Area and Waffle; the example does not extend that scope to every sensor.

The included tests exercise synthetic responses and a fake HTTP opener. They establish the example's state mapping and request behavior. They do not establish authenticated provider access, physical sensing performance, end-to-end delay or production readiness. No live provider call was made when preparing this example.

A vacant measurement also does not mean a room is bookable. Reservations, access restrictions and equipment requirements belong to the application that makes that decision.

Bring your display requirements and space list to a Density demo, or email sales@density.io. Use the occupancy API guide for the broader integration decisions and the Entry guide when the measurement needs entrance and exit counts.

Browse occupancy guides and sensor comparisons · Read the plain-text version