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.

Fetch floor plan information and heatmap data​

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": "floor-l12",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-01T23:59:59Z",
  "resolutionCms": 100
}

Example response​

{
  "data": {
    "floor": {
      "id": "floor-l12",
      "name": "Level 12",
      "floorPlanUrl": "https://cdn.xysense.io/floorplans/floor-l12.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
      }
    ]
  }
}

Plot heatmap cells on the floor plan​

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 IDs, mapping, and coordinates):

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,
}))

Display heatmap data​

  • Load the floor plan from floor.floorPlanUrl.
  • Use floor.scale to convert API coordinates into rendered image pixels.
  • 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.

Notes​

  • The maximum heatmap request window is 31 days.
  • resolutionCms sets the cell size of the heatmap grid in centimetres. Larger values return fewer, coarser cells.
  • Historical heatmap availability is delayed by roughly 15 minutes.