Skip to main content

Historical heatmap

Use historical heatmap data when you want aggregated movement density over a selected time window.

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.

1. Fetch the heatmap cells and the floor plan​

resolutionCms sets the grid cell size in centimetres: larger values return fewer, coarser cells. The maximum aggregation window, and how far behind live heatmaps run, are in Limits and retention.

Open in API Explorer

Example query​

query FloorHeatmap($floorId: ID!, $from: Date!, $to: Date!, $resolutionCms: Int) {
  floor(id: $floorId) {
    id
    name
    floorPlanUrl
    scale
  }
  historicalHeatmap(floorId: $floorId, from: $from, to: $to, resolutionCms: $resolutionCms) {
    from
    to
    center
    weight
  }
}

Example variables​

{
  "floorId": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-01T23:59:59Z",
  "resolutionCms": 100
}

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
    },
    "historicalHeatmap": [
      {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-06-01T23:59:59Z",
        "center": {
          "x": 1842,
          "y": 971
        },
        "weight": 74
      },
      {
        "from": "2026-06-01T00:00:00Z",
        "to": "2026-06-01T23:59:59Z",
        "center": {
          "x": 2510,
          "y": 1164
        },
        "weight": 41
      }
    ]
  }
}

2. Convert cell centres to image pixels​

The essential conversion is from centimetres in the API response to pixels in the displayed floor plan. scale is the plan's resolution in centimetres per image pixel, so divide by it (see the coordinate system):

const heatmapPoints = response.data.historicalHeatmap.map((cell) => ({
  x: cell.center.x / response.data.floor.scale,
  y: cell.center.y / response.data.floor.scale,
  value: cell.weight,
}))

3. Render the overlay​

  • Load the floor plan from floor.floorPlanUrl.
  • weight is an integer representing accumulated activity in the cell. Normalise by the maximum weight in the response when your heatmap library expects a 0 to 1 intensity.
  • Keep the floor plan and heatmap request scoped to the same floor and time window.