Working with a large number of objects

API users often find they must display hundreds or even thousands of objects on a single map.

The easiest way to put an object on the map is to create a geo object (an instance of the GeoObject class) and add it to the map. By using geo objects, hundreds of objects can be marked on the map without loss of performance.

But if you need to put several thousand objects on the map, this approach will lead to a significant loss of performance. This is related to the following problems:

  • Geo object processing on the client side.

    The creation, processing, and rendering of a geo object is an expensive operation in terms of resources spent. Adding several thousand geo objects to the map places a heavy load on the browser. This may cause pages to freeze.

  • Non-optimal data loading.

    When working with a large number of objects, a problem may occur with loading extra data. For example, when objects are placed all over the world, but the user is only viewing the map of a single city.

The API provides a set of tools for solving the problems listed above:

Note. All four tools lack the ability to drag objects on the map. They also do not support object editing.

These tools are described below, along with a table showing the advantages and disadvantages of each of them.

Advantages and disadvantages of tools

Tool Advantages Disadvantages


— No need to implement the server part.

— Allows filtering objects when displaying them.

— Uses object clusterization on the client side.

— Allows simultaneous rendering of about one thousand objects (that fall in the viewport) without loss of performance.

— Optimal data loading must be implemented independently.


— Optimally loads data from the server.

— Allows filtering objects when displaying them.

— Uses object clusterization on the client side.

— Allows simultaneous rendering of about one thousand objects (that fall in the viewport) without loss of performance.

— The server part must be implemented.


— Optimally loads data from the server.

— Can display results of server clusterization.

— Allows simultaneous rendering of about one thousand objects (that fall in the viewport) without loss of performance.

— The server part must be implemented.

Hotspot layer

— Allows various objects to be placed on the map: placemarks, circles, polygons, and so on.

— Only necessary data is loaded from the server.

— No restrictions on the number of objects to display on the map simultaneously without loss of performance.

— Complex implementation of the server part.

— Not possible to re-render an object on the client side. To change the appearance of an object (for example, when pointing the mouse at it), a request for a new image must be sent to the server.

ObjectManager object manager

This is how the ObjectManager works: As input, the manager gets a JSON description of all the objects that should be placed on the map. According to this description, the manager creates object overlays (their visual representation), which it then adds to the map. The ObjectManager also allows clustering objects.

Before working with the ObjectManager, the JSON description of objects must be downloaded from the remote server to the client side (for example, using the jQuery.getJSON() function).

This tool has the lowest performance of all the tools discussed. Nevertheless, the tool has a noticeable performance advantage when compared to using separate geo objects or the clusterer.

LoadingObjectManager object manager

The LoadingObjectManager object manager works on the same principle as ObjectManager — it creates overlays based on a JSON description of objects, and adds them to the map.

The difference between these two managers is as follows: ObjectManager does not load data from the server. It only works with the objects that were pre-loaded on the client side. LoadingObjectManager loads data itself, and only for the objects that fall within the map viewport.

LoadingObjectManager stores loaded data on the client side. When the user moves the map or changes the zoom, the manager checks whether the data was previously loaded — if not, it downloads the data.

When using LoadingObjectManager, you must implement server processing of the data yourself. Since the server and manager exchange data in JSONP format, the server must return data for requested objects wrapped in a callback function.

LoadingObjectManager is recommended when a large number of objects need to be displayed on the map, but there is no sense in loading all of them at once (for example, when placemarks cover the entire world, but only a single country will be shown on the map).

RemoteObjectManager object manager

The way RemoteObjectManager works is similar to LoadingObjectManager. The main difference between these tools is that RemoteObjectManager does not clusterize objects on the client side, but it can display results of server clusterization.

RemoteObjectManager stores data downloaded from the server. However, when the zoom changes, the manager requests data from the server again, even if the data for the visible area was pre-loaded at a different zoom level.

Of all three managers, RemoveObjectManager provides the best performance when working with a large number of objects.

Hotspot layer

This tool lets you put a large number of different objects on the map — placemarks, circles, rectangles, and so on. The tool is used, for example, when displaying the traffic layer and geo-anchored photos on the map.

The principle of hotspots is as follows: Instead of displaying separate geo objects on the map, a single layer is displayed that contains the images of all these objects. On top of the layer with object images, a layer of hotspots is added to the map, containing information about these objects and their borders.

The hotspot layer allows the objects to be interactive, meaning that we can program an object's reaction to user actions.

Information about objects and their images is downloaded from the server. The developer needs to ensure that the server processes the requests coming from the client side and returns data in the required format.

Of all four technologies, this technology is the most effective, but it is also the most difficult to use.