Available data
XY Sense exposes seven broad categories of data, the same whether you query them over the GraphQL API or receive them through webhooks. Space and sensor data provide the reference model for your portfolio. Time-series data provides current, recent, or aggregated observations that can be joined to that model using stable identifiers.
Access to occupancy, analytics, floor sightings, historical heatmaps, and space sensor readings depends on the features enabled for your organisation.
| Category | What it contains | Typical use |
|---|---|---|
| Space data | Buildings, floors, floor spaces, shapes, types, groups, names, and capacities | Build portfolio navigation and resolve IDs from events |
| Sensor data and status | Area, entry, and space sensors, installations, positions, associations, and connection state | Monitor sensor health and associate readings with spaces |
| Occupancy time series | Current and recent headcount and occupancy-state changes per floor space | Live availability, automation, and state reconciliation |
| Space sensor readings | Comfort, air-quality, light, noise, pressure, and sensor-derived occupancy readings | Environmental monitoring and space automation |
| Floor sightings | Detected XY positions and total headcount for a floor | Live floor views, wayfinding, and spatial applications |
| Analytics time series | Aggregated occupancy metrics over minute, five-minute, hourly, and daily intervals | Utilisation reporting and trend analysis |
| Historical heatmaps | Weighted floor-plan cells aggregated over a requested time range | Understand where activity occurred within a floor |
Limits and retention
This table is the single source of truth for request windows, retention, and freshness. The guides link here rather than repeating the numbers, so if a figure appears elsewhere in these docs and disagrees with this table, treat this table as correct and tell us.
| Dataset | Maximum window per request | Rolling retention | Freshness |
|---|---|---|---|
| Space and sensor reference | n/a, current state | n/a, current state | Updated as your portfolio changes |
| Sensor connection status | n/a, current state | n/a, current state | Near-real-time |
| Occupancy changes | 1 hour | 1,000,000 changes or 24 hours | ~2 seconds |
| Floor sightings | 1 hour | 1,000,000 updates or 24 hours | ~2 seconds |
| Space sensor readings | 24 hours | 1,000,000 readings or 48 hours | ~10 minutes for comfort and air quality |
| Analytics, per minute | 1 day | Retained long-term | Previous day |
| Analytics, per five minutes | 1 day | Retained long-term | Previous day |
| Analytics, per hour | 31 days | Retained long-term | Previous day |
| Analytics, per day | 365 days | Retained long-term | Previous day |
| Historical heatmaps | 31 days | Retained long-term | ~15 minutes behind live |
Analytics is processed overnight per building, so each day's figures become available from around 6 am the next morning in the building's local time. The most recent analytics you can retrieve is the previous day's.
Whichever limit is reached first applies: space sensor readings, for example, are dropped at 1,000,000 readings even if that happens inside 48 hours.
Analytics and heatmap requests are scoped to one building and paged with a maximum page size of 100,000 records.
Raw events age out at the retention shown above. If your application needs event-level history beyond those windows, capture it through webhooks and store it from day one. Webhook queue depth and retry limits are listed separately under delivery and batching.
Space data
Space data describes the physical hierarchy of your portfolio:
- Each building has one or more floors.
- Each floor has one or more floor spaces, such as desks, rooms, or zones.
- Floor spaces have a shape and space type, and can belong to space groups.
- Shapes are polygons represented by points. Point coordinates are centimetres from the top-left of the floor plan.
- Stable building, floor, and floor-space IDs connect reference data to occupancy, analytics, sightings, heatmaps, and webhook events.
Start with building and floor discovery, then use the generated Building, Floor, and FloorSpace type references for field-level detail.
Sensor data and connection status
Floors can contain area sensor, entry sensor, and space sensor installations. Each installation records its floor position and references the physical sensor.
Associations differ by sensor type:
- Area sensor installations have no direct floor-space association. Occupancy is derived by merging detections across sensors and overlaying space shapes, so there is no per-sensor occupancy to query: see How sensors map to spaces.
- Entry sensor installations expose entries that track forward and backward movement. Entries are associated with floor spaces so movement contributes to live headcount and occupancy state.
- Space sensor installations can be associated with multiple floor spaces. Individual capabilities can be ignored for an installation or floor-space association.
Connection status is available for each sensor. An offline sensor does not always indicate a fault: check the floor's currentFloorStatus, because sensors on floors being installed or reviewed may not yet be expected to remain online.
See sensor connection status for practical queries.
Occupancy time series
Occupancy represents the headcount and occupancy state for a floor space at a point in time. Updates are produced approximately every two seconds and can be accessed as:
- The latest occupancy for a floor space.
- Recent occupancy changes across accessible spaces.
- Occupancy changes since a timestamp, optionally filtered by building, floor, or floor space.
Request windows and retention are in Limits and retention.
Occupancy states are:
CurrentlyOccupied: one or more sightings within 30 seconds ofcollectedDate.RecentlyOccupied: one or more sightings between 30 and 60 seconds beforecollectedDate.NotOccupied: no sightings within 60 seconds ofcollectedDate.Unknown: no occupancy information is available for the space.
For why the states behave this way, including why a space can change state with nobody entering or leaving it, see How occupancy is determined.
Use webhooks for ongoing occupancy changes. Use occupancy polling for bootstrap, replay, and reconciliation windows.
Space sensor readings
Space sensor readings contain current and recent observations from space sensors. Depending on the installed model and enabled features, capabilities can include:
- Occupancy
- Temperature
- Humidity
- Ambient and relative light
- Ambient noise
- Barometric pressure
- Carbon dioxide
- Volatile organic compounds
- Particulate matter at 1, 2.5, and 10 micrometres
The exact capabilities available to you depend on the sensor models installed and on which capabilities are enabled per space, so discover them at runtime with the spaceSensorCapabilities query rather than assuming a fixed set. Each capability includes its measurement unit and the sensor types that support it.
Readings can be fetched by floor space or physical sensor, as the latest values or as changes since a timestamp. Request windows, retention, and update frequency are in Limits and retention.
Use webhooks for ongoing reading changes and space sensor readings polling for capability discovery, latest values, history, and reconciliation.
Floor sightings
Floor sightings contain the detected XY positions and total headcount for a floor at a point in time. Coordinates are centimetres from the top-left of the floor plan, and updates are produced approximately every two seconds.
Sightings can be fetched as the latest observations per floor or as changes since a timestamp. Request windows and retention are in Limits and retention.
Use webhooks for ongoing sighting updates and floor sightings polling for recent snapshots and reconciliation.
Analytics time series
Analytics data contains aggregated occupancy metrics for each floor space, including minimum, maximum, and time-weighted average occupant counts and occupied duration.
Analytics is processed overnight for each building, so it is next-day data rather than a live feed. Request windows and availability are in Limits and retention.
Each interval applies different default filtering:
| Interval | Default filtering |
|---|---|
| Per minute | None |
| Per five minutes | None |
| Per hour | Excludes walk-bys |
| Per day | Excludes walk-bys and out-of-hours activity |
The walk-by filter excludes activity with less than one minute of usage over ten minutes. Daily results also apply each building's configured active hours, which default to 7 am to 7 pm, Monday to Friday.
See analytics polling for query and pagination examples.
Historical heatmaps
Historical heatmaps aggregate activity into weighted cells across a floor plan. Each cell contains its centre point, aggregation window, and a relative event weight.
Unlike the other analytics queries, heatmaps run close to live rather than next-day. Request windows and freshness are in Limits and retention. See historical heatmap for floor-plan positioning and rendering guidance.