Skip to main content

Floor sightings polling

Use floor sightings polling when you need XY coordinates for observed people on a floor.

Requires the Sightings API feature

The Sightings 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.

Fetch floor information​

Open in API Explorer

Example query​

query SightingFloor($floorId: ID!) {
  floor(id: $floorId) {
    id
    name
    floorPlanUrl
    scale
  }
}

Example variables​

{
  "floorId": "floor-l12"
}

Example response​

{
  "data": {
    "floor": {
      "id": "floor-l12",
      "name": "Level 12",
      "floorPlanUrl": "https://cdn.xysense.io/floorplans/floor-l12.png",
      "scale": 1.8
    }
  }
}

Fetch recent floor sightings​

If you omit from, the API returns the last minute for each matching floor.

Open in API Explorer

Example query​

query RecentFloorSightings($floorIds: [ID!]) {
  floorSightingChanges(floorIds: $floorIds, includeLatest: true) {
    nextFrom
    data {
      floorId
      headcount
      collectedDate
      sightings
    }
  }
}

Example variables​

{
  "floorIds": [
    "floor-l12"
  ]
}

Example response​

{
  "data": {
    "floorSightingChanges": {
      "nextFrom": "2026-06-02T07:36:11.964156Z",
      "data": [
        {
          "floorId": "floor-l12",
          "headcount": 3,
          "collectedDate": "2026-06-02T07:36:11.964156Z",
          "sightings": [
            { "x": 1842, "y": 971 },
            { "x": 2510, "y": 1164 },
            { "x": 2732, "y": 1189 }
          ]
        }
      ]
    }
  }
}

Fetch floor sightings updates​

Open in API Explorer

Example query​

query FloorSightingUpdates($floorIds: [ID!], $from: Date!, $to: Date!) {
  floorSightingChanges(floorIds: $floorIds, from: $from, to: $to, includeLatest: false) {
    from
    to
    nextFrom
    data {
      floorId
      headcount
      collectedDate
      sightings
    }
  }
}

Example variables​

{
  "floorIds": [
    "floor-l12"
  ],
  "from": "2026-06-02T07:30:00Z",
  "to": "2026-06-02T07:40:00Z"
}

Example response​

{
  "data": {
    "floorSightingChanges": {
      "from": "2026-06-02T07:30:00Z",
      "to": "2026-06-02T07:40:00Z",
      "nextFrom": "2026-06-02T07:36:11.964156Z",
      "data": [
        {
          "floorId": "floor-l12",
          "headcount": 2,
          "collectedDate": "2026-06-02T07:36:11.964156Z",
          "sightings": [
            { "x": 1842, "y": 971 },
            { "x": 2510, "y": 1164 }
          ]
        }
      ]
    }
  }
}

Notes​

  • Floor-sighting payload coordinates are in centimeters from the top-left of the floor plan.
  • The floor scale field is the plan's resolution in centimetres per image pixel, so divide coordinates by scale to get image pixels. See IDs, mapping, and coordinates.
  • Persist nextFrom for incremental polling.