API Reference
WS detail/list (heatmap)

Heatmaps

Spatial heatmaps — path, linger, entry, exit, and interaction patterns.

Returns spatial heatmaps showing where visitors went, lingered, entered, exited, and interacted inside a location. Returned via the detail/list route with returnEntityType: "heatmap".

Body parameters

Standard detail request envelope. Set returnEntityType: "heatmap" and provide a filter object.

Required filter fields

FieldTypeDescription
startstring (ISO 8601)Inclusive start timestamp
endstring (ISO 8601)Inclusive end timestamp
heatmapTypestring[]Array of one or more: path, linger, entry, exit, lingerPeopleCount, lingerAverageTime, lingerAccumulatedTime, interaction

Optional filter fields

FieldTypeDescription
rolesstring[]Restrict to specific role(s)
agesstring[]Restrict to specific age bucket(s)
gendersstring[]Restrict to specific gender(s)
taxonomystringRestrict to a zone path

Example request

{
  "action": "detail",
  "data": {
    "id": "req-hm-001",
    "route": "detail/list",
    "body": {
      "returnEntityType": "heatmap",
      "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
      "entityType": "location",
      "filter": {
        "start": "2024-04-01T00:00:00.000Z",
        "end": "2024-04-07T23:59:59.000Z",
        "heatmapType": ["path", "linger"]
      }
    }
  }
}

Example response

req-hm-001|0|0|[
  {
    "organisation_id": "64a1b2c3d4e5f6a7b8c9d0e2",
    "location_id": "64a1b2c3d4e5f6a7b8c9d0e3",
    "recording_id": "64a1b2c3d4e5f6a7b8c9d0e4",
    "url": "https://heatmaps.auravisionlabs.com/<signed-key>",
    "created": "2024-04-01T00:15:00.000",
    "local_time": "2024-04-01T01:15:00.000",
    "age": "25-34",
    "gender": "female",
    "role": "customer",
    "heatmap_type": "path"
  },
  {
    "organisation_id": "64a1b2c3d4e5f6a7b8c9d0e2",
    "location_id": "64a1b2c3d4e5f6a7b8c9d0e3",
    "recording_id": "64a1b2c3d4e5f6a7b8c9d0e4",
    "url": "https://heatmaps.auravisionlabs.com/<signed-key>",
    "created": "2024-04-01T00:15:00.000",
    "local_time": "2024-04-01T01:15:00.000",
    "age": "25-34",
    "gender": "female",
    "role": "customer",
    "heatmap_type": "linger"
  }
]

Heatmap images are referenced by short-expiry signed URL. Fetch them directly with GET; don’t persist the URL.