Class: Map

Feedback

Last UpdatedMay 21, 2025
11 minute read

H.Map

new H.Map (element, baseLayer, opt_options)

The Map class defines a map instance. By creating this object, you initialize a visible map attached to a DOM element. The Map class is the entry point to all operations involving layers, map objects and geo-screen transformations. Use the options argument to initialize the map with a specific map view.

Search:

Name	Type	Description
`element`	HTMLElement	HTML element into which the map will be rendered.
`baseLayer`	H.map.layer.Layer	The layer to be used as the base layer.
`opt_options`	H.Map.Options	optional Additional map options (for example a map view)

Throws:

if the element is not a HTMLElement
Type H.lang.InvalidArgumentError

Example

var platform = new H.service.Platform({
  apikey: '{YOUR_API_KEY}'
});

// Obtain the default map types from the platform
var maptypes = platform.createDefaultLayers();

// Instantiate and display a map
var map = new H.Map(document.getElementById('mapdiv'), maptypes.vector.normal.map, {
  center: {lat: 0, lng: 51},
  zoom: 8
});

Extends

H.util.EventTarget

Members

H.Map.EngineState number static

States of the render engine.

Properties:

Name	Description
`IDLE`	The engine is currently idle (rendering completed).
`BUSY`	The engine is actively rendering.

H.Map.EngineType number static

Search:

Name	Description	Notes
P2D	For using the `H.map.render.p2d.RenderEngine`.	Legacy. Not maintained.
WEBGL	For using the `H.map.render.webgl.RenderEngine`.	Current default. In maintenance.
HARP	For using the HARP engine.	Fully supported. Future default engine.

Properties:

Search:

Name	Description
`P2D`
`WEBGL`
`HARP`

draggable boolean

Indicates whether the map will be considered as target for drag events. The default value is false

Methods

addEventListener (type, handler, opt_capture, opt_scope) inherited

This method adds a listener for a specific event.

Note that to prevent potential memory leaks, you must either call removeEventListener or dispose on the given object when you no longer need it.

Search:

Name	Type	Description
`type`	string	The name of the event
`handler`	function	An event handler function
`opt_capture`	boolean	optional `true` indicates that the method should listen in the capture phase (bubble otherwise)
`opt_scope`	Object	optional An object defining the scope for the handler function

addLayer (layer, opt_idx)H.Map

This method adds a layer to the map. If the layer was already added before, it will be moved above the most recently added layer.

Name	Type	Description
`layer`	H.map.layer.Layer	The map layer to be added
`opt_idx`	number	optional index at which the new layer should be inserted

Returns:

Type	Description
H.Map	current map instance

addObject (mapObject)H.map.Object

This method adds a map object to the map. The map object can be a marker or a spatial object such as a polygon or polyline.

Name	Type	Description
`mapObject`	H.map.Object	The map object to add

Throws:

This method throws an error if the mapObject parameter is not a map object.
Type Error

Returns:

Type	Description
H.map.Object	The added map object

addObjects (mapObjects)H.Map

This method adds an array of objects or an object group to the map.

Note: Objects which were added to the map previously won't be added again.

Name	Type	Description
`mapObjects`	Array.<!H.map.Object>

Throws:

if the argument is not an Array of H.map.Object instances
Type H.lang.InvalidArgumentError

Returns:

Type	Description
H.Map	The current map instance

addOnDisposeCallback (callback, opt_scope) inherited

This method adds a callback which is triggered when the EventTarget object is being disposed.

Name	Type	Description
`callback`	function	The callback function.
`opt_scope`	Object	optional An optional scope for the callback function

capture (callback, opt_capturables, opt_x1, opt_y1, opt_x2, opt_y2)

This method captures the desired region of the map and the associated map objects. The method returns an HTML5 Canvas element. The origin of coordinate system is the top-left corner of the viewport.

In order to see any captured UI controls in the output, pass in a reference to H.ui.UI object. At present, only H.ui.ScaleBar UI element supports the feature.

