Manage map objects

The Maps API for JavaScript provides an object model that enables convenient organization of objects on a map. The API categorizes objects into three types: markers, spatials, and groups.

Marker

Markers represent visual indicators of locations on the map, characterized by their geographical coordinates (latitude and longitude) and an associated icon. When you pan the map, the marker's position changes, but its size remains constant regardless of the map's zoom level.

The API offers two types of markers to cater to different scenarios:

Regular marker (H.map.Marker)
DOM marker (H.map.DomMarker)

For more information, see Add markers.

Geo shape

Spatial objects (spatials), also referred to as geo shapes in this guide, are circles, rectangles, polylines, and polygons. You can use these objects to mark areas on a map. A spatial object is defined by a set of geographical points that are translated and scaled as the map is panned and zoomed, ensuring that the position of the shape on the display accurately reflects its geographic location.

A spatial object includes styling information, which determines how to render its outline and fill it (if it's a closed shape). The Maps API provides the following classes to represent spatial objects:

H.map.Polyline for polylines
H.map.Polygon for polygons
H.map.Circle for circles
H.map.Rect for rectangles For more information, see Use geoshapes.

Overlay

An overlay is an object that covers a rectangular area on the map with a bitmap image. It is defined by a set of geographical points. The image can be procedurally generated or retrieved from the server as a static bitmap.

For more information, see Display custom overlays.

Group

Groups are logical containers that can hold collections of child objects (markers or spatials, as well as sub-groups). Groups allow for efficient management of map objects, enabling atomic operations such as adding, removing, showing, and hiding sets of objects without individual manipulation. Additionally, groups facilitate calculations of bounding boxes encompassing all contained objects and provide event listening capabilities for events dispatched by child objects within the group.

For more information, see H.map.Group documentation in the API Reference.

Add or remove objects

Each map object type corresponds to a class in the API. When creating a new instance of such a class, it does not automatically appear on the map. Instead, like nodes in the HTML document object model (DOM), objects must be explicitly added to the root group using the addObject() method. Conversely, to remove an object from the map, use the removeObject() method.

Groups also have their own addObject() and removeObject() methods, behaving like container elements in the HTML DOM. You can create an empty group on the map and add individual objects later.

The following code example demonstrates how to:

Create an empty group
Add it to the map
Create a marker and make it a member of the group

// Create a group that can hold map objects:
const group = new H.map.Group();

// Add the group to the map object (created earlier):
map.addObject(group);

// Create a marker:
const marker = new H.map.Marker(map.getCenter());

// Add the marker to the group (which causes 
// it to be displayed on the map)
group.addObject(marker);

Understand rendering order of map objects

The rendering engine of the HERE Maps API for JavaScript evaluates map objects and then renders spatial objects, markers, and DOM markers in separate passes. As a result, spatials, markers, and DOM markers cannot be intermixed. Spatial objects are rendered within the main scene's geographic space and are rendered like other map layers. Following this, the API renders all regular Markers, followed by the rendering of all DomMarkers.

Next steps

For more information, see: