Skip to main content

Space sensor readings polling

Use this flow for comfort, air quality, and sensor-derived occupancy measurements from space sensors.

Requires the Space Sensor Readings API feature

The Space Sensor Readings API feature is enabled by XY Sense per organisation and can vary per building and floor. If your queries return an access-disabled error, your XY Sense representative can enable it. See Feature enablement.

1. Discover which capabilities your sensors report​

Open in API Explorer

Example query​

query SpaceSensorCapabilities {
  spaceSensorCapabilities {
    id
    name
    description
    unit
  }
}

Example response​

{
  "data": {
    "spaceSensorCapabilities": [
      {
        "id": "9bbebc44-654a-4496-a055-5a892008a94d",
        "name": "Temperature",
        "description": "Ambient temperature",
        "unit": "degrees Celsius"
      },
      {
        "id": "47c873e6-3c60-41f8-9d17-96e5639b3bde",
        "name": "Humidity",
        "description": "Relative humidity",
        "unit": "percent"
      }
    ]
  }
}

2. Read the latest values​

If you omit from, the API returns the latest readings for each matching space sensor.

Open in API Explorer

Example query​

query LatestSpaceSensorReadings($floorIds: [ID!]) {
  spaceSensorReadings(floorIds: $floorIds, includeLatest: true, comfortOnly: false) {
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

{
  "floorIds": [
    "a2961d46-971f-4ce1-a66e-7ee7bdb2a204"
  ]
}

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "nextFrom": "2026-06-02T07:36:11.964156Z",
      "data": [
        {
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "capabilityName": "Temperature",
          "value": "22.4",
          "collectedAt": "2026-06-02T07:36:11.964156Z"
        },
        {
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "capabilityName": "Humidity",
          "value": "48.2",
          "collectedAt": "2026-06-02T07:36:11.964156Z"
        }
      ]
    }
  }
}

3. Poll for changes with a moving cursor​

Persist nextFrom and send it as the next request's from. Request windows and retention are in Limits and retention.

Open in API Explorer

Example query​

query SpaceSensorReadingChanges($floorIds: [ID!], $from: Date!, $to: Date!) {
  spaceSensorReadings(floorIds: $floorIds, from: $from, to: $to, includeLatest: false, comfortOnly: false) {
    from
    to
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

{
  "floorIds": [
    "a2961d46-971f-4ce1-a66e-7ee7bdb2a204"
  ],
  "from": "2026-06-02T07:00:00Z",
  "to": "2026-06-02T08:00:00Z"
}

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "from": "2026-06-02T06:00:00Z",
      "to": "2026-06-02T07:00:00Z",
      "nextFrom": "2026-06-02T06:50:12.331245Z",
      "data": [
        {
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "capabilityName": "Temperature",
          "value": "22.4",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        },
        {
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "capabilityName": "Humidity",
          "value": "48.2",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        }
      ]
    }
  }
}

Finding which spaces a sensor serves​

Use floor-space metadata when you need to render or label which spaces a sensor installation serves.

Open in API Explorer

Example query​

query SpaceSensorAssociations($floorId: ID!) {
  floor(id: $floorId) {
    id
    name
    floorSpaces {
      id
      name
      spaceSensorInstallations {
        id
        name
        spaceSensorId
      }
    }
    spaceSensorInstallations {
      id
      name
      spaceSensorId
      floorSpaces {
        id
        name
      }
      ignoredCapabilities {
        id
        name
      }
    }
  }
}

Example variables​

{
  "floorId": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204"
}

Example response​

{
  "data": {
    "floor": {
      "id": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204",
      "name": "Level 12",
      "floorSpaces": [
        {
          "id": "6e0b4c85-1f27-4d93-a8b5-3c7d9e0f1a24",
          "name": "Room 12A",
          "spaceSensorInstallations": [
            {
              "id": "9c1d5e83-2b47-4f60-a915-6d8e0f1a2b37",
              "name": "Room 12A Sensor",
              "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46"
            }
          ]
        }
      ],
      "spaceSensorInstallations": [
        {
          "id": "9c1d5e83-2b47-4f60-a915-6d8e0f1a2b37",
          "name": "Room 12A Sensor",
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "floorSpaces": [
            {
              "id": "6e0b4c85-1f27-4d93-a8b5-3c7d9e0f1a24",
              "name": "Room 12A"
            }
          ],
          "ignoredCapabilities": [
            {
              "id": "47c873e6-3c60-41f8-9d17-96e5639b3bde",
              "name": "Humidity"
            }
          ]
        }
      ]
    }
  }
}

Narrowing the poll to specific sensors​

Filter by sensor when a receiver only needs part of the estate. Use comfortOnly: true when you want comfort and air-quality readings without occupancy-style sensor output.

Open in API Explorer

Example query​

query FilteredSpaceSensorReadingChanges($spaceSensorIds: [ID!], $from: Date!, $to: Date!) {
  spaceSensorReadings(spaceSensorIds: $spaceSensorIds, from: $from, to: $to, includeLatest: false) {
    nextFrom
    data {
      spaceSensorId
      capabilityName
      value
      collectedAt
    }
  }
}

Example variables​

{
  "spaceSensorIds": [
    "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
    "sensor-02"
  ],
  "from": "2026-06-02T07:00:00Z",
  "to": "2026-06-02T08:00:00Z"
}

Example response​

{
  "data": {
    "spaceSensorReadings": {
      "nextFrom": "2026-06-02T06:50:12.331245Z",
      "data": [
        {
          "spaceSensorId": "3f7a2c19-8d64-4b05-9e13-7a2b5c8d0e46",
          "capabilityName": "CarbonDioxide",
          "value": "641",
          "collectedAt": "2026-06-02T06:50:12.331245Z"
        }
      ]
    }
  }
}