Heatmap | ArcGIS Maps SDK for JavaScript

Fatal car crashes in 2017 represented as a continuous heatmap. Areas with higher concentrations of crashes are yellow.

What is a heatmap?

A Heatmap renders point features as a raster surface, emphasizing areas with a higher density of points along a continuous color ramp.

Why are heatmaps useful?

Heatmaps can be used as an alternative to clustering, opacity, and bloom to visualize overlapping point features. Unlike these alternative techniques for visualizing density, you can use a heatmap to weight the density of points based on a data value. This may reveal a different pattern than density calculated using location alone.

Location-only heatmap	Data-weighted heatmap
Figure : Density of car crashes that resulted in a fatality (2017). Yellow areas indicate the highest density of crash incidents.	Figure : Density of fatal car crashes involving drunk drivers (2017). Yellow areas indicate the highest density of crash incidents that involved drunk drivers.

How a heatmap works

Heatmaps are created by setting a HeatmapRenderer instance to the renderer property of the layer. The HeatmapRenderer has several key properties. The radius determines the area of influence surrounding a point. For example, if you set a radius of 10 pixels, each pixel within 10 pixels of a single point will be assigned a density value. The pixel directly on top of the point will have the highest density. Smaller density values are assigned to pixels surrounding the point inversely proportional to the distance from the point. Pixels on the screen that fall outside that 10-pixel radius of all points will have a density value of 0.

The density value of each pixel accumulates based on its proximity to multiple points. For example, a pixel within 10px of 10 points, will have a higher density value than pixels within 10x of only one point.

The colorStops in the renderer determine how to colorize pixels based on the ratio of a pixel’s density value to the maxDensity (i.e. pixel density / maxDensity). Pixels with a density value at or above the maxDensity have a density ratio of 1 and should be assigned the brightest color since these represent the hottest areas. The larger the maxDensity, the fewer hot spots will exist in the map.

Examples

Location heatmap

To create a heatmap, you must apply a HeatmapRenderer to a point layer. Set the renderer properties using the guidelines outlined above. Open this example in CodePen and adjust the radius and maxDensity to see how these properties impact the heatmap.

Density of car crashes that resulted in a fatality (2017). Yellow areas indicate the highest density of crash incidents.

ArcGIS JS API


37 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>Fatal car crashes</title>
7

8
    <style>
9
      html,
10
      body,
11
      #viewDiv {
12
        height: 100%;
13
        margin: 0;
14
      }
15
    </style>
16

17
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/dark/main.css" />
18
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
19
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
20

21
    <script type="module">
22
      const [WebMap, FeatureLayer, MapView, Legend] = await $arcgis.import([
23
        "@arcgis/core/WebMap.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/views/MapView.js",
26
        "@arcgis/core/widgets/Legend.js",
27
      ]);
28

29
      const url =
30
        "https://services1.arcgis.com/4yjifSiIG17X0gW4/arcgis/rest/services/FatalAccidents2017/FeatureServer";
31

32
      const layer = new FeatureLayer({
33
        title: "Fatal car accidents (2017)",
34
        url,
35
      });
36

37

38
      const colors = [
39
        "rgba(115, 0, 115, 0)",
40
        "#820082",
41
        "#910091",
42
        "#a000a0",
43
        "#af00af",
44
        "#c300c3",
45
        "#d700d7",
46
        "#eb00eb",
47
        "#ff00ff",
48
        "#ff58a0",
49
        "#ff896b",
50
        "#ffb935",
51
        "#ffea00",
52
      ];
53

54
      layer.renderer = {
55
        type: "heatmap",
56
        colorStops: [
57
          { color: colors[0], ratio: 0 },
58
          { color: colors[1], ratio: 0.083 },
59
          { color: colors[2], ratio: 0.166 },
60
          { color: colors[3], ratio: 0.249 },
61
          { color: colors[4], ratio: 0.332 },
62
          { color: colors[5], ratio: 0.415 },
63
          { color: colors[6], ratio: 0.498 },
64
          { color: colors[7], ratio: 0.581 },
65
          { color: colors[8], ratio: 0.664 },
66
          { color: colors[9], ratio: 0.747 },
67
          { color: colors[10], ratio: 0.83 },
68
          { color: colors[11], ratio: 0.913 },
69
          { color: colors[12], ratio: 1 },
70
        ],
71
        radius: 18,
72
        maxDensity: 0.04625,
73
        minDensity: 0,
74
      };
