How sensors map to spaces

If you have integrated with occupancy hardware before, you probably expect to ask a sensor for its state: one sensor covers one desk or one room, you read it, and that is the occupancy. That is how a PIR sensor works.

XY Sense area sensors work differently. There is no direct relationship between an area sensor and a space: occupancy is measured across the whole floor and then attributed to each space. Understanding that upfront makes the rest of the API fit together, and it is worth knowing before you model your side.

What area sensors actually produce

An area sensor detects people as anonymous positions within its field of view. It does not know what a desk is, which room it is looking at, or where one space ends and the next begins.

A floor is covered by however many sensors it takes, and their coverage overlaps. One person standing in an overlap is seen by more than one sensor. So detections are not usable as-is:

1. Sensors detect people as positions.
2. XY Sense stitches those detections together into a single picture of the floor, deduplicating people seen by more than one sensor as it goes.
3. Space shapes are overlaid on that picture, and the people inside each shape are counted.
4. That count, and how recently it changed, is the occupancy for that space.

This is why the API exposes floor sightings rather than sensor detections: by the time data reaches you, per-sensor detections have already been merged into one floor-level view with a single headcount. There is no endpoint for "what did sensor X see", because that is an intermediate state rather than an answer.

The consequences worth designing around

• You cannot query occupancy for an area sensor, and the schema reflects that: AreaSensorInstallation exposes floor and floorLocation, but no floor spaces. The omission is deliberate, not missing functionality.
• Occupancy is a property of a space, not of a sensor. Join everything on floorSpaceId. Any integration logic keyed to a sensor identity will not survive an install change.
• Spaces can change without sensors changing. Redrawing a space boundary, splitting a room into two zones, or retiring a desk changes occupancy immediately with no hardware change at all. Equally, sensors can be added, moved, or swapped without changing which spaces exist. Refresh your cached space reference data on a schedule and treat an unknown floorSpaceId as a signal to refresh.
• Sensor health is not space health. One offline area sensor degrades coverage across part of a floor, it does not switch one space off. Do not map a sensor's connection state onto a space's occupancy in your UI. See sensor connection status.
• Do not rebuild occupancy from sightings yourself. You can read floor sightings and test them against space polygons, and it will look like it works, but you will be reimplementing the space-overlay step without the filtering and state model that occupancy applies. Use the occupancy dataset and keep sightings for spatial views.

How each sensor type relates to spaces

The "no space association" rule is specific to area sensors. The three sensor types each relate to spaces in their own way:

Sensor type	Associated with spaces?	How it contributes to occupancy
Area sensor	No. Positioned on a floor, with no floor-space association at all	Detections are stitched and deduplicated, then spaces are overlaid
Entry sensor	Yes, indirectly. Its entries are associated with floor spaces	Directional movement through an entry adds to or subtracts from a count
Space sensor	Yes, directly. An installation is associated with one or more spaces	Reports readings for a space, which can include an occupancy capability

A space sensor maps most directly to a single space, and even so its readings are a separate dataset from occupancy.

occupancySource tells you which method produced a value

An Occupancy record carries an occupancySource, which reports how that value was arrived at: Area, Entry, Space, Manual, or Unknown. A floor equipped with more than one type of sensing can therefore produce occupancy for different spaces by different methods.

Treat it as diagnostic context rather than something to branch your integration on. The headcount and status mean the same thing whichever source produced them, and a space's source can change if the hardware on that floor changes.

Where to go next

• How occupancy is determined for the state model applied to these counts, and why analytics figures differ from live ones.
• Available data for the sensor and installation fields.
• Joining data to your own system for the floor plan coordinate system that positions and space shapes share.