Note that instances of H.map.Icon taint the output canvas if images from different origins are used. When an image source sets CORS headers, H.map.Icon supports a flag that enables image loading with cross-origin parameters. Internet Explorer always taints the canvas element when SVG images are used. CORS support for images starts only from IE11.

Search:

Name	Type	Description
`callback`	function(HTMLCanvasElement)	Callback function to call once capturing has been finished. If the Map's render engine doesn't support capturing capability then `null` is passed as argument, otherwise a canvas element that represents the captured map.
`opt_capturables`	Array.<!H.util.ICapturable>	optional Collection of "capturable" element(s) to draw onto the resulting canvas
`opt_x1`	number	optional The x coordinate of the left edge of the capturing rectangle, defaults to 0
`opt_y1`	number	optional The y coordinate of the top edge of the capturing rectangle, defaults to 0
`opt_x2`	number	optional The x coordinate of the right edge of the capturing rectangle, defaults to viewport width
`opt_y2`	number	optional The y coordinate of the bottom edge of the capturing rectangle, defaults to viewport height

Throws:

This method throws an error if the callback parameter is not a function
Type Error

Example

var platform = new H.service.Platform({
  apikey: '{YOUR_API_KEY}'
});
var maptypes = platform.createDefaultLayers();
var map = new H.Map(mapContainer, maptypes.vector.normal.map, {
  center: {lat: -40, lng: 178},
  zoom: 2
});
var ui = H.ui.UI.createDefault(map, maptypes);
map.capture(function(canvas) {
  // Here we have the canvas with desired area of the map,
  // (from top left (0,0) corner to the bottom right (100,100) corner)
}, [ui], 0, 0, 100, 100);

clearContent (opt_onprogress)H.util.Request

This method clears the entire stored content.

Name	Type	Description
`opt_onprogress`	function(H.util.Request)	optional A callback which is invoked each time the progress state of the returned clear request changes

See:

storeContent

Returns:

Type	Description
H.util.Request	A handle to the created flush request

dispatchEvent (evt) inherited

This method dispatches an event on the EventTarget object.

Name	Type	Description
`evt`	H.util.Event \| string	An object representing the event or a string with the event name

dispose () inherited

This method removes listeners from the given object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners.

geoToScreen (geoPoint)H.math.Point

This method retrieves the screen coordinates corresponding to the geographical coordinates supplied by the caller.

Name	Type	Description
`geoPoint`	H.geo.IPoint	point on the map

Returns:

Type	Description
H.math.Point

getBaseLayer ()H.map.layer.Layer

This method gets the current base map layer.

Returns:

Type	Description
H.map.layer.Layer	representing the current base map layer.

getCenter ()H.geo.Point

This method returns the current center of the map.

Returns:

Type	Description
H.geo.Point

getElement ()HTMLElement

This method retrieves the map root HTML element.

Returns:

Type	Description
HTMLElement

getImprint ()H.map.Imprint

This method retrieves the imprint object for this map.

Returns:

Type	Description
H.map.Imprint

getLayers ()H.map.DataModel

This method retrieves the map's current layer collection.

Returns:

Type	Description
H.map.DataModel

getObjectAt (x, y, callback)

To obtain the top-most z-ordered map object found at the specified screen coordinates. Coordinates are viewport pixel coordinates starting from top-left corner as origin (0, 0).

Search:

Name	Type	Description
`x`	number	map viewport x-axis pixel coordinate
`y`	number	map viewport y-axis pixel coordinate
`callback`	function((H.map.Feature\|undefined))	It is invoked when the operation has been finished. It gets as argument the top-most map feature object or `undefined` if no object has been found.

getObjects (opt_recursive)Array.<!H.map.Object>

This method obtains a list of all objects that have been added to the map. See H.map.Group#getObjects.

Unless opt_recursive parameter is set to true, this method will return only first level objects, for example if group with a marker is added to the map, only the group will be returned and not the marker.

Note: Adding or removing objects on the obtained list doesn't affect the map. Use the map's addObject and removeObjects methods instead.

Name	Type	Description
`opt_recursive`	boolean	optional Indicates whether objects in sub-groups are also collected.

