Binning | ArcGIS Maps SDK for JavaScript

Argo float locations aggregated at a fixed bin level of 3. Level 3 is probably more useful at regional extents, but the global view can be a nice way to show density at a higher resolution. Binning allows you to see the density of features based on a geographic grid of cells.

What is binning?

Binning aggregates data to predefined cells, effectively representing feature data as a gridded polygon layer. Typically, bins are styled with a continuous color ramp and labeled with the count of features contained by the bin. The JS API uses the public domain geohash geocoding system to create the bins.

This is an effective way to show the density of features. Unlike clustering, binning shows feature density in geographic space, not screen space.

Binning allows you to effectively visualize where features stack on top of another or are in very close proximity to each other. Use the swipe widget above to compare a layer of points with a binned version of the same data.

Why is binning useful?

Large layers can be deceptive. What appears to be just a few points can in reality be several thousand. Binning allows you to visually represent the density of features in a geographic grid of cells.

For example, the following map shows the locations of thousands of Argo floats (similar to a buoy). Regions A and B both have a high density of features, making them impossible to compare without additional help.

binning disabled

Figure : Region A and region B both have a high density of features. It is impossible to tell how many points overlap in each area.

However, when binning is enabled, the user can now clearly compare the density of both regions.

binning enabled

Figure : Binning allows the user to easily compare the density of overlapping features at a glance.

How binning works

Binning is configured on the featureReduction property of the layer. You can enable binning with minimal code by setting the featureReduction type to binning.

layer.featureReduction = {
  type: "binning"
};

Since binning does not have a default renderer, you won’t be able to see the bins without explicitly defining a renderer. The featureReduction property gives you control over many other binning properties, including the following:

fixedBinLevel - Determines the resolution of the grid (only accepts values 1-9). Larger numbers result in a higher resolution. Low numbers result in a coarse resolution.
fields - Defines how to aggregate the layer’s fields based on a statistic type.
renderer - Defines the style of the bins.
popupTemplate - Allows you to summarize data in the bin when the user clicks it.
labels - Typically used to label each bin with the number of features it contains.

Binning polylines and polygons

Binning is typically used to visualize large point layers, but may be used with any geometry type (since version 4.31). In the case of binning polyline or polygon features, the centroid of the line or polygon is used to determine the bin in which it is placed. This may lead to some features being placed in (or excluded from) unexpected bins. Because of this, special considerations should be taken when binning lines and polygons.

Tip

Use the following guidelines when binning lines or polygons:

Binning works best when features have a regular size smaller than the bin size.
The density of irregularly shaped features may be misrepresented as some features may overlap several bins.
Because binning is based on feature centroids, some features may be placed into bins that do not contain the majority of the feature.
Some areas covered by large polygons or polylines may show no bins at all.
As a guideline, small features like parcels, buildings, swimming pools, bridges, culverts, or connectors are well-suited for binning at small scales.
Large, irregularly shaped features like counties, states, or countries generally do not need to be aggregated.
Binning works best at smaller scales (when zoomed out). You should set a maxScale in the feature reduction configuration to disable binning at larger scales (when zoomed in) where features can be viewed in full fidelity.

See the Binning polylines for a good example of a binned polyline layer.

Examples

Basic binning

The following example demonstrates how to enable binning and configure the renderer, labels, and a popup for displaying the feature count inside each bin. You must select a fixedBinLevel between 1-9 when enabling binning. Choose a bin level based on the data extent. The following table describes suggested bin levels given your data extent.

Fixed bin level	Suggested data extent
1-3	Global extents.
3-5	Regional extents (e.g. countries and states).
5-7	Local communities (e.g. counties and cities).
7-9	Hyper local areas (e.g. neighborhoods and buildings).

You must also define aggregate fields to make the binning visualization meaningful. An aggregate field determines how to represent data from the underlying layer in its aggregate form (i.e. the bin). For example, to create an aggregate field for feature count inside the bin, use the count statistic type.

layer.featureReduction = {
  type: "binning",
  fixedBinLevel: 2,
  fields: [{
    name: "aggregateCount",
    statisticType: "count"
  }]
};

This can now be used in the renderer, labels, and popup for each bin. These properties are configured just as they would be on any other layer type, except they must refer to aggregate fields defined in FeatureReductionBinning.fields instead of the underlying layer’s fields. Typically, bins are styled with a continuous color visual variable as demonstrated in this example.

Argo float locations aggregated at a fixed bin level of 2. This is a great resolution for global data.


31 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
    <title>Binning - Argo float locations - level 2</title>
6

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

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

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

29
      const colors = ["#4d394d", "#6c2f68", "#901f8a", "#c700bb", "#ff33f3"];
30

31

