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.

1. Get the floor plan and its scale​

Sighting coordinates are centimetres from the top-left of the floor plan, and scale is the plan's resolution in centimetres per image pixel, so divide by it to place a sighting on the image. See the coordinate system.

Open in API Explorer

Example query​

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

Example variables​

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

Example response​

{
  "data": {
    "floor": {
      "id": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204",
      "name": "Level 12",
      "floorPlanUrl": "https://cdn.xysense.io/floorplans/level-12.png",
      "scale": 1.8
    }
  }
}

2. Fetch a recent snapshot of the floor​

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": [
    "a2961d46-971f-4ce1-a66e-7ee7bdb2a204"
  ]
}

Example response​

{
  "data": {
    "floorSightingChanges": {
      "nextFrom": "2026-06-02T07:36:11.964156Z",
      "data": [
        {
          "floorId": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204",
          "headcount": 3,
          "collectedDate": "2026-06-02T07:36:11.964156Z",
          "sightings": [
            { "x": 1842, "y": 971 },
            { "x": 2510, "y": 1164 },
            { "x": 2732, "y": 1189 }
          ]
        }
      ]
    }
  }
}

3. Poll for updates 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 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": [
    "a2961d46-971f-4ce1-a66e-7ee7bdb2a204"
  ],
  "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": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204",
          "headcount": 2,
          "collectedDate": "2026-06-02T07:36:11.964156Z",
          "sightings": [
            { "x": 1842, "y": 971 },
            { "x": 2510, "y": 1164 }
          ]
        }
      ]
    }
  }
}