Docs Portal

XY Sense

XYSense

The XY Sense connector integrates with the XY Sense occupancy and indoor air quality (IAQ) sensing platform. It listens for real-time updates as occupancy changes or new sensor readings come in from the virtual devices mapped to each floor space. Using webhooks, it streams live occupancy status, headcount data, and environmental metrics directly into the Mapped graph.

Use Cases

Real-time occupancy monitoring: Track which spaces are currently occupied and their headcount to drive workplace analytics dashboards.
Indoor air quality visibility: Monitor temperature, humidity, CO₂, TVOC, particulate matter, noise, light, and barometric pressure to ensure healthy and comfortable environments.
Space utilization analysis: Aggregate historical occupancy and environmental data to identify underused or overcrowded spaces and inform space planning decisions.
Occupancy & IAQ-driven automation: Use live occupancy and air quality signals as triggers for downstream building systems such as HVAC, ventilation, lighting, or cleaning schedules.

Configuration

Auth Requirements

The connector authenticates with the XY Sense Core API using an API key name and secret. The API key must have WriteExternalApi permissions enabled so the connector can register and manage webhooks.

Field	Required	Description
Api Key Name	Yes	The name of the API key issued by XY Sense. Found in the XY Sense admin portal under API key management.
Api Secret	Yes	The secret associated with the API key. Provided when the API key is created in the XY Sense portal.

During configuration, the connector validates the credentials by minting a bearer token and confirming write permissions by creating and immediately deleting a test webhook.

Place Mappings

The connector fetches all available floor spaces from XY Sense and presents them for mapping to the Mapped graph hierarchy. Each row maps an XY Sense floor space to a Building → Floor → Space hierarchy.

Field	Required	Unique	Description
building.name	Yes	—	Name of the building (auto-populated from XY Sense location name)
building.address	Yes	—	Address of the building (auto-populated from XY Sense location address)
floor.name	Yes	—	Name of the floor (auto-populated from XY Sense floor name)
floor.level	Yes	—	Numeric floor level (auto-derived from floor name, e.g. "Level 3" → level 2, zero-indexed)
space.name	Yes	—	Name of the space (auto-populated from XY Sense floor space name)
space.code	No	—	Optional space code identifier
space.refId	Yes	Yes	Unique XY Sense floor space ID used to link webhook events to mapped spaces

Mapped Concepts

API to Mapped Entities

Occupancy Entities

XY Sense Concept	Mapped Entity Type	exactType	Description
Location (Building)	Building	—	Created by place mapping; the building containing the floor spaces
Floor	Floor	—	Created by place mapping; the floor within the building
Floor Space	Space	—	Created by place mapping; the physical space being monitored. Carries maxOccupancy from the XY Sense capacity value.
— (virtual)	Zone	OCCUPANCY_ZONE	An occupancy zone created as a child of the Space (hasPart). Groups the occupancy sensing device and its points.
— (virtual)	Thing	OCCUPANCY_SENSING_DEVICE	A virtual occupancy sensing device that serves the zone and is located in the space.
Occupancy Status	Point	OCCUPANCY_SENSOR	Binary occupancy status point — 0 = CurrentlyOccupied, 1 = NotOccupied
Headcount	Point	OCCUPANCY_COUNT_SENSOR	Numeric headcount point — current number of occupants in the space

IAQ (Air Quality) Entities

XY Sense Concept	Mapped Entity Type	exactType	Description
Space Sensor Installation	Thing	AIR_QUALITY_SENSING_DEVICE	A virtual air quality sensing device for each space with active IAQ sensor capabilities. Located in and serves the Space.
Temperature	Point	TEMPERATURE_SENSOR	Ambient temperature reading
Humidity	Point	HUMIDITY_SENSOR	Relative humidity reading
Ambient Light	Point	ILLUMINANCE_SENSOR	Ambient light level in lux
Relative Light	Point	ILLUMINANCE_SENSOR	Relative light level as percentage
Ambient Noise	Point	SOUND_PRESSURE_LEVEL_SENSOR	Ambient noise level in decibels
Barometric Pressure	Point	SEA_LEVEL_AIR_PRESSURE_SENSOR	Barometric pressure reading
Carbon Dioxide	Point	CO2_LEVEL_SENSOR	CO₂ concentration in parts per million
Volatile Organic Compounds	Point	TVOC_LEVEL_SENSOR	Total volatile organic compound concentration
Particulate Matter 1	Point	PM_1_LEVEL_SENSOR	PM1 particulate matter concentration
Particulate Matter 2.5	Point	PM_2_5_LEVEL_SENSOR	PM2.5 particulate matter concentration
Particulate Matter 10	Point	PM_10_LEVEL_SENSOR	PM10 particulate matter concentration

Note: IAQ capabilities are auto-discovered at provision time. Only capabilities actively reporting from a sensor are provisioned as points. Capabilities marked as "ignored" in the XY Sense configuration (at installation or floor-space level) are excluded.

Relationship summary:

The Space is part of the Floor/Building place hierarchy (managed by place mappings).
The OccupancyZone is a part of the Space (hasPart).
The OccupancySensingDevice serves the OccupancyZone (serves) and is located in the Space (hasLocation).
Both occupancy Points are attached to the OccupancySensingDevice (hasPoint) and the OccupancyZone (hasPoint).
The AirQualitySensingDevice serves and is located in the Space (serves, hasLocation).
IAQ Points are attached to the AirQualitySensingDevice (hasPoint).

Time Series Points

Occupancy Points

XY Sense Event Field	Mapped Point exactType	Datatype	Unit	Description
OccupancyStatus	OCCUPANCY_SENSOR	DOUBLE	NUM	Binary occupancy indicator. 0 = CurrentlyOccupied, 1 = NotOccupied. The valueMap field provides human-readable labels. stateTexts: ["CurrentlyOccupied", "NotOccupied"].
Headcount	OCCUPANCY_COUNT_SENSOR	DOUBLE	NUM	Current number of occupants detected in the space.

Occupancy events are sourced from XY Sense OccupancyChanges webhooks. The timestamp for the occupancy status point comes from OccupancyStatusChangeDate, and the headcount point timestamp comes from CollectedDate.

IAQ Points

XY Sense Capability	Mapped Point exactType	Datatype	Unit	Description
Temperature	TEMPERATURE_SENSOR	DOUBLE	DEG_C	Ambient temperature in degrees Celsius
Humidity	HUMIDITY_SENSOR	DOUBLE	PERCENT	Relative humidity percentage
Ambient Light	ILLUMINANCE_SENSOR	DOUBLE	LUX	Ambient illuminance in lux
Relative Light	ILLUMINANCE_SENSOR	DOUBLE	PERCENT	Relative light level as a percentage
Ambient Noise	SOUND_PRESSURE_LEVEL_SENSOR	DOUBLE	DeciB	Sound pressure level in decibels
Barometric Pressure	SEA_LEVEL_AIR_PRESSURE_SENSOR	DOUBLE	MilliBAR	Barometric pressure in millibars
Carbon Dioxide	CO2_LEVEL_SENSOR	DOUBLE	PPM	CO₂ concentration in parts per million
Volatile Organic Compounds	TVOC_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	Total volatile organic compound concentration in µg/m³
Particulate Matter 1	PM_1_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM1 particulate matter in µg/m³
Particulate Matter 2.5	PM_2_5_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM2.5 particulate matter in µg/m³
Particulate Matter 10	PM_10_LEVEL_SENSOR	DOUBLE	MicroGM-PER-M3	PM10 particulate matter in µg/m³

IAQ events are sourced from XY Sense SpaceSensorReadings webhooks. Each reading carries a CollectedAt timestamp indicating when the measurement was taken by the sensor.

Sample Code

Query all spaces with their occupancy and IAQ devices

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  spaces(filter: {connectedDataSourceId: {eq: "your-connector-Id"}}) {
    id
    name
    exactType
    id
    name
    maxOccupancy
    exactType
    isLocationOf {
      ... on Thing {
        id
        name
        exactType
        isVirtual
        serves {
          ... on Zone {
            id
            name
            exactType
          }
        }
        hasPoint {
          id
          name
          exactType
          datatype
          unit {
            id
          }
        }
      }
    }
  }
}

Query occupancy zones with their points and latest time series

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  zones(filter: {connectedDataSourceId: {eq: "your-connector-Id"}}) {
    id
    name
    exactType
    isServedBy {
      id
      name
      exactType
      isVirtual
    }
    hasPoint {
      id
      name
      exactType
      datatype
      unit {
        id
      }
      series(latest: true) {
        value {
          int64Value
        }
        timestamp
        ingestionTime
      }
    }
  }
}

Query IAQ devices with their sensor points and latest time series

Request ResponseCopy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  things(
    filter: {connectedDataSourceId: {eq: "CONY6QnVTHmicqhVKtwcVrpWe"}, and: {exactType: {eq: "Air_Quality_Sensing_Device"}}}
  ) {
    id
    name
    exactType
    isVirtual
    hasLocation {
      ... on Space {
        id
        name
      }
    }
    hasPoint {
      id
      name
      exactType
      datatype
      unit {
        id
      }
      series(latest: true) {
        value {
          float64Value
        }
        timestamp
        ingestionTime
      }
    }
  }
}

Graph Diagrams

Occupancy

Diagram of XY Occupancy Sensor model. Building hasPart Floor hasPart Space, which isLocationOf Occupancy Sensing Device. The Occupancy Sensing Device serves Zone, which hasPart the earlier Space. Occupancy Sensing Device hasPoint Occupancy Sensor, Zone hasPoint the same Occupancy Sensor, and hasPoint Occupancy Count Sensor.

IAQ

Diagram of XY IAQ model. Building hasPart Floor hasPart Space, which isLocationOf Air Quality Sensing Device. This device hasPoint several Points: Temperature Sensor, Humidity Sensor, CO2 Level Sensor, TVOC Level Sensor, Illuminance Sensor, Sound Pressure Level Sensor, PM 1 Level Sensor, PM 2 5 Level Sensor, PM 10 Level Sensor.