Maps API for JavaScript Developer's Guide

H.Map

Class Summary

Extends: H.util.EventTarget

Map class defines map instance in the application. By creating this object you will initialize a visible map object which is attached to the provided dom element. Map class is an entry point to all operations related to layers, map objects and geo-screen transformations. By specifying options you can initialize map with predefined view.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

getElement () : {Element}

This method returns the map root html element

setCenter (center, opt_animate) : {H.Map}

This method sets the new center on a map.

getCenter () : {H.geo.Point}

This method returns currently rendered center of the map.

setZoom (zoom, opt_animate) : {H.Map}

This method sets the zoom level on the map. Every zoom level represents different scale i.e map at zoom level 2 is twice as large as the map at zoom level 1.

getZoom () : {number}

This method returns currently rendered zoom level.

zoomAt (zoom, x, y)

This method changes the map zoom while keeping target screen coordinates specified as x,y at the same place where they were before.

setViewBounds (boundingRect, opt_animate) : {H.Map}

This method sets the bounding rect to be displayed by the map. Maps display the bounding rect in a way that it fits entirely in the current viewport.

getViewBounds () : {H.geo.Rect}

This method returns bounding rect for the current map view. Returned bounding rect defines entire currently viewable area on the screen.

getCameraDataForBounds (rect) : {H.map.ViewModel.CameraData}

Calculates the best CameraModel to show the provided bounding rectangle

getViewPort () : {H.map.ViewPort}

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

getViewModel () : {H.map.ViewModel}

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

getLayers () : {H.map.DataModel}

This method returns the map's current layer collection.

getImprint () : {H.map.Imprint}

This method returns the imprint object for this map.

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

This method captures desired region of the map and objects on it. Result is returned as an HTML5 Canvas element. Origin of coordinate system for capturing is in the top left corner of the viewport.

setEngineType (type) : {H.Map}

This method sets the rendering engine type for the map. Rendering engine is responsible for displaying i.e tiles and data on the map.

storeContent (opt_onprogress, opt_bounds, opt_min, opt_max, opt_layer) : {H.util.Request}

To persistently store 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 established and also to reduce the download traffic for frequently visited map areas.

clearContent (opt_onprogress) : {H.util.Request}

To clear the entire stored content

addLayer (layer, opt_idx) : {H.Map}

This method adds a layer to the map.

removeLayer (layer) : {H.Map}

This method removes layer from the map.

setBaseLayer (layer) : {H.Map}

This method will set provided layer as base map. The layer will be inserted as the bottom most layer in the map.

getBaseLayer () : {?H.map.layer.Layer}

To get the current base map layer.

geoToScreen (geoPoint) : {?H.math.Point}

Returns the screen coordinates according to the given geographical coordinates. This method returns a screen pixel coordinates for the provided geo point.

screenToGeo (x, y) : {?H.geo.Point}

Returns the geographical coordinates according to the given screen coordinates.

screenToCameraData (x, y) : {H.map.ViewModel.CameraData}

Returns the camera data according to the given screen coordinates. Method converts screen pixel coordinates to correct camera data object

addObject (mapObject) : {!H.map.Object}

This method adds an map object to the map. Map object can be a marker or a spatial object like polygon or polyline.

removeObject (mapObject) : {!H.map.Object}

This method removes previously added map object from the map.

getObjects () : {Array<H.map.Object>}

This method retrieves the list of all objects which have been added to the map.

addObjects (mapObjects) : {H.Map}

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

removeObjects (mapObjects) : {H.Map}

This method removes an array of object or an object group from the map.

getObjectAt (x, y) : {?H.map.Object}

Returns the top most z-ordered map object found under the specific screen coordinates. Coordinates are viewport pixel coordinates starting from top left corner as (0, 0) point.

getObjectsAt (x, y) : {Array<!H.map.Object>}

Returns a list of map objects in descending z-order found under the specific screen coordinates. Coordinates are viewport pixel coordinates starting from top left corner as (0, 0) point.

addEventListener (type, handler, opt_capture, opt_scope)

