Skip to main content

Analytics polling

Use analytics polling when you need aggregated utilisation metrics instead of raw occupancy changes.

Requires the Analytics API feature

The Analytics 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 building information​

Open in API Explorer

Example query​

query AnalyticsBuildings {
  buildings {
    id
    name
    analyticsAvailableTo
    floors(isLive: true) {
      id
      name
      scale
      floorPlanUrl
    }
  }
}

Example response​

{
  "data": {
    "buildings": [
      {
        "id": "bldg-melb-hq",
        "name": "Melbourne HQ",
        "analyticsAvailableTo": "2026-06-02T00:00:00Z",
        "floors": [
          {
            "id": "floor-l12",
            "name": "Level 12",
            "scale": 0.065,
            "floorPlanUrl": "https://cdn.xysense.io/floorplans/floor-l12.png"
          }
        ]
      }
    ]
  }
}

Fetch analytics data​

Analytics time series are available in multiple granularities. Use the interval query that matches your reporting need. This example uses hourly aggregation.

Open in API Explorer

Example query​

query OccupancyPerHour($floorId: ID!, $from: Date!, $to: Date!) {
  occupancyPerHour(floorId: $floorId, from: $from, to: $to, take: 1000) {
    items {
      floorSpaceId
      periodStartUtc
      periodStartLocal
      minOccupants
      maxOccupants
      avgOccupants
      occupiedMinutes
      occupiedHours
    }
    hasNextPage
    totalItems
  }
}

Example variables​

{
  "floorId": "floor-l12",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-02T00:00:00Z"
}

Example response​

{
  "data": {
    "occupancyPerHour": {
      "items": [
        {
          "floorSpaceId": "desk-ne-101",
          "periodStartUtc": "2026-06-01T01:00:00Z",
          "periodStartLocal": "2026-06-01T11:00:00+10:00",
          "minOccupants": 0,
          "maxOccupants": 1,
          "avgOccupants": 0.63,
          "occupiedMinutes": 38,
          "occupiedHours": 0.63
        }
      ],
      "hasNextPage": false,
      "totalItems": 1
    }
  }
}

Fetch space information​

Pull floor-space metadata so the analytics rows can be joined back to named spaces, types, and capacities.

Open in API Explorer

Example query​

query AnalyticsFloorSpaces($floorId: ID!) {
  floorSpaces(floorId: $floorId) {
    id
    name
    capacity
    spaceType {
      id
      name
      globalSpaceCategory {
        id
        name
      }
    }
  }
}

Example variables​

{
  "floorId": "floor-l12"
}

Example response​

{
  "data": {
    "floorSpaces": [
      {
        "id": "desk-ne-101",
        "name": "Desk NE-101",
        "capacity": 1,
        "spaceType": {
          "id": "space-type-desk",
          "name": "Desk",
          "globalSpaceCategory": {
            "id": "category-workstation",
            "name": "Workstation"
          }
        }
      }
    ]
  }
}

Notes​

  • Analytics queries allow up to 31 days per request.
  • Analytics are not available until approximately 6am the following day in the building's timezone.
  • Pick occupancyPerMinute, occupancyPerFiveMinutes, occupancyPerHour, or occupancyPerDay based on the resolution you need.