Maps API for JavaScript Developer's Guide

Marker Objects

One of the most common use cases for a mapping application is to show points of interest (POIs) on the map. The HERE Maps API for JavaScript, makes the implementation very easy by allowing you to represent POIs as markers.

The Maps API offers two sorts of markers:

Table 1. Marker Types in HERE Maps API for JavaScript
Marker type Class Description
Marker H.map.Marker A "normal" marker that uses a static image as an icon. Large numbers of markers of this types can be added to the map very quickly and efficiently.
DOM marker H.map.DomMarker A marker which supports HTML (and SVG) content, which can be dynamic. Markers of this type are best displayed individually or in small sets.

A marker of either type consists of a geographical point defined by its latitude and longitude and a visual representation, which is an icon. Marker icons are rendered in screen-space, meaning that their size never changes regardless of the zoom level of the map.

Maker and DomMarker require different icon types. A Marker object accepts Icon instances (H.map.Icon) and a DomMarker needs an instance of DomIcon (H.map.DomIcon). This scheme allows icons to be reused in multiple marker objects.

It is also important to note that Markers and DomMarkers are rendered in separate rendering steps. Markers are rendered onto the map canvas and therefore appear behind any DomMarkers, which are rendered in an overlay on top of the map.

Marker with a Static SVG Icon

The code below shows how to instantiate a marker with an SVG icon.

// Create a map:
var map = new H.Map(...);

// Define a variable holding SVG mark-up that defines an icon image:
var svgMarkup = '<svg width="24" height="24" ' +
  'xmlns="http://www.w3.org/2000/svg">' +
  '<rect stroke="white" fill="#1b468d" x="1" y="1" width="22" ' +
  'height="22" /><text x="12" y="18" font-size="12pt" ' +
  'font-family="Arial" font-weight="bold" text-anchor="middle" ' +
  'fill="white">H</text></svg>';

// Create an icon, an object holding the latitude and longitude, and a marker:
var icon = new H.map.Icon(svgMarkup),
  coords = {lat: 52.53075, lng: 13.3851},
  marker = new H.map.Marker(coords, {icon: icon});

// Add the marker to the map and center the map at the location of the marker:
map.addObject(marker);
map.setCenter(coords);

The code creates:

  1. A map object (see also Quick Start).
  2. An SVG icon image (as a string).
  3. An object containing the geographic coordinates of a location, and a "normal" marker.

The last line of code adds the newly created marker to the map.

The resulting map centered on the location of the marker is shown in the image below.

Note: It is crucial to reuse icons between the markers to achieve better performance.

Figure 1. The map after adding the SVG marker

Marker with a Static Image

The following code snippet shows how to instantiate an icon and a marker from an image URL.

The code creates:

  1. A map object (see also Quick Start)
  2. An icon using the URL of a bitmap (PNG image)
  3. A "normal" marker initialized with the bitmap.

The last line of the code adds the marker to the map.

// Create a map:
var map = new H.Map(...);

// Create a marker icon from an image URL:
var icon = new H.map.Icon('graphics/markerHouse.png');

// Create a marker using the previously instantiated icon:
var marker = new H.map.Marker({ lat: 52.5, lng: 13.4 }, { icon: icon });

// Add the marker to the map:
map.addObject(marker);

The image below shows the map centered on the location of the marker that uses a bitmap icon.

Figure 2. Map with a bitmap marker

This example uses a basic set of parameters to create a marker with a custom image icon. However, icons and markers provide further customization options, which can be passed to the constructors as parameters. These options include, for example, custom hit-areas and anchors for image icons. For the full documentation, see the API Reference.

Note: The icon property of a marker is one of the optional parameters as well. The API provides a default icon for markers to which a custom icon has not been assigned.

Marker with HTML / SVG content

Image markers are a good way to highlight points of interest on a map with static graphical content. In certain use-cases, it is desirable to provide markers with interactive or animated HTML content (for example animated GIFs, animated SVGs or hover effects), rather than pre-rendered images. The Maps API provides the DomMarker class for such use-cases.

The following example shows how a DomMarker can be used to create a marker with animated SVG content. In this case, the animated marker icon is a bouncing ball.

The code creates:

  1. A map object (see also Quick Start).
  2. A variable that holds the definition of an animated SVG image.
  3. An icon (initialized with the SVG image.
  4. An object containing the geographic coordinates of a location.
  5. A "normal" marker.

The last two lines add the marker to the map and center the map, using the object holding the geographic coordinates.

// Create a map object:
var map = new H.Map(...);

// Define a variable holding SVG mark-up that defines an animated icon image:
var animatedSvg =
  '<svg version="1.1" xmlns="http://www.w3.org/2000/svg" x="0px" ' + 
  'y="0px" style="margin:-112px 0 0 -32px" width="136px"' + 
  'height="150px" viewBox="0 0 136 150"><ellipse fill="#000" ' +
  'cx="32" cy="128" rx="36" ry="4"><animate attributeName="cx" ' + 
  'from="32" to="32" begin="0s" dur="1.5s" values="96;32;96" ' + 
  'keySplines=".6 .1 .8 .1; .1 .8 .1 1" keyTimes="0;0.4;1"' + 
  'calcMode="spline" repeatCount="indefinite"/>' +  
  '<animate attributeName="rx" from="36" to="36" begin="0s"' +
  'dur="1.5s" values="36;10;36" keySplines=".6 .0 .8 .0; .0 .8 .0 1"' + 
  'keyTimes="0;0.4;1" calcMode="spline" repeatCount="indefinite"/>' +
  '<animate attributeName="opacity" from=".2" to=".2"  begin="0s" ' +
  ' dur="1.5s" values=".1;.7;.1" keySplines=" .6.0 .8 .0; .0 .8 .0 1" ' +
  'keyTimes=" 0;0.4;1" calcMode="spline" ' +
  'repeatCount="indefinite"/></ellipse><ellipse fill="#1b468d" ' +
  'cx="26" cy="20" rx="16" ry="12"><animate attributeName="cy" ' +
  'from="20" to="20" begin="0s" dur="1.5s" values="20;112;20" ' +
  'keySplines=".6 .1 .8 .1; .1 .8 .1 1" keyTimes=" 0;0.4;1" ' +
  'calcMode="spline" repeatCount="indefinite"/> ' +
  '<animate attributeName="ry" from="16" to="16" begin="0s" ' + 
  'dur="1.5s" values="16;12;16" keySplines=".6 .0 .8 .0; .0 .8 .0 1" ' +
  'keyTimes="0;0.4;1" calcMode="spline" ' +
  'repeatCount="indefinite"/></ellipse></svg>';

// Create an icon object, an object with geographic coordinates and a marker:
var icon = new H.map.DomIcon(animatedSvg),
  coords = {lat: -22.8906, lng: -43.2283},
  marker = new H.map.DomMarker(coords, {icon: icon});

// Set map center and zoom, add the marker to the map:
map.setCenter(coords);
map.setZoom(18);
map.addObject(marker);

The image below shows the map with a marker that uses an animated icon.

Figure 3. Map with an animated marker