Handling Large Amounts of Markers in Google Maps
To use markers in Google Maps is fairly trivial, at least when you have a reasonable amount of them. But once you have more than a few hundred of them, performance quickly starts to degrade. In this article I will show you a few approaches to speed up performance. I’ve also put together a test page to compare them.
Update [2009-05-06]:This article has been updated with the addition of the utility library MarkerClusterer. The test results in the end of the article and the test page has also been revised.
If you’re new to markers in Google Maps I recommend that you first read Basic operations with markers in Google Maps for an introduction on how to use them.
The Marker Manager – Keeps track of them
Your first option might be to use the MarkerManager since it’s an utility library provided by Google. Rather than adding each marker individually to the map using GMap2.addOverlay() you first add them to the MarkerManager. The MarkerManager keeps track of all your markers. By defining at which zoom-levels each marker should appear you can cluster the markers to reduce the amount being shown at a time.
The MarkerManager is initially a bit slower than just adding markers directly to the map but the added benefit is that you can have more control over them.
You add markers to the MarkerManager with addMarker(GMarker, minZoom, maxZoom?). This method takes three arguments, the first one being the marker you want to add. The two second arguments are optional but define at which zoom-levels the marker will be visible.
A simple example
// Create a new map
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(59.5, 14.0), 6);
// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create a new marker
var marker = new GMarker(new GLatLng(59.0, 13.80));
// Add marker to the MarkerManager
mgr.addMarker(marker);
Obviously there’s not much use adding a single marker to the MarkerManager, but if you have hundreds of them, this might be the way to go.
Bulk adding the markers
An even more efficient way of using the MarkerManager is to do a bulk add by first putting all your markers into an array and then add the array to the MarkerManager with the addMarkers(markerArray, minZoom, maxZoom?) method.
// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create marker array
var markers = [];
// Loop to create markers and adding them to the MarkerManager
for(var i = 0; i < 50; i += 0.1) {
var marker = new GMarker(new GLatLng(59.0 + i, 13.80 + i));
markers.push(marker);
}
// Add the array to the MarkerManager
mgr.addMarkers(markers);
// Refresh the MarkerManager to make the markers appear on the map
mgr.refresh();
Notice that you have to use mgr.refresh() after adding the marker array to it. That's not necessary when adding the markers one by one.
Additional methods
- removeMarker(marker)
Removes a marker from the MarkerManager - clearMarkers()
Removes all markers. - getMarkerCount(zoom)
Returns the number of markers at a given zoom-level.
The MarkerManager is a utility library provided by Google. On the URL below you'll find the source code as well as the full documentation and examples.
Marker Light - Markers on a diet
Pamela Fox at Google has made a sample app for what she calls MarkerLight, which render less complex markers, thus increasing performance. The trade-off is that it's really just an image on the map, you can't interact with it. If you don't have the need for interaction this is a really easy way to gain performance, the only difference from the ordinary way of doing it is that you create a MarkerLight instead of a GMarker.
On Pamelas post about MarkerLight she explains why this approach is faster:
The reason GMarker takes so long is that it's actually composed of many DOM elements - foreground, shadow, printable version, clickable area, etc.
If your purpose is visualization, then you can get away with just creating a GOverlay extension like MarkerLight that creates a div with a background URL (or background color, even better!).
- Pamela Fox
Here's how to use it:
map.addOverlay(new MarkerLight(latlng, {image: "red_dot.png"}));
red_dot.png in is the image used for the marker. It's a very small and simple one.
You can try performance with different numbers of markers on Pamelas test page.
Using Marker Light in combination with MarkerManager
You can add the benefits of MarkerLight with the clustering capabilities of the MarkerManager. It's really easy, just combine the two:
mgr.addMarker(new MarkerLight(latlng, {image: "red_dot.png"}));
The reason you should do this is that you can display a different number of markers at different zoom levels. This way you can ensure that not too many markers are displayed at the same time.
Clusterer - Only show what you need
A different approach is to use ACME labs Clusterer. It's a third party library that offers a faster way of adding markers. It's released under the BSD license and is freely available.
It allows faster performance by doing two things.
- Only the markers currently visible actually get created.
- If too many markers would be visible, then they are grouped together into cluster markers.
This lets you have literally thousands of markers on a map while maintaining decent performance. My tests with this approach shows that it's significantly faster than the MarkerManager approach.
Here's how to use it:
// Create a Clusterer object var clusterer = new Clusterer(map); // Create marker var marker = new GMarker(new GLatLng(57.8, 14.0)); // Add marker to the map clusterer.AddMarker(marker, 'text to infobox');
To remove a marker from the map call clusterer.RemoveMarker(marker).
There's also a few methods to change the behavior of the marker.
- clusterer.SetIcon(GIcon)
Changes the cluster icon - clusterer.SetMaxVisibleMarkers(n)
Sets the threshold marker count where clustering kicks in. Default value is 150. - clusterer.SetMinMarkersPerCluster(n)
Sets the minumum number of markers for a cluster. Default value is 5. - clusterer.SetMaxLinesPerInfoBox(n)
Sets the maximum number of lines in an info box. Default value is 10.
ClusterMarker - Chunk 'em all up
ClusterMarker is a free Javascript library released under the GNU General Public License, that adds clustering capabilities to markers. The unique thing with this library is that it automatically detects markers that intersect each other and cluster these into a single cluster marker.
The images below illustrates how this works
The constructor takes two arguments and looks like this:
var cluster = new ClusterMarker(map, options).
map is a reference to the map object and options is an object literal that can have these properties:
- clusterMarkerIcon [GIcon]
Changes the default cluster marker icon to an icon of your choice.
- markers [array]
An array with all the markers you want to pass to the ClusterMarker
Apart from these properties you can also use all the other properties of the class. Se the documentation for a complete list.
Here's how to add markers using the ClusterMarker with a minimum amount of code.
var markerArray = [];
// Insert code to fill the markerArray with markers...
// Creating a new cluster by adding the map and the markerarray
var cluster = new ClusterMarker(map, {markers: markerArray});
// Refreshing to show the added markers
cluster.refresh();
This code will insert the markers on the map and cluster them under one icon if they're close enough to each other. For more fine grained control of how it operates there are several methods and properties. For a detailed explanation of how the library works there's excellent documentation on the Clustermarker Project page.
MarkerClusterer - The new kid in town
This utility library is the newest of them all and wasn't around when I originally wrote this article. This library, which is written by Xiaoxi Wu and is part of the Google Maps Open Source Utility Library is easy to use and shows excellent performance.
Like some of the other libraries it reduces the number of visible markers by clustering them together making it easier to get an overview. Watch the image below to see how.
Image by Xiaoxi Wu
It's constructor takes three arguments, the first one being a reference to the map, the second one being an array of GMarkers and the third one being an object literal with options. Only the first one is required.
var markerCluster = new MarkerClusterer(map, markers, opts);
So to add a bunch of markers to the map having the default settings of the MarkerClusterer you do this:
var markers = []; // Insert code to fill the markerArray with markers... // Creating a new cluster by adding the map and the array of markers var markerCluster = new MarkerClusterer(map, markers);
See the documentation for a full explanation of the library and it's capabilities. Also read MarkerClusterer: A Solution to the Too Many Markers Problem on the Google Geo Developer blog for more information.
Compare performance
Compare the different techniques on the Test page
Inspired by Pamela Fox testpage for MarkerLight I've set up a test page of my own where you can test the performance of all the different approaches in this article.
The result
I ran a series of test with a few different browsers. In each test I added 500 markers using the different techniques. Between each test I refreshed the browsers. All tests were performed on a PC with a 3.60 GHz Pentium 4 HT processor and 2 Gb RAM running Windows XP.
| Google Chrome 1.0.154 | Safari 3.2.1 | Firefox 3.0.10 | Internet Explorer 8.0 | Opera 9.63 | Average result | |
|---|---|---|---|---|---|---|
| GMarker | 1649 | 1168 | 3020 | 3329 | 1250 | 2083 |
| MarkerManager | 1828 | 1333 | 3232 | 5485 | 1297 | 2635 |
| MarkerLight | 393 | 269 | 797 | 860 | 297 | 523 |
| MarkerManager + MarkerLight | 400 | 534 | 1134 | 906 | 469 | 689 |
| Clusterer2 | 29 | 40 | 66 | 109 | 47 | 58 |
| ClusterMarker | 432 | 502 | 832 | 1219 | 500 | 697 |
| MarkerClusterer | 189 | 527 | 374 | 1047 | 329 | 493 |
Note: Since the addition of MarkerClusterer I've ran the tests again and updated the result grid. Some of the web browsers are newer than in the lats test run. See the old test results.
In this test Clusterer2 was the fastest technique of them all. Be aware however that this is not the entire truth since I've only been able to measure how long it takes before the markers are passed to the map, not the actual time until they are visible on the map. When taking this into consideration I find that MarkerClusterer is the fastest technique closely followed by ClusterMarker.
When it comes to browsers the fastest performance is marked with green and the worst performance is marked with red in the result grid. Not surprisingly Internet Explorer is the slowest of the lot. Google Chrome and Safari has the fastest overall performance with their blazing fast Javascript engine.
If you have an idea on how to improve this test to better measure the actual time until the markers are visible on the map, please share in the comments or contact me through the Contact page.
Conclusion
The techniques showed in this article are all fairly easy to implement and works well when you don't have an incredibly large amount of markers. For those occasions where none of these techniques suffice you will have to resort to more extreme measures, like creating a big overlay with all the markers, but that's beyond the scope of this article.
I hope that you'll find these techniques helpful. Happy coding!

