# Heatmap
The **Butlr Heatmap API** provides a powerful way to visualize occupancy patterns across physical spaces. This feature generates a grid-based representation of detection density, allowing you to identify high-traffic areas, understand space utilization patterns, and make data-driven decisions about space optimization.
## Overview
The heatmap functionality maps normalized sensor coordinates to physical space with configurable grid resolution, providing an accurate representation of occupancy patterns. The API returns data in a structured format that represents occupancy grid cells, making it easy to visualize where people spend time in your spaces.
{% hint style="success" %}
**Key Features**
1. **Physical Space Mapping:** Proper dimensions in meters with accurate spatial representation
2. **Configurable Grid Resolution:** Choose from 0.25m, 0.5m, or 1.0m grid sizes
3. **Center-point Based Grid:** Each cell is represented by its center point coordinates
4. **Sparse Grid Representation:** Only non-empty cells are returned by default
5. **Optimized Performance:** Efficient processing of large detection datasets
**Important Note:** There is currently a 7-day limit to the time range that can be queried in the heatmap API. For longer periods, you'll need to make multiple queries and combine the results.
{% endhint %}
***
### **Example Query**
The following example demonstrates how to retrieve **heatmap data** for a floor using the Detections API.
**POST** `https://api.butlr.io/v3/detections`
```json
// POST https://api.butlr.io/v3/detections
{
"data_types": ["heatmap_v2"],
"filter": {
"space_id": "space_2qfeX6pnfGCeD4r49CtSJqYq456",
"start": "2024-01-01T00:00:00Z",
"stop": "2024-01-08T00:00:00Z",
"omit_empty_value": true
},
"window": {
"heatmap_v2_options": {
"grid_resolution": 0.5,
"heatmap_type": "occupancy",
"normalize": false
}
}
}
```
***
### **Key Parameters**
1. **Data Types:**
* **`"data_types": ["heatmap_v2"]`**: Specifies that we want heatmap v2 data.
2. **Filter Parameters:**
* **`"space_id": "space_XXXX"`**: Filters the query to the specific floor (replace `space_XXXX` with the floor ID).
* **`"start": "2024-01-01T00:00:00Z"`**: The start time of the query period.
* **`"stop": "2024-01-08T00:00:00Z"`**: The end time of the query period (maximum 7 days from start).
* **`"omit_empty_value": true`**: Whether to omit cells with zero detections in the response.
3. **Window Parameters:**
* **`"grid_resolution": 0.5`**: Specifies the grid cell size in meters (0.25, 0.5, or 1.0).
* **`"heatmap_type": "occupancy"`**: The type of heatmap (currently only "occupancy" is supported).
* **`"normalize": false`**: Whether to normalize values (0-1).
***
### **Response Format**
The API returns data in a structured JSON format that represents the occupancy grid cells:
```json
{
"heatmap_v2": {
"array_cells": [
[14.75, 35.25, 64], // [x, y, value] format
[47.5, 13.5, 46332],
[0.5, 19.5, 249],
// Additional cells...
],
"metadata": {
"type": "occupancy", // Type of heatmap
"resolution": 0.5, // Grid cell size in meters
"total_detections": 18609968, // Total number of detections
"max_value": 1410752, // Maximum detection count in any cell
"bounds": {
"min_x": -6.5,
"max_x": 57.5,
"min_y": -3.5,
"max_y": 35.5
}
}
}
}
```
Each cell in the `array_cells` array contains:
* Position \[0]: X-coordinate of the cell center (in meters)
* Position \[1]: Y-coordinate of the cell center (in meters)
* Position \[2]: Detection count/value for that cell
The `metadata` provides important context:
* `bounds`: Physical boundaries of the heatmap area (min/max coordinates)
* `resolution`: Size of each grid cell in meters
* `max_value`: Maximum detection count in any single cell
* `total_detections`: Sum of all detection counts across all cells
* `type`: The type of heatmap (currently only "occupancy" is supported)
***
### **Customizing Your Queries**
* **Grid Resolution:**\
Adjust `"grid_resolution": 0.5` to other values like `0.25` or `1.0` depending on the level of detail needed.
* **Time Range:**\
Modify `"start"` and `"stop"` to align with your analysis period. Longer time ranges will show cumulative patterns over time.
* **Include Empty Cells:**\
Set `"omit_empty_value": false` in the filter to include cells with zero detections in the response.
* **Normalization:**\
Set `"normalize": true` to normalize values between 0 and 1, which can be useful for visualization.
{% hint style="info" %}
**Performance Note:** The heatmap API is optimized for efficient processing of large datasets. Performance is primarily determined by the number of detections processed rather than the time range queried.
{% endhint %}
## Advanced Usage
### Visualizing Heatmap Data
Heatmap data is typically visualized as a color gradient overlaid on a floor plan, with color intensity indicating the relative number of detections in each grid cell. Common visualization approaches include:
1. **Color Gradient:** Using a color scale from cool (low values) to warm (high values)
2. **Opacity Mapping:** Varying the opacity based on detection count
3. **3D Surface:** Creating a 3D surface where height represents detection count
{% hint style="info" %}
**Note:** The visualizations shown above require post-processing code to render the heatmap API data. The API returns the raw data points, which need to be processed and rendered using visualization libraries such as matplotlib in Python. The checkerboard visualization demonstrates that the API only returns cells that have at least one detection (shown in white), while empty cells (shown in black) are omitted by default.
{% endhint %}
### Analyzing Occupancy Patterns
Heatmap data can provide valuable insights into space utilization:
* **Identify High-Traffic Areas:** Locate areas with the highest detection counts
* **Discover Underutilized Spaces:** Find areas with minimal activity
* **Optimize Layout:** Use occupancy patterns to inform space redesign
* **Compare Time Periods:** Analyze how space usage changes over different time periods
### Combining with Other Metrics
For a comprehensive understanding of space utilization, combine heatmap data with other metrics:
* **Room Occupancy:** Compare heatmap patterns with room-level occupancy counts
* **Traffic Data:** Correlate movement patterns with entry/exit traffic
* **Presence Time:** Analyze how long people stay in different areas
### Aggregating Data for Longer Time Periods
Due to the 7-day limit on heatmap queries, analyzing longer time periods requires multiple queries and aggregation:
1. **Split the Time Range:** Divide your analysis period into 7-day segments
2. **Make Multiple Queries:** Query each segment separately
3. **Combine Results:** Aggregate the cell values from each response
4. **Normalize if Needed:** Adjust values to account for different time periods
This approach allows you to analyze occupancy patterns over weeks, months, or even longer periods while respecting the API's time range limitations.
{% hint style="info" %}
For real-time occupancy data, refer to the Real-time Occupancy documentation.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.butlr.io/historical-occupancy/reporting-api-overview/heatmap.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.