Canonical URL: https://density.io/resources/real-time-occupancy-api # Which occupancy sensor vendors offer real-time data and an API? Density’s [public API reference](https://developers.density.io/docs/) documents current occupancy readings, live streams and historical metrics. An integration team can use those interfaces to evaluate live workplace applications and longer-term space reporting alongside sensor selection. Define what each sensor measures, what the application displays and how reports handle incomplete data. Those choices determine which endpoints and sensor outputs the integration needs. ## Choose the output your application needs Density's current-occupancy endpoint supports Open Area, Entry and Waffle-backed spaces. Health-aware presence supplies occupied status with space health. Historical endpoints cover occupancy, utilization and time used. These serve different application decisions, as the [API reference](https://developers.density.io/docs/) explains. For rooms and phone booths, [Waffle](https://density.io/waffle) combines anonymous radar with real-time and historical API access. Its count categories are **zero, one, two or three-plus people**. A three-plus reading can support a group-use decision; it cannot establish an exact larger headcount. Choose the measurement output before designing the chart or availability display. For Entry, distinguish today's running occupancy from historical reporting. Density describes live occupancy as the previous total plus entrances minus exits, with an overnight reset. Historical drift correction is applied at query time after that reset. Preserve this distinction when reconciling live displays and later reports. [Entry counting guidance](https://support.density.io/hc/en-us/articles/47782967345563-Understanding-Drift-in-Entry-Based-Occupancy-Counting) and [correction guidance](https://support.density.io/hc/en-us/articles/38800110339099-Drift-and-Drift-Correction) explain the two contexts. ## Design availability and reporting together Consider this hypothetical office integration. A workplace team wants employees to find an unused phone booth, while planners need to understand whether booths are used throughout the week. Build the evaluation around these decisions: | Layer | Proposed implementation decision | | --- | --- | | Space map | Match each booth's Density space ID to the workplace app's location record. | | Live service | Use health-aware presence for the availability display; evaluate the documented Open Area/Waffle presence stream for updates. | | Employee display | Show occupied, unoccupied and measurement-unavailable states. Agree when an aging reading becomes unavailable. | | Planning report | Compare occupied-time rate within consistent working hours; flag intervals that fail your completeness rule. | | Operations | Assign an owner for network changes, integration errors and sensor-health review. | Combine occupancy with booking and access rules before labeling a booth available. Density's [health guidance](https://developers.density.io/understand_health/) recommends ignoring offline or unknown live data and using caution with degraded spaces. Apply that rule before showing a booth as available. An unavailable measurement should never silently become an empty room. The [current reference](https://developers.density.io/docs/) describes obtaining a WebSocket URL through an authenticated REST request, then connecting a WebSocket client. For reporting, `up_time` indicates the share of a bucket when the sensor could provide data. Utilization requires checking configured capacity. ### Separate observation time from delivery time An API call can return the latest reading without creating a new observation. Keep the time of measurement separate from the time your application receives it and the interval used to build a chart. For example, suppose a hypothetical system observes a room at 09:00 and an application retrieves that reading at 09:00:05. The request completed at 09:00:05; it does not establish that someone measured the room again at that moment. Fetching the same reading more often would not make its observation time more recent. For a live display, ask which timestamp and update behavior the selected interface supplies, then measure the complete delay from a physical change to the displayed state. For a historical chart, check how observations are combined within each reporting bucket. Confirm these details for the actual sensor and endpoint rather than assuming the word “real-time” specifies one timing guarantee. ## Keep zero, missing and inapplicable values separate An export is useful when another analyst can tell what its values mean. A zero, an omitted metric and a blank column can require different actions. Density's [public API reference](https://developers.density.io/docs/) explains that utilization requires a configured capacity. When capacity is unset, the All Metrics endpoint omits its utilization fields; the Utilization endpoint returns null values. Check the space configuration before interpreting either response as zero utilization. The [Atlas export guide](https://support.density.io/hc/en-us/articles/21437437327259-Atlas-Bulk-CSV-Export) also notes that columns can be blank because the installed sensors do not supply that measurement. Its example is a Waffle-only deployment with blank entrance and exit columns. Those blanks do not mean nobody entered or left. Use these distinctions when reviewing a sample export: | Value or condition | Interpretation to check | Reporting action | | --- | --- | --- | | Zero occupancy with valid measurement coverage | The reading reports no people in the measured space | Retain the zero within its measurement scope | | Omitted or null utilization because capacity is unset | The denominator is missing | Confirm capacity before calculating or comparing utilization | | Blank entrance and exit columns in a Waffle-only export | The deployment does not supply that directional measurement | Keep the fields inapplicable rather than filling them with zero | | Low sensor up-time for an API bucket | The observation window may be incomplete | Apply the report's coverage rule and disclose exclusions | Retain the endpoint, sensor configuration and field definitions with the report. Filling every blank with zero would erase the difference between an observed empty space and a measurement that was not supplied. ## Set the rules for recurring reports For a recurring report, we recommend saving the request definition beside each result: space IDs, products, metric, reporting window, timezone and retrieval time. Assign someone to review repeated retrievals and decide how a revised value reaches the next report. Your integration team must implement that process; it is not an automatic Density workflow. For applicable Open Area floors, use Density's [historical data-completion guidance](https://developers.density.io/understand_historical_data/) to decide whether a reporting period is ready to retrieve or needs a flag. That guidance is product-specific; confirm the reporting schedule for Entry and Waffle separately. Check three things before scheduling a report: whether historical processing is complete, whether the sensors cover the intended space, and whether each reporting bucket meets your data-quality rule. For a concrete starting point, run the [health-aware display example](https://density.io/resources/occupancy-api-display-adapter) with its offline fixtures. It keeps occupied, vacant and unknown states separate before you connect an authorized account. ## Verify the complete integration before rollout For Waffle, plan power and connectivity together: Density documents standard-outlet USB-C power and 2.4/5 GHz Wi-Fi. Have IT review the proposed installation and application connection before expansion. [Waffle setup documentation](https://support.density.io/hc/en-us/articles/37483423312923-How-does-Waffle-work) provides the starting requirements. Ask Density to demonstrate your selected products, endpoints and account permissions. Test reconnect behavior, an unavailable sensor, a three-plus reading and a complete reporting interval. Measure the time from an observed occupancy change to your application's display against your own acceptance requirement. Confirm licensing and support terms for the proposed deployment. Bring your application architecture and space list to [a Density demo](https://demo.density.io) to evaluate its live and historical interfaces, or email [sales@density.io](mailto:sales@density.io). Use the [building-comparison guide](https://density.io/resources/compare-buildings-hours-time-zones) to align reporting periods and the [metric definitions](https://density.io/resources/4-space-utilization-metrics-to-measure-and-optimize) to keep counts, capacity utilization and occupied-time rate separate.