This method allows to listen for specific event triggered by the object. Keep in mind, that you must removeEventListener manually or dispose an object when you no longer need it. Otherwise memory leak is possible.

removeEventListener (type, handler, opt_capture, opt_scope)

This method will removed previously added listener from the event target

dispatchEvent (evt)

This method will dispatch event on the event target object

dispose ()

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

addOnDisposeCallback (callback, opt_scope)

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

Events Summary

Table 2. Events
Events

mapviewchangestart : {H.util.Event}

Fired when changes of this map's view are starting

mapviewchange : {H.map.ChangeEvent}

Fired when changes of this map's view are ongoing

mapviewchangeend : {H.util.Event}

Fired when changes of this map's view are ending

baselayerchange : {H.util.ChangeEvent}

Fired when this map's base layer changes

enginechange : {H.util.ChangeEvent}

Fired when this map's engine changes i.e when entering panorama. Event holds references to old and new engine type.

Class Description

Map class defines map instance in the application. By creating this object you will initialize a visible map object which is attached to the provided dom element. Map class is an entry point to all operations related to layers, map objects and geo-screen transformations. By specifying options you can initialize map with predefined view.

Example

var platform = new H.service.Platform({
  app_id: "{your app id}",
  app_code: "{your app code}"
});
var maptypes = platform.createDefaultLayers();

var map = new H.Map(document.getElementById('mapdiv'), maptypes.normal.map, {
  center: new H.geo.Point(0, 51),
  zoom: 8
});

Constructor Details

H.Map(element, baseLayer, opt_options)

Parameters:
 
element:
{Element}
 
html element into which the map will be rendered
baseLayer:
{H.map.layer.Layer}
 
The layer to be used as the base (bottom most) layer.
opt_options:
{H.Map.Options=} [optional]
 
additional map options

Method Details

getElement () : {Element}

This method returns the map root html element

Returns:
 
{Element}

setCenter (center, opt_animate) : {H.Map}

This method sets the new center on a map.

Parameters:
 
center:
{H.geo.IPoint}
 
requested center to be set
opt_animate:
{boolean=} [optional]
 
parameter indicates if animated transition should be applied, default is false
Returns:
 
{H.Map}
the instance itself

getCenter () : {H.geo.Point}

This method returns currently rendered center of the map.

Returns:
 
{H.geo.Point}

setZoom (zoom, opt_animate) : {H.Map}

This method sets the zoom level on the map. Every zoom level represents different scale i.e map at zoom level 2 is twice as large as the map at zoom level 1.

Parameters:
 
zoom:
{number}
 
requested zoom level
opt_animate:
{boolean=} [optional]
 
parameter indicates if animated transition should be applied, default is false
Returns:
 
{H.Map}
the instance itself

getZoom () : {number}

This method returns currently rendered zoom level.

Returns:
 
{number}

zoomAt (zoom, x, y)

This method changes the map zoom while keeping target screen coordinates specified as x,y at the same place where they were before.

Parameters:
 
zoom:
{number}
 
new zoom level
x:
{number}
 
map viewport x-axis pixel coordinate
y:
{number}
 
map viewport y-axis pixel coordinate

setViewBounds (boundingRect, opt_animate) : {H.Map}

This method sets the bounding rect to be displayed by the map. Maps display the bounding rect in a way that it fits entirely in the current viewport.

Parameters:
 
boundingRect:
{H.geo.Rect}
 
view bound which should be shown on map
opt_animate:
{boolean=} [optional]
 
parameter indicates if animated transition should be applied, default is false
Returns:
 
{H.Map}
the instance itself

getViewBounds () : {H.geo.Rect}

This method returns bounding rect for the current map view. Returned bounding rect defines entire currently viewable area on the screen.

Returns:
 
{H.geo.Rect}

getCameraDataForBounds (rect) : {H.map.ViewModel.CameraData}

Calculates the best CameraModel to show the provided bounding rectangle

Parameters:
 
rect:
{H.geo.Rect}
 
The geographical bounding rectangle to use
Returns:
 
