Available data

The GraphQL API exposes seven broad categories of XY Sense data. 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

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.
• 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.

Each request can cover up to one hour. The rolling history contains up to the most recent 1,000,000 changes or 24 hours of data.

Occupancy states are:

• CurrentlyOccupied: one or more sightings within 30 seconds of collectedDate.
• RecentlyOccupied: one or more sightings between 30 and 60 seconds before collectedDate.
• NotOccupied: no sightings within 60 seconds of collectedDate.
• Unknown: no occupancy information is available for the space.

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. A request can cover up to 24 hours, and the rolling history contains up to the most recent 1,000,000 readings or 48 hours of data. Comfort and air-quality readings are typically updated approximately every 10 minutes.

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. Each request can cover up to one hour, and the rolling history contains up to the most recent 1,000,000 updates or 24 hours of data.

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. The previous day's data becomes available at approximately 6 am the following day in the building's local time.

Interval	Maximum range per request	Default filtering
Per minute	1 day	None
Per five minutes	1 day	None
Per hour	31 days	Excludes walk-bys
Per day	365 days	Excludes walk-bys and out-of-hours activity

Requests are scoped to a building and paged with a maximum page size of 100,000 records. 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.

Data is available with an approximate 15-minute delay. A request can aggregate a maximum window of 31 days. See historical heatmap for floor-plan positioning and rendering guidance.