Returns:

Type	Description
Array.<!H.map.Object>	the list of all user objects which are currently on the map.

getObjectsAt (x, y, callback, opt_allowDuplicates)

To obtain a list of map objects in descending z-order found at the specified screen coordinates. The coordinates are viewport pixel coordinates starting from top left corner as origin (0, 0).

Search:

Name	Type	Description
`x`	number	map Viewport x-axis pixel coordinate
`y`	number	map Viewport y-axis pixel coordinate
`callback`	function(!Array.<!H.map.Feature>)	It is invoked when the operation has been finished. It gets as argument a list of feature objects found.
`opt_allowDuplicates`	boolean	optional Boolean flag indicating that multiple pick results for the same feature are allowed, if the render engine supports it. Be aware that setting this flag to true may cause performance impacts!

getObjectsWithin (area, callback, opt_options)

To obtain a list of map objects which intersect the provided area.

Search:

Name	Type	Description
`area`	H.geo.Polygon	The polygonal geographical area where to obtain the map objects. Since the polygon's legs are not projected, for some areas covering several latitude degrees the set of objects retrieved is not guaranteed to be what is shown in the map.
`callback`	function(!Array.<!H.map.Object>)	The function to invoke when the request operation has been finished. It gets a list of all found objects as argument.
`opt_options`	H.Map.GetObjectsWithinOptions	optional Additional options to filter the obtained map objects

getViewModel ()H.map.ViewModel

This method retrieves current view model. View model can be used to modify the current view or camera. H.map.ViewModel

Returns:

Type	Description
H.map.ViewModel

getViewPort ()H.map.ViewPort

This method retrieves the current map viewport. The viewport can be used to modify padding and margin, which reflect the position of the viewport center and the amount of extra data loaded (for margin)

Returns:

Type	Description
H.map.ViewPort

getZoom ()number

This method retrieves the current map zoom level.

Returns:

Type	Description
number

removeEventListener (type, handler, opt_capture, opt_scope) inherited

This method removes a previously added listener from the EventTarget instance.

Search:

Name	Type	Description
`type`	string	The name of the event
`handler`	function	A previously added event handler
`opt_capture`	boolean	optional `true` indicates that the method should listen in the capture phase (bubble otherwise)
`opt_scope`	Object	optional An object defining the scope for the handler function

removeLayer (layer)H.Map

This method removes a layer from the map.

Name	Type	Description
`layer`	H.map.layer.Layer	The map layer to be removed

Returns:

Type	Description
H.Map	current map instance

removeObject (mapObject)H.map.Object

This method removes previously added map object from the map. Note that method can be used to remove only direct children of the root group of the default object layer.

Name	Type	Description
`mapObject`	H.map.Object	The map object to remove

Throws:

This method throws an error if the mapObject parameter is not a map object.
Type Error

Returns:

Type	Description
H.map.Object	The removed map object

removeObjects (mapObjects)H.Map

This method removes an array of map objects from the map. Note that method can be used to remove only direct children of the root group of the default object layer.

Name	Type	Description
`mapObjects`	Array.<!H.map.Object>

Throws:

This method throws an error if the mapObjects parameter is not an array of map objects
Type Error

Returns:

Type	Description
H.Map	The current map instance

screenToGeo (x, y)H.geo.Point

This method retrieves the geographical coordinates corresponding to the screen coordinates supplied by the caller.

Name	Type	Description
`x`	number	Map viewport x-axis pixel coordinate
`y`	number	Map viewport y-axis pixel coordinate

Returns:

Type	Description
H.geo.Point	object containing the screen coordinates for the specified geographical location.

screenToLookAtData (x, y)H.map.ViewModel.ILookAtData

This method retrieves LookAtData according to the given screen coordinates. The method converts screen pixel coordinates to correct LookAtData object.

Name	Type	Description
`x`	number	map viewport x-axis pixel coordinate
`y`	number	map viewport y-axis pixel coordinate

Returns:

Type	Description
H.map.ViewModel.ILookAtData