{H.map.ViewModel.CameraData}
The result, represented by the properties zoom (number) and position (geo.Point)

getViewPort () : {H.map.ViewPort}

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

Returns:
 
{H.map.ViewPort}

getViewModel () : {H.map.ViewModel}

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

Returns:
 
{H.map.ViewModel}

getLayers () : {H.map.DataModel}

This method returns the map's current layer collection.

Returns:
 
{H.map.DataModel}

getImprint () : {H.map.Imprint}

This method returns the imprint object for this map.

Returns:
 
{H.map.Imprint}

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

This method captures desired region of the map and objects on it. Result is returned as an HTML5 Canvas element. Origin of coordinate system for capturing is in the top left corner of the viewport.

In order to see the "capturable" UI controls in the output, pass in a reference to H.ui.UI object. At the moment only H.ui.ScaleBar ui element supports the feature.

Note, that instances of H.map.Icon will taint the output canvas if images from different origin were used. For cases when image source sets CORS headers H.map.Icon supports 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.

Example

var map = new H.Map(mapContainer, defaultLayers.normal.map, {
  center: {lat: -40, lng: 178},
  zoom: 2
});
var ui = H.ui.UI.createDefault(map, defaultLayers);
map.capture(function(canvas) {
  // Here we've got 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);
Parameters:
 
callback:
{function(HTMLCanvasElement=)}
 
Callback function to call once result of the capturing is ready
opt_capturables:
{Array<H.util.ICapturable>=} [optional]
 
Collection of "capturable" element(s) to draw into 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

setEngineType (type) : {H.Map}

This method sets the rendering engine type for the map. Rendering engine is responsible for displaying i.e tiles and data on the map.

Parameters:
 
type:
{H.Map.EngineType}
 
Returns:
 
{H.Map}
the map itself

storeContent (opt_onprogress, opt_bounds, opt_min, opt_max, opt_layer) : {H.util.Request}

To persistently store 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 established and also to reduce the download traffic for frequently visited map areas.

Parameters:
 
opt_onprogress:
{function(H.util.Request)=} [optional]
 
A callback which is invoked every time when the progress state of the returned store request changes.
opt_bounds:
{H.geo.Rect=} [optional]
 
The area to store, default is the current view bounds
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
Returns:
 
{H.util.Request}
A handle to the created storage request

clearContent (opt_onprogress) : {H.util.Request}

To clear the entire stored content

Parameters:
 
opt_onprogress:
{function(H.util.Request)=} [optional]
 
A callback which is invoked every time when the progress state of the returned clear request changes
Returns:
 
{H.util.Request}
A handle to the created flush request

addLayer (layer, opt_idx) : {H.Map}

This method adds a layer to the map.

Parameters:
 
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:
 
{H.Map}
current map instance

removeLayer (layer) : {H.Map}

This method removes layer from the map.

Parameters:
 
layer:
{H.map.layer.Layer}
 
The map layer to be removed
Returns:
 
{H.Map}
current map instance

setBaseLayer (layer) : {H.Map}

This method will set provided layer as base map. The layer will be inserted as the bottom most layer in the map.

Parameters:
 
layer:
{H.map.layer.Layer}
 
The layer to use as base map
Returns:
 
{H.Map}
the instance itself

getBaseLayer () : {?H.map.layer.Layer}

To get the current base map layer.

Returns:
 
{?H.map.layer.Layer}

geoToScreen (geoPoint) : {?H.math.Point}

Returns the screen coordinates according to the given geographical coordinates. This method returns a screen pixel coordinates for the provided geo point.

Parameters:
 
geoPoint:
{H.geo.IPoint}
 
point on the map
Returns:
 
{?H.math.Point}

screenToGeo (x, y) : {?H.geo.Point}

Returns the geographical coordinates according to the given screen coordinates.

Parameters:
 
x:
{number}
 
map viewport x-axis pixel coordinate
y:
{number}
 
map viewport y-axis pixel coordinate
Returns:
 
{?H.geo.Point}

screenToCameraData (x, y) : {H.map.ViewModel.CameraData}

Returns the camera data according to the given screen coordinates. Method converts screen pixel coordinates to correct camera data object

Parameters:
 
x:
{number}
 
map viewport x-axis pixel coordinate
y:
{number}
 
map viewport y-axis pixel coordinate

addObject (mapObject) : {!H.map.Object}

This method adds an map object to the map. Map object can be a marker or a spatial object like polygon or polyline.

Parameters:
 
mapObject:
{!H.map.Object}
 
The map object to add
Returns:
 
{!H.map.Object}
the added map object

removeObject (mapObject) : {!H.map.Object}

This method removes previously added map object from the map.

Parameters:
 
mapObject:
{!H.map.Object}
 
The map object to remove
Returns:
 
{!H.map.Object}
the removed map object

getObjects () : {Array<H.map.Object>}

This method retrieves the list of all objects which have been added to the map.

Note: The returned list should be used for read access only. Modifying the list directly can destroy the integrity of this map's object model. Please use the map's addObject/addObjects and removeObject/removeObjects methods.

Returns:
 
{Array<H.map.Object>}
the list of all use objects which are currently on the map.

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 will not be added again.

Parameters:
 
mapObjects:
{Array<!H.map.Object>}
 
Returns:
 
{H.Map}
the map instance

removeObjects (mapObjects) : {H.Map}

This method removes an array of object or an object group from the map.

Parameters:
 
mapObjects:
{(Array<H.map.Object> | H.map.Group)}
 
Returns:
 
{H.Map}
the map instance

getObjectAt (x, y) : {?H.map.Object}

Returns the top most z-ordered map object found under the specific screen coordinates. Coordinates are viewport pixel coordinates starting from top left corner as (0, 0) point.

Parameters:
 
x:
{number}
 
map viewport x-axis pixel coordinate
y:
{number}
 
map viewport y-axis pixel coordinate
Returns:
 
{?H.map.Object}
the encountered top most map object or null if no object found

getObjectsAt (x, y) : {Array<!H.map.Object>}

Returns a list of map objects in descending z-order found under the specific screen coordinates. Coordinates are viewport pixel coordinates starting from top left corner as (0, 0) point.

Parameters:
 
x:
{number}
 
map viewport x-axis pixel coordinate
y:
{number}
 
map viewport y-axis pixel coordinate
Returns:
 
{Array<!H.map.Object>}

addEventListener (type, handler, opt_capture, opt_scope)

This method allows to listen for specific event triggered by the object. Keep in mind, that you must removeEventListener manually or dispose an object when you no longer need it. Otherwise memory leak is possible.

Parameters:
 
type:
{string}
 
name of event
handler:
{!Function}
 
event handler function
opt_capture:
{boolean=} [optional]
 
if set to true will listen in the capture phase (bubble otherwise)
opt_scope:
{Object=} [optional]
 
scope for the handler function

removeEventListener (type, handler, opt_capture, opt_scope)

This method will removed previously added listener from the event target

Parameters:
 
type:
{string}
 
name of event
handler:
{!Function}
 
previously added event handler
opt_capture:
{boolean=} [optional]
 
if set to true will listen in the capture phase (bubble otherwise)
opt_scope:
{Object=} [optional]
 
scope for the handler function

dispatchEvent (evt)

This method will dispatch event on the event target object

Parameters:
 
evt:
{(H.util.Event | string)}
 
event object or event name

dispose ()

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

addOnDisposeCallback (callback, opt_scope)

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

Parameters:
 
callback:
{!Function}
 
The callback function.
opt_scope:
{Object=} [optional]
 
An optional scope to call the callback in.

Event Details

mapviewchangestart: {H.util.Event}

Fired when changes of this map's view are starting

mapviewchange: {H.map.ChangeEvent}

Fired when changes of this map's view are ongoing

mapviewchangeend: {H.util.Event}

Fired when changes of this map's view are ending

baselayerchange: {H.util.ChangeEvent}

Fired when this map's base layer changes

enginechange: {H.util.ChangeEvent}

Fired when this map's engine changes i.e when entering panorama. Event holds references to old and new engine type.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.