Cluster data for visualization
- Last UpdatedFeb 27, 2025
- 10 minute read
When displaying a large data set that might contain several thousand points on a map, you might encounter some potential issues. Firstly, performance degradation might occur if all the points (also called "markers") are visible at lower zoom levels. Secondly, markers in close geographic proximity might overlap and even obscure each other at lower zoom levels.
To address these issues, you can use clustering. Clustering involves an algorithm that collapses two or more points that are located near each other on the screen into a single cluster point. All other points that are not collapsed are still visible on the map as "noise points."
The following figure shows the noise points as blue dots and clusters as green and orange markers, with each cluster displaying the cumulative weight of the data points it combines:

The following sections use a simple practical example of data points that represent airports in London, UK, to walk you through the process of creating a cluster data set and then displaying it on a map.
Before you begin
To create a web page with a map and basic interactions, start by creating an HTML file that references a JavaScript code snippet responsible for rendering the map.
For more information and code samples, see Get started.In your JavaScript snippet, center the map on London, UK, and set the zoom level to
7
, as shown in the following example:
Enable clustering
Include the clustering module mapsjs-clustering.js
in the <head>
section of the .html
file, as shown in the following example:
Create a clustering data set
Within yuor JavaScript snippet, create a variable that stores data points to display as clusters on the map, as shown in the following example:
In this example, the code declares a variable called dataPoints
and initializes it as an empty array. Then, the code adds new H.clustering.DataPoint
objects to the array by using the push()
method. Each H.clustering.DataPoint
object represents a location of an airport in London, UK, and is created with latitude and longitude values.
Note
You can modify the data set by adding, removing or completely replacing the datapoints. Calling these methods triggers reclustering.
Display cluster data on the map
Initialize a HERE Maps clustering data provider and layer. Then, add the data points to the map as a clustered layer. For example, see the following code snippet:
This code creates an H.clustering.Provider
object that runs the clustering algorithm and groups data points, depending on their screen density. The H.map.layer.ObjectLayer
object adds the clustered data points on the map.
Result: The following figure shows how the HERE clustering algorithm renders the airport data set on the map as clusters or individual data points, depending on the zoom level:

Zooming in causes the cluster to divide into individual data points:

Fine-tune cluster creation
To customize the clustering algorithm for your use case, you can adjust the parameters of the H.clustering.Provider
class.
This class includes properties that determine how clusters and noise points are visually represented, the maximum radius for data points to be considered part of a cluster, and the minimum weight required to form a cluster.
To adjust clustering behavior to your needs, update the H.clustering.Provider
instance with your customizations. For example:
where:
The
min
andmax
properties are not part of the configurable options of theH.clustering.Provider
class. These options define the zoom level range in which clustering occurs.The
eps
property determines the maximum radius within which data points are considered as part of a cluster.For example, in the code example, the
eps
value is set to32
. This means that if two data points are within32
pixels of each other on the map, the clustering algorithm considers them as part of the same cluster.The
minWeight
property determines the minimum weight required to form a cluster.In the example provided, the
minWeight
property is set to3
, which means that three data points with a combined weight of at least3
are required to form a cluster. For example, if there are three data points each with a weight of1
, or two data points with a weight of2
and one data point with a weight of1
, they are clustered together. However, if there are only two data points each with a weight of1
, they are not clustered together.
Customize theming
On the map, clusters and noise points are depicted by using markers. By default, the clustering provider utilizes the default bitmap markers theme, which incorporates weight information to display clusters and noise points on the map. To adjust marker look and feel to your use case, you can create a custom theme and set it as the value of the theme property when calling the provider.
Define an SVG template to use for noise icons. The following template consists of an SVG element with a green circle inside:
Create an
H.map.Icon
object by using thenoiseSvg
template. Specify the size and anchor of the icon in pixels:Define an SVG template to use for cluster icons. The following template consists of an SVG element with a red circle inside, with the size and position of the circle specified using variables:
Modify the
H.clustering.Provider
object to take an array ofdataPoints
and atheme
implementation as parameters:The
theme
implementation specifies how the clusters and noise points are displayed on the map, where:- The
getClusterPresentation()
function calculates the size and position of the cluster icon using the weight of the cluster and the SVG template that you defined earlier. The function then creates anH.map.Marker
object for the cluster by using the icon, minimum and maximum zoom levels, and data for the marker. - The
getNoisePresentation()
function creates anH.map.Marker
object for each noise point by using the same SVG template that you defined earlier and sets the icon and minimum zoom level for the marker.
- The
Result: The following figure shows the result of using a custom theme for clustering data points. In this figure, cluster markers are represented as red circles and noise points are represented as green circles.:

Interact with markers
You can interact with markers representing clusters and noise points and access cluster (H.clustering.ICluster
) or noise point (H.clustering.INoisePoint
) data on demand by using map events.
To process a specific event type in the clustering provider, you can add an event listener for that type.
In the following example, an event listener is added to the clustered data provider to detect when a marker has been tapped. When a marker is tapped, the latitude and longitude of the marker are logged to the console, depending on the marker type.
The following figure shows the output in the developer console window:
Source code
This section contains the full JavaScript code that was used in this tutorial. This code sets up a map and adds multiple markers to it, which are clustered together based on their proximity. The code also defines how the markers should look and behave when clicked, as well as adding an event listener to log the latitude and longitude of any clicked markers. Finally, the code enables default pan and zoom interactions on the map.
Next steps
For more information on the Maps API for JavaScript design, see API Reference.