Choosing a data source
XY Sense exposes the same underlying data in several ways, each suited to a different job. A few minutes here will help you pick the right one for your workload before you build.
Which source for which job
| You want | Use | Instead of |
|---|---|---|
| Live occupancy pushed to your system | Webhooks (OccupancyChanges) | Polling analytics |
| Live/recent occupancy on demand | occupancyChanges / occupancy queries (polling guide) | occupancyPerMinute, which is next-day analytics |
| Utilisation reporting over days/weeks/months | Analytics queries (occupancyPerHour, occupancyPerDay, ...) | Storing and aggregating every webhook event yourself |
| Where activity happened on a floor plan over a period | Historical heatmap | Reconstructing it from sightings |
| Raw event-level history beyond the retention windows below | Webhooks, captured and stored on your side |
The API focuses on recent events plus long-term aggregates: raw events are kept for a rolling window, and beyond it the API serves aggregates (analytics and heatmaps). The exact windows per dataset are in Limits and retention. If your application needs raw events long-term, capture them via webhooks and store them from day one, since raw events age out of the API.
Feature enablement
Each source above is gated by a feature that XY Sense enables for your organisation, and enablement can vary per building and floor. Before building against one, confirm with your XY Sense representative that it is enabled where you need it. The feature names below are entitlements rather than separate endpoints, which is why one feature covers both the queries and the matching webhook.
| Data | Feature |
|---|---|
Occupancy queries and OccupancyChanges webhooks | Occupancy API |
Floor sighting queries and FloorSightings webhooks | Sightings API |
Space sensor reading queries and SpaceSensorReadings webhooks | Space Sensor Readings API |
| Analytics queries and historical heatmaps | Analytics API |
| Test-data generator mutations | Dev mode (per floor) |
When a feature is not enabled, queries return a readable error naming the feature and the affected floors (for example Analytics Api access disabled for floor ...), and webhook registration for the matching event type is declined with a similar message. Running the Quickstart queries is a quick way to smoke-test your access.
Live data vs analytics
- Occupancy changes, sightings, and sensor readings are near-real-time, with updates as often as every ~2 seconds.
- Analytics (
occupancyPerMinute,occupancyPerFiveMinutes,occupancyPerHour,occupancyPerDay) is processed overnight per building, so it is next-day data, not a live feed. Note thatoccupancyPerMinuteis next-day analytics too: minute resolution means minute granularity, not minute latency. - Historical heatmaps are the exception among the analytics queries and run close to live.
Exact availability for each is in Limits and retention.
Analytics also applies filtering that live data does not, so the two can legitimately disagree for the same space and hour. See How occupancy is determined.