36 collapsed lines
75

76

77
      const map = new WebMap({
78
        basemap: {
79
          portalItem: {
80
            id: "466f3f43c231453c938c6776777b89e2",
81
          },
82
        },
83
        layers: [layer],
84
      });
85

86
      const view = new MapView({
87
        container: "viewDiv",
88
        center: [-117.79621, 33.91474],
89
        scale: 1155581,
90
        constraints: {
91
          snapToZoom: false,
92
          minScale: 4622324,
93
          maxScale: 1155500,
94
        },
95
        map,
96
      });
97

98
      view.ui.add(
99
        new Legend({
100
          view,
101
        }),
102
        "top-right",
103
      );
104
    </script>
105
  </head>
106

107
  <body>
108
    <div id="viewDiv"></div>
109
  </body>
110
</html>

Data-weighted heatmap

This example modifies the previous heatmap to weight the surface by a data variable. The crashes layer used in this example has an attribute that tallies the number of drunk drivers involved in the incident. We can visualize where more drunk drivers are involved in fatal accidents by weighting by that field.

When a field is specified, each pixel’s density is multiplied by the data value, so you need to adjust the maxDensity accordingly.

Density of car crashes involving drunk drivers that resulted in a fatality (2017). Yellow areas indicate the highest density of crash incidents.

ArcGIS JS API


37 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>Fatal car crashes</title>
7

8
    <style>
9
      html,
10
      body,
11
      #viewDiv {
12
        height: 100%;
13
        margin: 0;
14
      }
15
    </style>
16

17
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/dark/main.css" />
18
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
19
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
20

21
    <script type="module">
22
      const [WebMap, FeatureLayer, MapView, Legend] = await $arcgis.import([
23
        "@arcgis/core/WebMap.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/views/MapView.js",
26
        "@arcgis/core/widgets/Legend.js",
27
      ]);
28

29
      const url =
30
        "https://services1.arcgis.com/4yjifSiIG17X0gW4/arcgis/rest/services/FatalAccidents2017/FeatureServer";
31

32
      const layer = new FeatureLayer({
33
        title: "Fatal car accidents involving drinking (2017)",
34
        url,
35
      });
36

37

38
      const colors = [
39
        "rgba(115, 0, 115, 0)",
40
        "#820082",
41
        "#910091",
42
        "#a000a0",
43
        "#af00af",
44
        "#c300c3",
45
        "#d700d7",
46
        "#eb00eb",
47
        "#ff00ff",
48
        "#ff58a0",
49
        "#ff896b",
50
        "#ffb935",
51
        "#ffea00",
52
      ];
53

54
      layer.renderer = {
55
        type: "heatmap",
56

57
        field: "Number_of_Drinking_Drivers",
58

59
        colorStops: [
60
          { color: colors[0], ratio: 0 },
61
          { color: colors[1], ratio: 0.083 },
62
          { color: colors[2], ratio: 0.166 },
63
          { color: colors[3], ratio: 0.249 },
64
          { color: colors[4], ratio: 0.332 },
65
          { color: colors[5], ratio: 0.415 },
66
          { color: colors[6], ratio: 0.498 },
67
          { color: colors[7], ratio: 0.581 },
68
          { color: colors[8], ratio: 0.664 },
69
          { color: colors[9], ratio: 0.747 },
70
          { color: colors[10], ratio: 0.83 },
71
          { color: colors[11], ratio: 0.913 },
72
          { color: colors[12], ratio: 1 },
73
        ],
74
        radius: 18,
75

76
        maxDensity: 0.00875,
77

78
        minDensity: 0,
79
      };
36 collapsed lines
80

81

82
      const map = new WebMap({
83
        basemap: {
84
          portalItem: {
85
            id: "466f3f43c231453c938c6776777b89e2",
86
          },
87
        },
88
        layers: [layer],
89
      });
90

91
      const view = new MapView({
92
        container: "viewDiv",
93
        center: [-117.79621, 33.91474],
94
        scale: 1155581,
95
        constraints: {
96
          snapToZoom: false,
97
          minScale: 4622324,
98
          maxScale: 1155500,
99
        },
100
        map,
101
      });