Excellent article. Thank you!
great article!, Do you know if there is something similar for Polyline?
in regards to your time measures, you could have a diferent image for each marker, passing an id like so:
img src=”myimage.php?id=xxx” and measure the time in the server, or just with the php file and in the php register the time, so you get a start and end time of the images served.
Hope that helps.
Ingo Claro: Well I’ve written two articles about performance on polylines in Google Maps. In the end of the second article there are links to test pages, testing different approaches and measuring performance. Check out Polylines in Google Maps [Part 1] and Polylines in Google Maps [Part 2].
Regarding you idea of measuring the time with the help of PHP I guess that it could work. One possible disadvantage being that it might slow down performance a bit since the browser won’t be able to cache the images. I would prefer if there were some way of doing it in pure Javascript. But still that’s the best idea so far. Thanks!
thanks! I’ll look at your articles.
In regards to the testing, I would be slower than a real world scenario, but it will measure all the technics the same, so it’s a fair comparision.
In that regard, I noticed that you make random point’s. It would be better to load pre calculated point’s and use the same data in all cases.
Awesome man!
Just as I’ve had to quit this war by lacking out of time.. you just did it great!
Great article! Thanks for gathering all this information. It’s going to save me a lot of time spent on research.
Regarding the testing of displaying of pins on the map, there’s no need to point to a dynamically served image. You just need to link to a static image with appropriate Cache-Control headers set, so browsers don’t download the image each time, and log requests with a large time resolution (1 millisecond should be enough). Provided these, you’ll be able to easily and accurately measure the time overhead after passing the markers to the map.
Another fantastic article. I’ll add this to the documentation shortly.
You might also want to try this new library, similar to ClusterMarker:
http://gmaps-utility-library-dev.googlecode.com/svn/trunk/markerclusterer/
Pamela: Sounds great! Yes I’ve discovered that library after I wrote this article and it looks very promising. I will have to include it in the test suite as soon as I find the time.
Nice article Gabriel! As you say, when you need to show thousands of markers, javascript libraries are not a valid approach. On our projects, we always do the markers clustering at server side, using python (or similar) and some precalculated info, and returning only the cluster info.
[...] hinaus finden man bei Gabriel Svennerberg den Beitrag “Handling Large Amounts of Markers in Google Maps” der unter anderem eine Vergleichsmessung der verschiedenen Browser bei vielen Markern mit den [...]
Marc Puig: What kind of algorithm you used to do server side clustering? Is the clustering done when loading to server or do it on the fly for every query? If you have severl 50,000 markers, clustering still takes a while. Thanks.
+1 for testing MarkerClusterer under the same conditions as the others please. MarkerClusterer is fairly quick in IE and looks user friendly (nice icon that includes the number of markers)
Gabriel, this has been a very useful article and well presented. Thank you.
Gary: MarkerClusterer looks very interesting and I will include it in my speed test as soon as I find the time. Meanwhile check out Xiaoxi Wu’s own Speed Test Page.
[...] Handling Large Amounts of Markers in Google Maps | In usability we trust To use markers in Google Maps is fairly trivial, at least when you have a reasonable amount of them. But once you have more than a few hundred of them, performance quickly starts to degrade. In this article I will show you a few approaches to speed up performance. I’ve also put together a test page to compare them. (tags: content tutorial maps googlemaps markermanager) [...]
[...] Ein guter Einstieg in dieses Thema ist der Blogpost von Gabriel Svennerberg zum Thema Handling Large Amounts of Markers in Google Maps. Hier werden verschiedene Methoden zum Clustern von Markern und vor allem ein Benchmark zur [...]
I would love to see a flex/flash class for this…
sorry flash code for MarkerClusterer
Thank you so much, amazing article, it summarized everything i need to know about clusters.
Thank you again
Keep up the good work
Just been trying to use your “MarkerManager + MarkerLight” code but after trying to add the marker lights to the marker manager i noticed that in your code you have commented out the part where it does this, and simply adds them in the same way as if you were just using marker lights (as simple overlays). Is there any reason for this? Is there still a way of added them to a marker manager or does this method no longer work ?
Josh: You’re absolutely right, there’s an error in the test case with Markerlight + MarkerManager. I must have changed it for some reason I can’t remember and then forgot to change it back. There’s no problem getting it to work so you can safely use that combination if you like.
Now it’s corrected in the example, and I have updated the results in the result grid accordingly.
Thanks for noticing!
Do you know how to do it with Google Web Toolkit? I have a GWT Google Map googleMap = new MapWidget(); … I need to do clustering.
Ive been really struggling to get below into a for loop, if anyone could shed some light
that would be awesome
map.addOverlay(new MarkerLight(latlng, {image: "red_dot.png"}));I have written a tutorial which describes some basis clustering techniques. It is written for static maps but can easily be adapted for server side clustering with Google Maps API.
There is any way to use MarkerClusterer with Flex?
Hi,
Great tutorial, found an error. Line 08 of the code example found in the section “Bulk adding the markers”:
marker.push(marker);
This should actually read:
markers.push(marker);
Jason
Jason: Good catch! Thanks for noticing! I’ve corrected the example now.
To time actual marker display, couldn’t the image src instead of being a http url to a php script, just be a javascript: url so that you can effect a method call on the display of the marker?
Ported to flash…
http://www.toruinteractive.com/stuff/MarkerClusterer_For_Flash.zip
Sean Toru
Can you plz help me with replacing fl package to mx package.
Thanks
Thank you SOOO much for the resources! I tried programming a class that would query my database for only the markers that where within the google maps box, and it was a MESS and had a million glitches! If I had known earlier that these sources were available, I would had never bothered querying my database like I did. Again, thanks a million.
Please delete my last post.
This is a sample of server side cluster based on admin border. Just for some one interest in that topic.
http://www.usda.gov/recovery/map/
nice example of server side clustering: http://www.geocubes.com
thank you! it’s realy help!
[...] Google eventually. A concern that needs addressed if this grows to above a few thousand…click here for some more [...]
Great article!
Do you know if there is marker cluster for the new v3 api?
Thank you so much..
great article, saved my day
I am about to finish my stuff now..! thanks again!
thanks thanks and thanks!
Great article!
[...] Shared Handling Large Amounts of Markers in Google Maps – In usability we trust. [...]
Great write up. Was wondering is any of this marker manager being ported over to Google Map V3?
Clayton Narcis: There’s no official version of MarkerManager for V3 but I know that some people have ported it but I don’t know if they are publicly available.
Hello,
i tried some speed tests with markerClusterer and ClusterMarker and I noticed that with a lot of markers ( > 1000) markerCluster seems to takes the advantage ( but sometimes not -_-’ ).
But once the markers are clusterized, i think i prefer the markerClusterer: when you drag the map, the markers don’t desappear quickly while clusters are redraw.
Furthermore, if you click on a cluster, the comportement is different : markerCluster will try to show a marker at the maximum zoom that is possible ( which sometimes is cool and sometimes not), while markerClusterer will bring you step by step ( zoom level by zoom level) to the marker. as for me, i prefer this way.
conclusion : i think they are two good clusters. People have to try them both. ( although MarkerClusterer has little issues at this date : http://code.google.com/p/gmaps-utility-library-dev/issues/list )
ps: both can works pretty well with MarkerLight. If you want to combine MarkerLight and MarkerClusterer, you have to add 3 methods to the markerLight class : hide(), show() and isHidden() ( see Mike Williams’s elabels to find these methods).
If you want to use clusterMarker with markerLight, you have to do a very little hack in cluster marker concerning the set of GIcon ( that you don’t need no more). You can even hack the clusterMarker to create a GOverlay ( as markerCkusterer rather than a GMarker).
ricco
ricco: I agree with you that they are both good clusterers, definitely two that should be considered when choosing the right clusterer for the job. Also thanks for the tip about using markerLight with the clusterers. Could come in handy!
Прикольно! Все очень понятно и грамотно, и в то же время без умствований и самолюбования, и на доступном языке. Редкий случай когда человек делится актуальной и полезной инфой. Спасибо автору!
I’m working on your example clustermaker. Line 6 cluster.refresh() dosen’t work. refresh is not in the cluter2.js. Please advice. Thank you
You might also be interested in my clusterer for Flash based on a serverside PHP solution I found. More info and a demo here:
http://www.kelvinluck.com/2009/08/google-maps-for-flash-marker-clustering/
For those of you who are looking for a clustering solution for the v3 API: There’s a new one i wrote at work, called Fluster and available for download at http://blog.fusonic.net. There will be an improved version the next days which speeds up the whole process of clustering significantly.
Matthias Burtscher Good job Matthias! I know a lot of people, myself included, have waited for this!
Hi
If someone is interested in an example of the MarkerClusterer in action, I’m using it to display my photos.
Wow, this is a great resource. Thank you very much for taking the time to compare all of these different techniques and for creating the demo page to sample them all!
Really useful. Thanks!
Hey Gabriel Svennerberg,
Thanks a lot for your help through the book, its really nice of you to share your knowledege. Awaiting for the complete version of book with clusters.
Thanks again.
Here is a marker manager for GMap v3, in case anyone is looking for it.
http://blog.fusonic.net/archives/tag/google-maps
have yet to test it but will definitely look into it
Will ClusterMarker & MarkerClusterer work with v3? If not whats the missing piece to cause issue? Thanks
[...] Tekst na podstawie własnych doświadczeń oraz art. "Handling Large Amounts of Markers in Google Maps" [...]
Great article! Thanks.