setBaseLayer (layer)H.Map

This method sets the provided layer as base map. The layer is inserted as the bottom-most layer in the map.

Name	Type	Description
`layer`	H.map.layer.Layer	The layer to use as base map

Returns:

Type	Description
H.Map	the instance itself

setCenter (center, opt_animate)H.Map

This method sets the center of the map.

Name	Type	Description
`center`	H.geo.IPoint	An object containing the coordinates of the new map center
`opt_animate`	boolean	optional A value indicating if an animated transition should be applied, default is `false`

Returns:

Type	Description
H.Map	the instance itself

setZoom (zoom, opt_animate)H.Map

This method sets the zoom level of the map. Every zoom level represents a different scale. The map at zoom level 2 is twice as large as the map at zoom level 1.

Name	Type	Description
`zoom`	number	A value indicating the new map zoom level
`opt_animate`	boolean	optional A value indicating if an animated transition should be applied, default is `false`

Returns:

Type	Description
H.Map	the instance itself

storeContent (opt_onprogress, opt_boundingBox, opt_min, opt_max, opt_layer)H.util.Request

This method persistently stores the content of a map layer for a given area and range of zoom levels. It can be used to enable map rendering when no internet connection is available and also to reduce the download traffic for frequently visited map areas.

Specified opt_min and opt_max values are clamped to the provider [min,max] range. Note that specifying a big range will cause many tile requests to the server and might greatly affect the performance of the browser.

Search:

Name	Type	Description
`opt_onprogress`	function(H.util.Request)	optional A callback invoked each time the progress state of the returned store request changes.
`opt_boundingBox`	H.geo.Rect	optional The area to store, default is the current bounding box of the map
`opt_min`	number	optional The minimum zoom level to store, default is the current zoom level
`opt_max`	number	optional The maximum zoom level to store, default is the current zoom level
`opt_layer`	H.map.layer.BaseTileLayer	optional The layer to store, default is the current base layer

Throws:

If the browser or the passed layer does not support persistent storage of map layer content
Type H.lang.IllegalOperationError

Returns:

Type	Description
H.util.Request	A handle to the created storage request

zoomAt (zoom, x, y)

This method changes the map zoom level while keeping the map location under the specified screen coordinates (x,y) fixed in the viewport.

Search:

Name	Type	Description
`zoom`	number	A value indicating the new map zoom level
`x`	number	A value representing the x coordinate in the map viewport
`y`	number	A value representing the y coordinate in the map viewport

Type Definitions

H.Map.BackgroundRange Object

This variable defines the number of lower and higher zoom levels, where cached content of the base map is rendered while content of the current zoom level is still loading. For example, if range is set to {lower: 3, higher: 2} and current level is 10, then the rendering engine tries to display cached tiles from the lower zoom levels 7, 8, 9 and the higher levels 11 and 12.

Properties:

Name	Type	Description
`lower`	number	The number of lower zoom levels to take into account, default is `0`
`higher`	number	The number of higher zoom levels to take into account, default is `0`

H.Map.GetObjectsWithinOptions Object

This type defines options that can be used for H.Map#getObjectsWithin calls.

Properties:

Search:

Name	Type	Argument	Description
`zoom`	number	<optional>	The optional zoom level for which the objects are requested. The default value is the map's current zoom level.
`visiblesOnly`	boolean	<optional>	Indicates whether only objects that are effectively visible are requested. The default value is `true`.
`types`	H.math.BitMask.<H.map.Object.Type>		To specify which types of map objects are requested. For example: `types: H.map.Object.Type.MARKER \| H.map.Object.Type.SPATIAL` The default value is `H.map.Object.Type.ANY`.

H.Map.Options Object

This type defines options that can be used to initialize the map.

Properties:

Search:

