▾
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.
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.

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.

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
maxScalein the feature reduction configuration to disable binning at larger scales (zoomed in). This allows individual features to appear in full detail.
- Set
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 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.
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.
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>36 collapsed lines
<html> <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>
<link rel="stylesheet" href="https://js.arcgis.com/5.2/esri/themes/light/main.css" /> <!-- 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 center="-19.933231, 15.586053" scale="73957191"> <arcgis-zoom slot="top-left"></arcgis-zoom> <arcgis-expand slot="top-left"> <arcgis-legend></arcgis-legend> </arcgis-expand> </arcgis-map>
<script type="module"> const [WebMap, FeatureLayer] = await $arcgis.import([ "@arcgis/core/WebMap.js", "@arcgis/core/layers/FeatureLayer.js", ]);
const viewElement = document.querySelector("arcgis-map");
const colors = ["#4d394d", "#6c2f68", "#901f8a", "#c700bb", "#ff33f3"];
const featureReduction = { type: "binning", fixedBinLevel: 2, fields: [ { name: "aggregateCount", alias: "Total count", statisticType: "count", }, ], renderer: { type: "simple", symbol: { type: "simple-fill", color: [0, 255, 71, 1], outline: null, outline: { color: colors[0], width: 0, }, }, visualVariables: [ { type: "color", field: "aggregateCount", legendOptions: { title: "Number of floats", }, stops: [ { value: 1, color: colors[0] }, { value: 25, color: colors[1] }, { value: 50.5, color: colors[2] }, { value: 75, color: colors[3] }, { value: 100, color: colors[4] }, ], }, ], },66 collapsed lines
labelsVisible: true, labelingInfo: [ { minScale: 120000000, maxScale: 0, deconflictionStrategy: "none", symbol: { type: "text", color: "white", font: { family: "Noto Sans", size: 10, weight: "bold", }, haloColor: colors[4], haloSize: 0.5, }, labelExpressionInfo: { expression: "Text($feature.aggregateCount, '#,###')", }, }, ], popupEnabled: true, popupTemplate: { title: "Aggregated floats", content: "{aggregateCount} Argo floats in this area.", }, };
const layer = new FeatureLayer({ blendMode: "lighten", title: "Argo floats", url: "https://www.ocean-ops.org/arcgis/rest/services/Argo/ARGOLocations/FeatureServer/1", featureReduction, });
const map = new WebMap({ basemap: { portalItem: { id: "38189d7d668c490895ed15fddcfdc7c7", }, }, layers: [layer], });
viewElement.map = map; viewElement.popup = { dockEnabled: true, dockOptions: { breakpoint: false, }, }; viewElement.constraints = { snapToZoom: false, }; viewElement.highlights = [ { name: "default", fillOpacity: 0.25, color: "#ff642e", haloOpacity: 1, }, ]; </script> </body></html>Alternate binning styles
Bins can be styled with any renderer suitable for a polygon layer.
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>42 collapsed lines
<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 and injuries)</title>
<!-- Load the ArcGIS Maps SDK for JavaScript from CDN --> <script type="module" src="https://js.arcgis.com/5.2/"></script> <style> html, body { margin: 0; height: 100%; } #infoDiv { padding: 10px; } </style> </head> <body> <arcgis-map center="-73.942905, 40.713667" scale="288895"> <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 legend-style="classic"></arcgis-legend> </div> </arcgis-expand> </arcgis-map>
<script type="module"> const [Map, FeatureLayer, LabelClass, AggregateField] = await $arcgis.import([ "@arcgis/core/Map.js", "@arcgis/core/layers/FeatureLayer.js", "@arcgis/core/layers/support/LabelClass.js", "@arcgis/core/layers/support/AggregateField.js", ]);
const colors = ["#d7e1ee", "#cbd6e4", "#b3bfd1", "#c86558", "#991f17"];
const featureReduction = { type: "binning", fixedBinLevel: 6, fields: [ new AggregateField({ name: "aggregateCount", statisticType: "count", }), new AggregateField({ name: "AVG_MOTORIST_INJURED", alias: "Ratio of motorist injuries to crashes", onStatisticField: "NUMBER_OF_MOTORIST_INJURED", statisticType: "avg", }), ], renderer: { type: "simple", symbol: { type: "simple-marker", color: [0, 255, 71, 1], outline: null, outline: { color: "rgba(153, 31, 23, 0.3)", width: 0.3, }, }, visualVariables: [ { type: "size", field: "aggregateCount", legendOptions: { title: "Total crashes", }, minSize: { type: "size", valueExpression: "$view.scale", stops: [ { value: 18055, size: 18 }, { value: 36111, size: 12 }, { value: 72223, size: 8 }, { value: 144447, size: 4 }, { value: 288895, size: 2 }, { value: 577790, size: 1 }, ], }, maxSize: { type: "size", valueExpression: "$view.scale", stops: [ { value: 18055, size: 48 }, { value: 36111, size: 32 }, { value: 72223, size: 24 }, { value: 144447, size: 18 }, { value: 288895, size: 12 }, { value: 577790, size: 6 }, ], }, minDataValue: 10, maxDataValue: 300, }, { type: "color", field: "AVG_MOTORIST_INJURED", legendOptions: { title: "% of motorists injured per crash", }, stops: [ { value: 0, color: colors[0], label: "No injuries" }, { value: 0.1, color: colors[1] }, { value: 0.38, color: colors[2], label: "38%" }, { value: 0.5, color: colors[3] }, { value: 0.75, color: colors[4], label: ">75%" }, ], }, ], }, };67 collapsed lines
const year = 2020;
const layer = new FeatureLayer({ title: "Motor vehicle crashes (2020)", url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/ArcGIS/rest/services/NYC_motor_crashes/FeatureServer/0", featureReduction, popupTemplate: { title: "Crash location", content: [ { type: "fields", fieldInfos: [ { fieldName: "CRASH_DATE", label: "Date", fieldFormat: { type: "date-time", dateStyle: "medium", timeStyle: "medium", hour12: "always", }, }, { fieldName: "NUMBER_OF_PERSONS_KILLED", label: "Fatalities", }, { fieldName: "NUMBER_OF_PERSONS_INJURED", label: "Injuries", }, ], }, ], }, definitionExpression: `CRASH_DATE > Date '${year - 1}-12-31' AND CRASH_DATE < Date '${year + 1}-01-01'`, renderer: { type: "simple", label: "Crash location", symbol: { type: "simple-marker", style: "circle", size: 5, color: colors[3], outline: { style: "solid", color: [15, 15, 15, 0.3], width: 0.5, }, }, }, });
// get the arcgis-map component element and set the map const viewElement = document.querySelector("arcgis-map"); viewElement.map = new Map({ basemap: "gray-vector", layers: [layer], });
const toggleButton = document.getElementById("showBins"); toggleButton.onclick = () => { layer.featureReduction = layer.featureReduction ? null : featureReduction; }; </script> </body></html>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
The following table describes the geometry and view types that are suited well for each visualization technique.
| 2D | 3D | Points | Lines | Polygons | Mesh | Client-side | Server-side | |
|---|---|---|---|---|---|---|---|---|
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | | | | | | |
| | | | ||||||
| | | | | | | | |
- Feature reduction selection not supported
- Only by feature reduction selection
- Only by scale-driven filter