32
      const featureReduction = {
33
        type: "binning",
34
        fixedBinLevel: 2,
35
        fields: [
36
          {
37
            name: "aggregateCount",
38
            alias: "Total count",
39
            statisticType: "count",
40
          },
41
        ],
42
        renderer: {
43
          type: "simple",
44
          symbol: {
45
            type: "simple-fill",
46
            color: [0, 255, 71, 1],
47
            outline: null,
48
            outline: {
49
              color: colors[0],
50
              width: 0,
51
            },
52
          },
53
          visualVariables: [
54
            {
55
              type: "color",
56
              field: "aggregateCount",
57
              legendOptions: {
58
                title: "Number of floats",
59
              },
60
              stops: [
61
                { value: 0, color: colors[0] },
62
                { value: 25, color: colors[1] },
63
                { value: 50, color: colors[2] },
64
                { value: 75, color: colors[3] },
65
                { value: 100, color: colors[4] },
66
              ],
67
            },
68
          ],
69
        },
78 collapsed lines
70

71
        labelsVisible: true,
72
        labelingInfo: [
73
          {
74
            minScale: 120000000,
75
            maxScale: 0,
76
            deconflictionStrategy: "none",
77
            symbol: {
78
              type: "text",
79
              color: "white",
80
              font: {
81
                family: "Noto Sans",
82
                size: 10,
83
                weight: "bold",
84
              },
85
              haloColor: colors[4],
86
              haloSize: 0.5,
87
            },
88
            labelExpressionInfo: {
89
              expression: "Text($feature.aggregateCount, '#,###')",
90
            },
91
          },
92
        ],
93
        popupEnabled: true,
94
        popupTemplate: {
95
          title: "Aggregated floats",
96
          content: "{aggregateCount} Argo floats in this area.",
97
        },
98
      };
99

100
      const layer = new FeatureLayer({
101
        blendMode: "lighten",
102
        title: "Argo floats",
103
        url: "https://www.ocean-ops.org/arcgis/rest/services/Argo/ARGOLocations/FeatureServer/1",
104
        featureReduction,
105
      });
106

107
      const map = new WebMap({
108
        basemap: {
109
          portalItem: {
110
            id: "38189d7d668c490895ed15fddcfdc7c7",
111
          },
112
        },
113
        layers: [layer],
114
      });
115

116
      const view = new MapView({
117
        container: "viewDiv",
118
        map: map,
119
        popup: {
120
          dockEnabled: true,
121
          dockOptions: {
122
            breakpoint: false,
123
          },
124
        },
125
        constraints: {
126
          snapToZoom: false,
127
        },
128
        scale: 140_000_000,
129
      });
130
      view.highlights.items[0].fillOpacity = 0.25;
131
      view.highlights.items[0].color = "#ff642e";
132
      view.highlights.items[0].haloOpacity = 1;
133

134
      const legendExpand = new Expand({
135
        view,
136
        content: new Legend({
137
          view,
138
        }),
139
      });
140
      view.ui.add(legendExpand, "top-left");
141
    </script>
142
  </head>
143

144
  <body>
145
    <div id="viewDiv"></div>
146
  </body>
147
</html>

Alternate binning styles

Bins can be styled with any renderer suitable for a polygon layer. This example demonstrates how to visualize bins based on two aggregate fields. The aggregate count is visualized with a size visual variable, and the average number of people injured in each crash is visualized using a color visual variable.

Car crashes (2020) aggregated to bins at a fixed level of 6. The size of each symbol indicates the total number of crashes. Color indicates the average number of injured motorists per crash.

1
      const featureReduction = {
2
        type: "binning",
3
        fixedBinLevel: 6,
4
        fields: [
5

6
          new AggregateField({
7
            name: "aggregateCount",
8
            statisticType: "count",
9
          }),
10
          new AggregateField({
11
            name: "AVG_MOTORIST_INJURED",
12
            alias: "Ratio of motorist injuries to crashes",
13
            onStatisticField: "NUMBER_OF_MOTORIST_INJURED",
14
            statisticType: "avg",
15
          }),
16

17
        ],
18
        renderer: {
19
          type: "simple",
20
          symbol: {
21
            type: "simple-marker",
22
            color: [0, 255, 71, 1],
23
            outline: null,
24
            outline: {
25
              color: "rgba(153, 31, 23, 0.3)",
26
              width: 0.3,
27
            },
28
          },
29

30
          visualVariables: [
31
            {
32
              type: "size",
33
              field: "aggregateCount",
34
              legendOptions: {
35
                title: "Total crashes",
36
              },
37
              minSize: {
38
                type: "size",
39
                valueExpression: "$view.scale",
40
                stops: [
41
                  { value: 18055, size: 18 },
42
                  { value: 36111, size: 12 },
43
                  { value: 72223, size: 8 },
44
                  { value: 144447, size: 4 },
45
                  { value: 288895, size: 2 },
46
                  { value: 577790, size: 1 },
47
                ],
48
              },
49
              maxSize: {
50
                type: "size",
51
                valueExpression: "$view.scale",
52
                stops: [
53
                  { value: 18055, size: 48 },
54
                  { value: 36111, size: 32 },
55
                  { value: 72223, size: 24 },
56
                  { value: 144447, size: 18 },
57
                  { value: 288895, size: 12 },
58
                  { value: 577790, size: 6 },
59
                ],
60
              },
61
              minDataValue: 10,
62
              maxDataValue: 300,
63
            },
64
            {
65
              type: "color",
66
              field: "AVG_MOTORIST_INJURED",
67
              legendOptions: {
68
                title: "% of motorists injured per crash",
69
              },
70
              stops: [
71
                { value: 0, color: colors[0], label: "No injuries" },
72
                { value: 0.1, color: colors[1] },
73
                { value: 0.3, color: colors[2], label: "30%" },
74
                { value: 0.5, color: colors[3] },
75
                { value: 0.75, color: colors[4], label: ">75%" },
76
              ],
77
            },
78
          ],
79

80
        },
81
      };

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 dataClustering High density dataHeatmap

What is binning?

Why is binning useful?

How binning works

Binning polylines and polygons

Examples

Basic binning

Alternate binning styles

Related samples and resources

Intro to binning

Binning polylines

Binning with aggregate fields

Binning - Filter by category

Summarize binned data using Arcade

FeatureReductionBinning

AggregateField

Binning now available in the ArcGIS API for JavaScript

API support