Name	Type	Argument	Description
`center`	H.geo.IPoint	<optional>	The initial center of the map, default is `{lat:0, lng: 0}`
`zoom`	number	<optional>	The initial zoom level of the map, default is `0` or the minimal zoom level of the base map.
`bounds`	H.geo.AbstractGeometry	<optional>	The bounding area to be displayed on the map. See `H.map.ViewModel#setLookAtData`.
`layers`	Array.<H.map.layer.Layer>	<optional>	A list of layers to render on top of the base map
`engineType`	H.Map.EngineType	<optional>	The initial engine type to use, default is `WEBGL`
`pixelRatio`	number		The pixelRatio to use for over-sampling in cases of high-resolution displays, default is `window.devicePixelRatio`.
`imprint`	H.map.Imprint.Options	<optional> <nullable>	The imprint options or `null` to suppress the imprint
`renderBaseBackground`	H.Map.BackgroundRange	<optional>	An object describing how many cached zoom levels should be used as a base map background while base map tiles are loading. Example: `{lower: 3, higher: 2}`.
`autoColor`	boolean	<optional>	A value indicating whether the UI colors should be automatically adjusted to the base layer (`true`, default). At present, only the copyright style is adjusted. See `H.map.layer.Layer.Options#dark`
`margin`	number	<optional>	The size in pixel of the supplemental area to render for each side of the map
`padding`	H.map.ViewPort.Padding	<optional>	The padding in pixels for each side of the map

Events

baselayerchange

Event fired when the map base layer changes.

Type:

H.util.ChangeEvent

enginestatechange

Event fired when state of the render engine has been changed.

Type:

H.util.ChangeEvent

mapviewchange

Event fired when changes to the current map view are ongoing.

Type:

H.map.ChangeEvent

mapviewchangeend

Event fired when changes to the current map view are ending.

Type:

H.util.Event

mapviewchangestart

Event fired when changes to the current map view are starting.

Type:

H.util.Event

Was this article helpful?

Yes No

HERE Maps API for JavaScript - API Reference

Filters

Product category

Technology

Doc type

Version

Product lifecycle

HERE Maps API for JavaScript - API Reference: Class: Map

new H.Map (element, baseLayer, opt_options)

Throws:

Example

Extends

Members

H.Map.EngineState number static

Properties:

H.Map.EngineType number static

Properties:

draggable boolean

Methods

addEventListener (type, handler, opt_capture, opt_scope) inherited

addLayer (layer, opt_idx)H.Map

Returns:

addObject (mapObject)H.map.Object

Throws:

Returns:

addObjects (mapObjects)H.Map

Throws:

Returns:

addOnDisposeCallback (callback, opt_scope) inherited

capture (callback, opt_capturables, opt_x1, opt_y1, opt_x2, opt_y2)

Throws:

Example

clearContent (opt_onprogress)H.util.Request

Returns:

dispatchEvent (evt) inherited

dispose () inherited

geoToScreen (geoPoint)H.math.Point

Returns:

getBaseLayer ()H.map.layer.Layer

Returns:

getCenter ()H.geo.Point

Returns:

getElement ()HTMLElement

Returns:

getImprint ()H.map.Imprint

Returns:

getLayers ()H.map.DataModel

Returns:

getObjectAt (x, y, callback)

getObjects (opt_recursive)Array.<!H.map.Object>

Returns:

getObjectsAt (x, y, callback, opt_allowDuplicates)

getObjectsWithin (area, callback, opt_options)

getViewModel ()H.map.ViewModel

Returns:

getViewPort ()H.map.ViewPort

Returns:

getZoom ()number

Returns:

removeEventListener (type, handler, opt_capture, opt_scope) inherited

removeLayer (layer)H.Map

Returns:

removeObject (mapObject)H.map.Object

Throws:

Returns:

removeObjects (mapObjects)H.Map

Throws:

Returns:

screenToGeo (x, y)H.geo.Point

Returns:

screenToLookAtData (x, y)H.map.ViewModel.ILookAtData

Returns:

setBaseLayer (layer)H.Map

Returns:

setCenter (center, opt_animate)H.Map

Returns:

setZoom (zoom, opt_animate)H.Map

Returns:

storeContent (opt_onprogress, opt_boundingBox, opt_min, opt_max, opt_layer)H.util.Request

Throws: