Item page
CodePen
Sandbox Download

Argo float locations aggregated at fixed bin level 3 to show global density at a higher resolution.

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.

CodePen
Sandbox Download

Use the swipe control to compare overlapping Argo float points with binned versions 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.

  • Choose suitable features.
    • Use binning for features of similar size that are smaller than the bins. Parcels, buildings, swimming pools, bridges, culverts, and connectors are often suitable when viewed at small scales (zoomed out).
    • Avoid binning large or irregularly shaped features. Features such as counties, states, and countries generally do not need aggregation, and binning may misrepresent their spatial distribution.
  • Account for centroid-based placement. Binning assigns each feature to a bin based on its centroid, not its full extent. As a result:
    • A feature may be assigned to a bin that contains little of its area or length.
    • Areas covered by large polygons or polylines may have no populated bins.
  • Set an appropriate scale limit.
    • Set maxScale in the feature reduction configuration to disable binning at larger scales (zoomed in). This allows individual features to appear in full detail.

Examples

Basic binning

Select a fixedBinLevel between 1 and 9 based on the data extent. The following table describes suggested bin levels given your data extent.

Fixed bin levelSuggested data extent
1-3Global extents.
3-5Regional extents (e.g. countries and states).
5-7Local communities (e.g. counties and cities).
7-9Hyper 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.

Aggregate fields can be used in a bin renderer, labels, and popup. These properties are configured as they would be for other layer types, but must refer to aggregate fields in FeatureReductionBinning.fields instead of the underlying layer’s fields. Bins are typically styled with a continuous color visual variable.

Item page
CodePen
Sandbox Download
Argo float locations are aggregated at fixed bin level 2 for a global view, with a renderer, labels, and a popup showing each bin's feature count.
Binning - Argo float locations (level 2)
20 collapsed lines
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>Binning - Argo float locations (level 2)</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.2/"></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<arcgis-map item-id="38234d361b3149f89f6b15a1bc800bf7">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-expand slot="top-left">
<arcgis-legend></arcgis-legend>
</arcgis-expand>
</arcgis-map>
2 collapsed lines
</body>
</html>

Alternate binning styles

Bins can be styled with any renderer suitable for a polygon layer.

Item page
CodePen
Sandbox Download
New York City car crashes are aggregated into bins, with size showing crash count and color showing injuries.
Binning - color and size (crash count and injuries)
24 collapsed lines
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
<title>Binning - color and size (crash count)</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
<script type="module" src="https://js.arcgis.com/5.2/"></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
#infoDiv {
padding: 10px;
}
</style>
</head>
<body>
<arcgis-map item-id="012a7a5e42e047e389f53a20ebd13eca">
<arcgis-zoom slot="top-left"></arcgis-zoom>
<arcgis-home slot="top-left"></arcgis-home>
<arcgis-expand slot="top-left" expand-icon="list-bullet">
<div id="infoDiv">
<calcite-button id="showBins" secondary width="full">Toggle Binning</calcite-button>
<arcgis-legend></arcgis-legend>
</div>
</arcgis-expand>
</arcgis-map>
15 collapsed lines
<script type="module">
const viewElement = document.querySelector("arcgis-map");
await viewElement.viewOnReady();
const layer = viewElement.map.layers.getItemAt(0);
const featureReduction = layer.featureReduction;
const toggleButton = document.getElementById("showBins");
toggleButton.addEventListener("click", () => {
layer.featureReduction = layer.featureReduction ? null : featureReduction;
});
</script>
</body>
</html>

API support

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

  • Full support
  • Partial support
  • No support
2D3DPointsLinesPolygonsMeshClient-sideServer-side
  1. Feature reduction selection not supported
  2. Only by feature reduction selection
  3. Only by scale-driven filter