102

103
      view.ui.add(
104
        new Legend({
105
          view,
106
        }),
107
        "top-right",
108
      );
109
    </script>
110
  </head>
111

112
  <body>
113
    <div id="viewDiv"></div>
114
  </body>
115
</html>

Scale-dependent Heatmap

Dynamic heatmaps are only visually appropriate at a few scale levels. As the user zooms out, the heatmap will always appear hotter. As the user zooms in, the heatmap will appear colder. To prevent the user from viewing a heatmap that is too hot, you can set a minScale on the layer or as a view constraint.

As the user zooms in, the heatmap becomes irrelevant. Therefore, you should set a watch on the view to toggle the layer’s heatmap to a simple renderer representing individual point locations.

Density of crimes classified as fraud in San Diego California. Zoom in and out on the map to view how the developer can restrict the user from seeing a heatmap that is too hot or too cold. As the user zooms in, the heatmap toggles off and displays the point locations as a simple renderer.

Set a constraint on map view scale to avoid hot heatmaps


35 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>Create a scale-dependent visualization | Sample | ArcGIS API for JavaScript 4.21</title>
7

8
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
9
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
10
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
11

12
    <style>
13
      html,
14
      body,
15
      #viewDiv {
16
        height: 100%;
17
        margin: 0;
18
      }
19
    </style>
20

21
    <script type="module">
22
      const [WebMap, MapView, Legend, reactiveUtils] = await $arcgis.import([
23
        "@arcgis/core/WebMap.js",
24
        "@arcgis/core/views/MapView.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/core/reactiveUtils.js",
27
      ]);
28

29
      const map = new WebMap({
30
        portalItem: {
31
          id: "559f46c1162d4a09901438d92148e53a",
32
        },
33
      });
34

35

36
      const view = new MapView({
37
        container: "viewDiv",
38
        map: map,
39
        constraints: {
40
          minScale: 1155582,
41
          snapToZoom: false,
42
        },
43
      });
48 collapsed lines
44

45

46
      view.ui.add(
47
        new Legend({
48
          view: view,
49
        }),
50
        "top-right",
51
      );
52

53
      view.when().then(() => {
54
        // When the view is ready, clone the heatmap renderer
55
        // from the only layer in the web map
56

57
        const layer = view.map.layers.getItemAt(0);
58
        const heatmapRenderer = layer.renderer.clone();
59

60
        // The following simple renderer will render all points as simple
61
        // markers at certain scales
62

63
        const simpleRenderer = {
64
          type: "simple",
65
          symbol: {
66
            type: "simple-marker",
67
            color: "#c80000",
68
            size: 5,
69
          },
70
        };
71

72
        // When the scale is larger than 1:72,224 (zoomed in passed that scale),
73
        // then switch from a heatmap renderer to a simple renderer. When zoomed
74
        // out beyond that scale, switch back to the heatmap renderer
75

76

77
        reactiveUtils.watch(
78
          () => view.scale,
79
          () => {
80
            layer.renderer = view.scale <= 72224 ? simpleRenderer : heatmapRenderer;
81
          },
82
        );
83

84
      });
85
    </script>
86
  </head>
87

88
  <body>
89
    <div id="viewDiv"></div>
90
  </body>
91
</html>

Switch to a location renderer after zooming beyond a scale threshold


76 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>Create a scale-dependent visualization | Sample | ArcGIS API for JavaScript 4.21</title>
7

8
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
9
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
10
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
11

12
    <style>
13
      html,
14
      body,
15
      #viewDiv {
16
        height: 100%;
17
        margin: 0;
18
      }
19
    </style>
20

21
    <script type="module">
22
      const [WebMap, MapView, Legend, reactiveUtils] = await $arcgis.import([
23
        "@arcgis/core/WebMap.js",
24
        "@arcgis/core/views/MapView.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/core/reactiveUtils.js",
27
      ]);
28

29
      const map = new WebMap({
30
        portalItem: {
31
          id: "559f46c1162d4a09901438d92148e53a",
32
        },
33
      });
34

35

36
      const view = new MapView({
37
        container: "viewDiv",
38
        map: map,
39
        constraints: {
40
          minScale: 1155582,
41
          snapToZoom: false,
42
        },
43
      });
44

45

46
      view.ui.add(
47
        new Legend({
48
          view: view,
49
        }),
50
        "top-right",
51
      );
52

53
      view.when().then(() => {
54
        // When the view is ready, clone the heatmap renderer
55
        // from the only layer in the web map
56

57
        const layer = view.map.layers.getItemAt(0);
58
        const heatmapRenderer = layer.renderer.clone();
59

60
        // The following simple renderer will render all points as simple
61
        // markers at certain scales
62

63
        const simpleRenderer = {
64
          type: "simple",
65
          symbol: {
66
            type: "simple-marker",
67
            color: "#c80000",
68
            size: 5,
69
          },
70
        };
71

72
        // When the scale is larger than 1:72,224 (zoomed in passed that scale),
73
        // then switch from a heatmap renderer to a simple renderer. When zoomed
74
        // out beyond that scale, switch back to the heatmap renderer
75

76

77
        reactiveUtils.watch(
78
          () => view.scale,
79
          () => {
80
            layer.renderer = view.scale <= 72224 ? simpleRenderer : heatmapRenderer;
81
          },
82
        );
9 collapsed lines
83

84
      });
85
    </script>
86
  </head>
87

88
  <body>
89
    <div id="viewDiv"></div>
90
  </body>
91
</html>

Static heatmaps

Static heatmaps allow you to persist the visual density’s of a heatmap from one scale across all scale levels. As the user zooms in and out, the heatmap will consistently show the same hot spots in the view.

As the user zooms in, the heatmap becomes irrelevant, so you may want to set a constraint on the MapView to prevent overzooming.

Density of trees in New York City (2015). Zoom in and out to observe how a static heatmap may be a more attractive solution to highlighting areas of high density.

ArcGIS JS API


49 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>NYC tree census</title>
7

8
    <style>
9
      html,
10
      body,
11
      #viewDiv {
12
        height: 100%;
13
        margin: 0;
14
      }
15
    </style>
16

17
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
18
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
19
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
20

21
    <script type="module">
22
      const [WebMap, FeatureLayer, MapView, Legend] = await $arcgis.import([
23
        "@arcgis/core/WebMap.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/views/MapView.js",
26
        "@arcgis/core/widgets/Legend.js",
27
      ]);
28

29
      const renderer = {
30
        type: "heatmap",
31
        colorStops: [
32
          { color: [133, 193, 200, 0], ratio: 0 },
33
          { color: [133, 193, 200, 0], ratio: 0.01 },
34
          { color: [133, 193, 200, 255], ratio: 0.01 },
35
          { color: [133, 193, 200, 255], ratio: 0.01 },
36
          { color: [144, 161, 190, 255], ratio: 0.0925 },
37
          { color: [156, 129, 132, 255], ratio: 0.175 },
38
          { color: [167, 97, 170, 255], ratio: 0.2575 },
39
          { color: [175, 73, 128, 255], ratio: 0.34 },
40
          { color: [184, 48, 85, 255], ratio: 0.4225 },
41
          { color: [192, 24, 42, 255], ratio: 0.505 },
42
          { color: [200, 0, 0, 255], ratio: 0.5875 },
43
          { color: [211, 51, 0, 255], ratio: 0.67 },
44
          { color: [222, 102, 0, 255], ratio: 0.7525 },
45
          { color: [233, 153, 0, 255], ratio: 0.835 },
46
          { color: [244, 204, 0, 255], ratio: 0.9175 },
47
          { color: [255, 255, 0, 255], ratio: 1 },
48
        ],
49

50
        maxDensity: 0.319,
51
        minDensity: 0,
52
        // settings for heatmap apply only to this scale
53
        // so renderer will look consistent without
54
        // dynamically updating on zoom
55

56
        referenceScale: 36111,
57

58
        radius: 6,
59
        legendOptions: {
60
          minLabel: "Low tree density",
61
          maxLabel: "High tree density",
62
        },
63
      };
41 collapsed lines
64

65

66
      const layer = new FeatureLayer({
67
        portalItem: {
68
          id: "a38dd6ef1000447b94bda500084c14c7",
69
        },
70
        popupTemplate: {
71
          title: "<i>{spc_latin}</i>",
72
          content:
73
            "<b>{spc_common}</b> in <b>{health}</b> condition located at {address}, {borough}.",
74
        },
75
        renderer,
76
        blendMode: "multiply",
77
      });
78

79
      const map = new WebMap({
80
        layers: [layer],
81
        basemap: "gray-vector",
82
      });
83

84
      const view = new MapView({
85
        container: "viewDiv",
86
        center: [-73.95697002727704, 40.626402246806926],
87
        scale: 72223,
88
        rotation: 78,
89
        map,
90
      });
91

92
      view.ui.add(
93
        new Legend({
94
          view: view,
95
        }),
96
        "top-right",
97
      );
98
    </script>
99
  </head>
100

101
  <body>
102
    <div id="viewDiv"></div>
103
  </body>
104
</html>

Faded heatmaps

Configuring a heatmap renderer with proper density values can be difficult, especially when the starting view scale is unknown. The heatmap smart mapping renderer creator helps generate a suggested heatmap given the current view scale and background color.

It also automatically fades colors from dense areas (full opacity) to sparse areas (high transparency). The fading of colors helps establish a fuzzy boundary, which is often more appropriate than a hard edge for heatmap visualizations.

Density of crimes in Chicago. Notice how this generated heatmap automatically fades colors so the boundaries become more fuzzy.

ArcGIS JS API


61 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5

6
    <title>Heatmap Renderer fade</title>
7

8
    <style>
9
      html,
10
      body,
11
      #viewDiv {
12
        height: 100%;
13
        margin: 0;
14
      }
15
    </style>
16

17
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
18
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
19
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
20

21
    <script type="module">
22
      const [WebMap, FeatureLayer, MapView, Legend, reactiveUtils, heatmapRendererCreator] =
23
        await $arcgis.import([
24
          "@arcgis/core/WebMap.js",
25
          "@arcgis/core/layers/FeatureLayer.js",
26
          "@arcgis/core/views/MapView.js",
27
          "@arcgis/core/widgets/Legend.js",
28
          "@arcgis/core/core/reactiveUtils.js",
29
          "@arcgis/core/smartMapping/renderers/heatmap.js",
30
        ]);
31

32
      const layer = new FeatureLayer({
33
        title: "Crimes",
34
        portalItem: {
35
          id: "dba30168bab24b1eb12e9402e19ac3d9",
36
        },
37
        opacity: 0.01,
38
      });
39

40
      const map = new WebMap({
41
        layers: [layer],
42
        basemap: "gray-vector",
43
      });
44

45
      const view = new MapView({
46
        container: "viewDiv",
47
        center: [-87.7051, 41.8393],
48
        scale: 263532,
49
        map,
50
      });
51

52
      view.ui.add(
53
        new Legend({
54
          view: view,
55
        }),
56
        "top-right",
57
      );
58

59
      view.when(async () => {
60
        const layerView = await view.whenLayerView(layer);
61

62
        const { renderer } = await heatmapRendererCreator.createRenderer({ layer, view });
63
        renderer.referenceScale = view.scale;
64
        layer.renderer = renderer;
14 collapsed lines
65

66
        reactiveUtils
67
          .whenOnce(() => !layerView?.updating)
68
          .then(() => {
69
            layer.opacity = 1;
70
          });
71
      });
72
    </script>
73
  </head>
74

75
  <body>
76
    <div id="viewDiv"></div>
77
  </body>
78
</html>

API support

The following table describes the geometry and view types that are suited well for each visualization technique.

	2D	Lines	Polygons	Client-side	Server-side
Clustering
Binning
Heatmap
Opacity
Bloom
Aggregation
Thinning	¹	¹	¹	²	³
Visible scale range

Full SupportPartial SupportNo Support

Feature reduction selection not supported
Only by feature reduction selection
Only by scale-driven filter

High density dataBinning High density dataOpacity

What is a heatmap?

Why are heatmaps useful?

How a heatmap works

Examples

Location heatmap

Data-weighted heatmap

Scale-dependent Heatmap

Static heatmaps

Faded heatmaps

Related samples and resources

Intro to heatmap

Create a scale-dependent visualization

Visualize points in a scene with a heatmap

Create a static heatmap

Next-Generation Heat Maps in Map Viewer: Better, faster, smoother, stronger

How to create heat maps that work at all scales

HeatmapRenderer

API support