Maps SDK for Web

tt.Map

extends Maps.Evented

The Map object represents the map on your page. It exposes methods and properties that enable you to programmatically change the map and fires events as users interact with it. You create a Map by specifying a container and other options.

Constructor

tt.Map(options)

Example
tt.map(options)
Parameters
Name Description
options
Object
default:None 		Object with options.
options.key
String
default:None 		Maps key.
options.container
HTMLElement | String
default:None 		The HTML element representig map container or id of that element.
options.language
String
default:None 		Map language.
options.geopoliticalView
String
default:None 		Map geopolitical view.
options.style
Object | String
default:None 		The map style.

Default value: https://api.tomtom.com/style/1/style/21.1.0-*? map=basic_main&traffic_incidents=incidents_day
&traffic_flow=flow_relative0&poi=poi_main

It can be one of following types:
  • URL to the JSON object conforming to the schema described in the Map Style Specification. Provided URL should follow this pattern: https://api.tomtom.com/style/1/style/<STYLES_VERSION>&map=<MAP_STYLE>&traffic_incidents=<INCIDENTS_STYLE>&traffic_flow=<FLOW_STYLE>&poi=<POI_STYLE>
    where:
  • JSON object conforming to the mentioned specification.
  • Configuration object e.g.:

    style: {

         map: 'basic_main',

         poi: 'poi_main',

         trafficIncidents: 'incidents_day',

         trafficFlow: 'flow_relative'

    }

List of styles supported provided by TomTom can be found in Map styles service (Merged style method section).

Please notice that visibility of certain layers of the style is altered by options.stylesVisibility

Note: methods responsible for showing/hiding traffic flow and traffic incidents will work only if sources conform given sourceName (e.g. showTrafficFlow() will only work if sourceName for trafficFlow is vectorTilesFlow and hideTrafficIncidents() will only work if sourceName for trafficIncidents is vectorTilesIncidents).
To change the parameters of incidents and traffic tiles options.transformRequest can be used.
options.stylesVisibility
Object
default:None 		The dictionary of options representing visibility of style parts. Determining which layers belongs to which style is based on the layer source name. We use following style name to source name mapping:
  • map: 'vectorTiles',
  • trafficFlow: 'vectorTilesFlow',
  • trafficIncidents: 'vectorTilesIncidents'
  • poi: 'poiTiles'
Styles downloaded from Map styles service follow this naming convention. By default layers belonging to "trafficFlow" and trafficIncidents" styles are hidden.

In case you provide your custom style, be aware that if the style does not have layers with sources named as in the mentioned mapping, this option will have no effect on visibility of layers.
options.stylesVisibility.map
Boolean
default:true 		The visibility of base map layers.
options.stylesVisibility.poi
Boolean
default:true 		The visibility of POI layers.
options.stylesVisibility.trafficFlow
Boolean
default:false 		The visibility of traffic flow layers.
options.stylesVisibility.trafficIncidents
Boolean
default:false 		The visibility of traffic incidents layers.
options.minZoom
Number
default:None 		The minimum zoom level of the map (0-24).
options.maxZoom
Number
default:None 		The maximum zoom level of the map (0-24).
options.minPitch
Number
default:0 		The minimum pitch of the map (0-60).
options.maxPitch
Number
default:60 		The maximum pitch of the map (0-60).
options.hash
Boolean | String
default:false 		If true, the map's position (zoom, center latitude, center longitude, bearing, and pitch) will be synced with the hash fragment of the page's URL. For example, http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60 . An additional string may optionally be provided to indicate a parameter styled hash, e.g. if hash: 'map' will be provided: http://path/to/my/page.html#map=2.59/39.26/53.07/-24.1/60 .
options.interactive
Boolean
default:true 		If false, no mouse, touch, or keyboard listeners will be attached to the map, so it will not respond to interaction.
options.bearingSnap
Number
default:7 		The threshold, measured in degrees, that determines when the map's bearing will snap to north. For example, with a bearingSnap of 7, if the user rotates the map within 7 degrees of north, the map will automatically snap to exact north.
options.pitchWithRotate
Boolean
default:true 		If false, the map's pitch (tilt) control with "drag to rotate" interaction will be disabled.
options.clickTolerance
Number
default:3 		The max number of pixels a user can shift the mouse pointer during a click for it to be considered a valid click (as opposed to a mouse drag).
options.failIfMajorPerformanceCaveat
Boolean
default:false 		If true, map creation will fail if the performance of Map would be dramatically worse than expected (i.e., a software renderer would be used).
options.preserveDrawingBuffer
Boolean
default:false 		If true, the map's canvas can be exported to a PNG using tt.map.getCanvas().toDataURL(). This is false by default as a performance optimization.
options.refreshExpiredTiles
Boolean
default:true 		If false, the map won't attempt to re-request tiles once they expire per their HTTP cacheControl / expires headers.
options.maxBounds
Maps.LngLatBounds
default:None 		If set, the map will be constrained to the given bounds.
options.scrollZoom
Boolean | Object
default:true 		If true, the "scroll to zoom" interaction is enabled. An Object value is passed as options to ScrollZoomHandler's enable method. 
scrollZoom: {
    around: 'center'
}
options.boxZoom
Boolean
default:true 		If true, the "box zoom" interaction is enabled (see BoxZoomHandler).
options.dragRotate
Boolean
default:true 		If true, the "drag to rotate" interaction is enabled (see DragRotateHandler).
options.dragPan
Boolean | Object
default:true 		If true, the "drag to pan" interaction is enabled. An Object value is passed as options to DragPanHandler's enable method. 
dragPan: {
    linearity: 0.3,
    easing: bezier(0,0,0.3,1),
    maxSpeed: 1400,
    deceleration: 2500
}
options.keyboard
Boolean
default:true 		If true, keyboard shortcuts are enabled (see KeyboardHandler).
options.doubleClickZoom
Boolean
default:true 		If true, the "double click to zoom" interaction is enabled (see DoubleClickZoomHandler).
options.touchZoomRotate
Boolean | Object
default:true 		If true, the "pinch to rotate and zoom" interaction is enabled. An Object value is passed as options to TouchZoomRotateHandler's enable method. 
touchZoomRotate: {
    around: 'center'
}
options.touchPitch
Boolean
default:true 		If true, the "drag to pitch" interaction is enabled (see TouchPitchHandler).
options.trackResize
Boolean | Object
default:true 		If true, the map will automatically resize when the browser window resizes.
options.center
Maps.LngLat
default:None 		The inital geographical center point of the map. If center is not specified in the constructor options, the Maps SDK will look for it in the map's style object. If it is not specified in the style it will default to (0, 0). Note: The Maps SDK uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
options.zoom
Number
default:0 		The initial zoom level of the map. If zoom is not specified in the constructor options, the Maps SDK will look for it in the map's style object. If it is not specified in the style it will default to 0.
options.bearing
Number
default:0 		The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If bearing is not specified in the constructor options, the Maps SDK will look for it in the map's style object. If it is not specified in the style it will default to 0.
options.pitch
Number
default:0 		The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-60). If pitch is not specified in the constructor options, the Maps SDK will look for it in the map's style object. If it is not specified in the style, it will default to 0.
options.bounds
Maps.LngLatBounds
default:None 		The initial bounds of the map. If bounds is specified, it overrides center and zoom constructor options.
options.fitBoundsOptions
Object
default:None 		A fitBounds options object to use only when fitting the initial bounds provided above.
options.renderWorldCopies
Boolean
default:None 		If true, multiple copies of the world will be rendered when zoomed out.
options.maxTileCacheSize
Number
default:null 		The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
options.localIdeographFontFamily
String
default:null 		If specified, defines a CSS font-family for locally overriding the generation of glyphs in the 'CJK Unified Ideographs' and 'Hangul Syllables' ranges. In these ranges, font settings from the map's style will be ignored except for font-weight keywords (light/regular/medium/bold). The purpose of this option is to avoid bandwidth-intensive glyph server requests.
options.collectResourceTiming
Boolean
default:false 		If true, Resource Timing API information will be collected for requests made by GeoJSON and Vector Tile Web Workers (this information is normally inaccessible from the main JavaScript thread). Information will be returned in a resourceTiming property of relevant data events.
options.fadeDuration
Number
default:300 		Controls the duration of the fade-in/fade-out animation for label collisions in milliseconds. This setting affects all symbol layers. This setting does not affect the duration of runtime styling transitions or raster tile cross-fading.
options.crossSourceCollisions
Boolean
default:true 		Controls the duration of the fade-in/fade-out animation for label.
options.attributionControlPosition
String
default:'bottom-right' 		Sets position of attribution control.
options.transformRequest
Function
default:None 		A callback function that runs before the map makes a request for an external URL. This callback can be used to modify the url, set headers or credentials. It takes url and resourceType as input parameters. It's expected to return an object with properties like url, headers, credentials.

This callback can be used to modify the requested parameters of the traffic and incident tiles.
This example shows how to add the trafficLevelStep parameter for the Vector Traffic Flow Tiles: 
transformRequest: function(url, resourceType) {
    if (resourceType === 'Tile' && url.includes('flow')) {
        return { url: url + '&trafficLevelStep=0.2'};
    }
}
For usage please check the Custom incident markers and popups example.

Properties

boxZoom: Maps.BoxZoomHandler

The BoxZoomHandler allows the user to zoom the map to fit within a bounding box. The bounding box is defined by clicking and holding shift while dragging the cursor.

doubleClickZoom: Maps.DoubleClickZoomHandler

The DoubleClickZoomHandler allows the user to zoom the map at a point by double clicking or double tapping.

dragPan: Maps.DragPanHandler

The DragPanHandler allows the user to pan the map by clicking and dragging the cursor.

dragRotate: Maps.DragRotateHandler

The DragRotateHandler allows the user to rotate the map by clicking and dragging the cursor while holding the right mouse button or ctrl key.

keyboard: Maps.KeyboardHandler

The KeyboardHandler allows the user to zoom, rotate, and pan the map using the following keyboard shortcuts:
  • = / +: Increase the zoom level by 1.
  • Shift-= / Shift-+: Increase the zoom level by 2.
  • -: Decrease the zoom level by 1.
  • Shift--: Decrease the zoom level by 2.
  • Arrow keys: Pan by 100 pixels.
  • Shift+⇢: Increase the rotation by 15 degrees.
  • Shift+⇠: Decrease the rotation by 15 degrees.
  • Shift+⇡: Increase the pitch by 10 degrees.
  • Shift+⇣: Decrease the pitch by 10 degrees.

touchPitch: Maps.TouchPitchHandler

The TouchPitchHandler allows the user to pitch the map with touch gestures.

touchZoomRotate: Maps.TouchZoomRotateHandler

The TouchZoomRotateHandler allows the user to zoom and rotate the map by pinching on a touchscreen.

Methods

addControl(plugin, [position]): Maps.Map

Add plugin to the map.

Parameters
Name Description
plugin
Plugin
default:None 		The plugin to add.
position
String
default:None 		The position on the map to which the control will be added. Valid values are 'top-left', 'top-right', 'bottom-left', and 'bottom-right'. Defaults to 'top-right'.
Returns

Map instance

addImage(id, image, options)

Add an image to the style. This image can be used in icon-image, background-pattern, fill-pattern, and line-pattern. An Map#error event will be fired if there is not enough space in the sprite to add this image.

Parameters
Name Description
id
Object
default:None 		The ID of the image.
image
Object
default:None 		The image as an HTMLImageElement, ImageData, or object with width, height, and data properties with the same format as ImageData.
options
Object
default:None
options.pixelRatio

default:None 		The ratio of pixels in the image to physical pixels on the screen
options.sdf

default:None 		Whether the image should be interpreted as an SDF image

addLayer(layer, [before]): Maps.Map

Adds a style layer to the map's style. A layer defines styling for data from a specified source.

Parameters
Name Description
layer
Object
default:None 		The style layer to add. To learn more about layer properties, please refer to Map Style Specification - Layer properties.
before
String
default:None 		The ID of an existing layer to insert before the new layer. If this argument is omitted, the layer will be appended to the end of the layers array.
Returns

This

addSource(id, source): Maps.Map

Adds a source to the map's style.

Parameters
Name Description
id
String
default:None 		The ID of the source to add. Must not conflict with existing sources.
source
Object
default:None 		The source object, conforming to the style specification. To learn more about source properties, please refer to Map Style Specification - Source properties.
Returns

This

areTilesLoaded( ): Boolean

Returns a Boolean indicating whether all tiles in the viewport from all sources on the style are loaded.

Returns

A Boolean indicating whether all tiles are loaded.

cameraForBounds(bounds, [options]): ICameraOptions | undefined

Parameters
Name Description
bounds
Maps.LngLatBounds
default:None 		Calculate the center for these bounds in the viewport and use the highest zoom level up to and including map.getMaxZoom() that fits in the viewport. LatLngBounds represent a box that is always axis-aligned with bearing 0.
options
Object
default:None 		Camera options.
options.padding
Object
default:None 		The amount of padding in pixels to add to the given bounds.
options.offset
Maps.Point
default:None 		The center of the given bounds relative to the map's center measured in pixels.
options.maxZoom
Number
default:None 		The maximum zoom level to allow when the map view transitions
Returns

If map is able to fit to provided bounds, returns camera options with center, zoom, and bearing. If map is unable to fit, method will warn and return undefined.

easeTo(options, [eventData]): Maps.Map

Changes any combination of center, zoom, bearing, and pitch, with an animated transition between old and new values. The map will retain its current values for any details not specified in options.

Parameters
Name Description
options
ICameraOptions | IAnimationOptions
default:None 		Camera and animation options.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

fitBounds(bounds, [options]): Maps.Map

Pans and zooms the map to contain its visible area within the specified geographical bounds. This function will also reset the map's bearing to 0 if the bearing is nonzero.

Example
var bounds = [[-10, 52], [10, 55]];
tt.map.fitBounds(bounds, {
 padding: { top: 10, bottom:25, left: 15, right: 5 }
 maxZoom: 12
});
Parameters
Name Description
bounds
Maps.LngLatBounds
default:None 		Center these bounds in the viewport and use the highest zoom level up to and including getMaxZoom that fits them in the viewport.
options
Object
default:None 		Options supports all properties from IAnimationOptions and ICameraOptions in addition to the fields below.
options.padding
Object
default:None 		The amount of padding in pixels to add to the given bounds.
options.linear
Boolean
default:None 		If true, the map transitions using Map#easeTo. If false, the map transitions using Map#flyTo. See those functions and AnimationOptions for information about the options available.
options.easing
Function
default:None 		An easing function for the animated transition.
options.offset
Maps.Point
default:None 		The center of the given bounds relative to the map's center measured in pixels.
options.maxZoom
Number
default:None 		The maximum zoom level to allow when the map view transitions to the specified bounds and fields listed in the example.
Returns

Map instance

flyTo([options], [eventData]): Maps.Map

Changes any combination of center, zoom, bearing, and pitch, animating the transition along a curve that evokes flight. The animation seamlessly incorporates zooming and panning to help users maintain their bearings even after traversing a great distance.

Parameters
Name Description
options
Object
default:None 		Options supports all properties from IAnimationOptions and ICameraOptions in addition to the fields below.
options.curve
Number
default:1.42 		The zooming "curve" that will occur along the flight path. A high value maximizes zooming for an exaggerated animation, while a low value minimizes zooming for an effect closer to Map#easeTo. 1.42 is the average value selected by participants in the user study discussed in van Wijk (2003). A value of Math.pow(6, 0.25) would be equivalent to the root mean squared average velocity. A value of 1 would produce a circular motion.
options.minZoom
Number
default:None 		The zero-based zoom level at the peak of the flight path. If options.curve is specified, this option is ignored.
options.speed
Number
default:1.2 		The average speed of the animation defined in relation to options.curve. A speed of 1.2 means that the map appears to move along the flight path by 1.2 times options.curve screenfuls every second. A screenful is the map's visible span. It does not correspond to a fixed physical distance, but varies by zoom level.
options.screenSpeed
Number
default:None 		The average speed of the animation measured in screenfuls per second assuming a linear timing curve. If options.speed is specified, this option is ignored.
options.maxDuration
Number
default:None 		The animation's maximum duration measured in milliseconds. If duration exceeds maximum duration it resets to 0.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

getBearing( ): Number

Returns the map's current bearing. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.

Returns

The map's current bearing.

getBounds( ): Maps.LngLatBounds

Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.

Returns

getCanvasContainer( ): HTMLElement

Returns the HTML element containing the map's <canvas> element. If you want to add non-GL overlays to the map, you should append them to this element. This is the element to which event bindings for map interactivity (such as panning and zooming) are attached. It will receive bubbled events from child elements such as the <canvas>, but not from map controls.

Returns

The container of the map's canvas.

getContainer( ): HTMLElement

Returns the map's containing HTML element.

Returns

The map's container.

getFeatureState(feature, key): Object

Gets the state of a feature. Features are identified by their id attribute, which must be an integer or a string that can be cast to an integer.

Parameters
Name Description
feature
Object
default:None 		Feature identifier. Feature objects returned from map.queryRenderedFeatures(). or event handlers can be used as feature identifiers.
feature.id
String | Number
default:None 		Unique id of the feature. If string is being passed, it has to be castable to integer.
feature.source
String
default:None 		The Id of the vector source or GeoJSON source for the feature.
feature.sourceLayer
String
default:None 		For vector tile sources, the sourceLayer is required.
key
String
default:None 		The key in the feature state to reset.
Returns

The state of the feature.

getFilter(layer): Array

Returns the filter applied to the specified style layer.

Parameters
Name Description
layer
String
default:None 		The ID of the style layer whose filter to get.
Returns

The layer's filter.

getGeopoliticalView( ): String

This method returns a geopolitical view set.

Returns

getLanguage( ): String

This method returns a language set.

Returns

getLayer(id): Object

Returns the layer with the specified ID in the map's style.

Parameters
Name Description
id
String
default:None 		The ID of the layer to get.
Returns

The layer with the specified ID, or undefined if the ID corresponds to no existing layers.

getLayoutProperty(layer, name): Any

Returns the value of a layout property in the specified style layer.

Parameters
Name Description
layer
String
default:None 		The ID of the layer to get the layout property from.
name
String
default:None 		The name of the layout property to get.
Returns

The value of the specified layout property.

getMaxZoom( ): Number

Returns the map's maximum allowable zoom level.

Returns

maxZoom.

getMinZoom( ): Number

Returns the map's minimum allowable zoom level.

Returns

minZoom.

getPaintProperty(layer, name): Any

Returns the value of a paint property in the specified style layer.

Parameters
Name Description
layer
String
default:None 		The ID of the layer to get the paint property from.
name
String
default:None 		The name of a paint property to get.
Returns

The value of the specified paint property.

getPitch( ): Number

Returns the map's current pitch (tilt).

Returns

The map's current pitch measured in degrees away from the plane of the screen.

getStyle( ): Object

Returns the map's style object which can be used to recreate the map's style.

Returns

The map's style object.

getZoom( ): Number

Returns the map's current zoom level.

Returns

The map's current zoom level.

hasControl(plugin): Boolean

Checks if a control is on the map.

Parameters
Name Description
plugin
Plugin
default:None 		The plugin to check.
Returns

True if map contains control.

hasImage(id): Boolean

Returns the source with the specified ID in the map's style.

Parameters
Name Description
id
String
default:None 		The ID of the image.
Returns

A Boolean indicating whether the image exists.

hidePOI( )

Hides the POI layer on the map.

Note: For custom traffic styles, this method will work only if sources conform to given sourceName (hidePOI() will only work if sourceName for trafficFlow will be poiTiles).

hideTrafficFlow( )

Hides a traffic flow layer on the map.

Note: For custom traffic styles, this method will work only if sources conform to given sourceName (hideTrafficFlow() will only work if sourceName for trafficFlow will be vectorTilesFlow).

hideTrafficIncidents( )

Hides traffic incidents layer on the map.

Note: For custom traffic styles, this method will work only if sources conform to given sourceName (hideTrafficIncidents() will only work if sourceName property for trafficIncidents will be vectorTilesIncidents).

isMoving( ): Boolean

Returns true if the map is panning, zooming, rotating, or pitching due to a camera animation or user gesture.

Returns

isRotating( ): Boolean

Returns true if the map is rotating due to a camera animation or user gesture.

Returns

isSourceLoaded(id): Boolean

Returns a Boolean indicating whether the source is loaded.

Parameters
Name Description
id
String
default:None 		The ID of the source to be checked.
Returns

A Boolean indicating whether the source is loaded.

isStyleLoaded( ): Boolean

Returns a Boolean indicating whether the map's style is fully loaded.

Returns

A Boolean indicating whether the style is fully loaded.

isZooming( ): Boolean

Returns true if the map is zooming due to a camera animation or user gesture.

Returns

jumpTo([options], [eventData]): Maps.Map

Changes any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not specified in options.

Parameters
Name Description
options
Object
default:None 		Options supports all properties from ICameraOptions.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

listImages( ): Array

Returns an Array of strings containing the IDs of all images currently available in the map. This includes both images from the style's original sprite and any images that have been added at runtime using map.addImage().

Returns

An Array of strings containing the names of all sprites/images currently available in the map.

loaded( ): Boolean

Returns a Boolean indicating whether the map is fully loaded. Returns false if the style is not yet fully loaded, or if there has been a change to the sources or style that has not yet fully loaded.

Returns

A Boolean indicating whether the map is fully loaded.

loadImage(url, callback)

Load an image from an external URL for use with Map#addImage. External domains must support CORS.

Parameters
Name Description
url
String
default:None 		The URL of the image file. Image file must be in png, webp, or jpg format.
callback
Function
default:None 		Expecting callback(error, data). Called when the image has loaded or with an error argument if there is an error.

moveLayer(id, [beforeId]): Maps.Map

Moves a layer to a different z-position.

Parameters
Name Description
id
String
default:None 		The ID of the layer to move.
beforeId
String
default:None 		The ID of an existing layer to insert before the new layer. If this argument is omitted, the layer will be appended to the end of the layers array.
Returns

This

off(type, layerId, listener): Maps.Map

Removes an event listener previously added with Map.on.

Parameters
Name Description
type
String
default:None 		The event type previously used to install the listener.
layerId
String
default:None 		The layer ID previously used to install the listener.
listener
Function
default:None 		The function previously installed as a listener.
Returns

This

off(type, listener): Maps.Map

Removes an event listener previously added with Map.on.

Parameters
Name Description
type
String
default:None 		The event type previously used to install the listener.
listener
Function
default:None 		The function previously installed as a listener.
Returns

This

on(type, layerId, listener): Maps.Map

Adds a listener for events of a specified type occurring on features in a specified style layer.

Parameters
Name Description
type
String
default:None 		The event type to listen for; one of 'mousedown' , 'mouseup' , 'click' , 'dblclick' , 'mousemove' , 'mouseenter' , 'mouseleave' , 'mouseover' , 'mouseout' , 'contextmenu' , 'touchstart' , 'touchend' , or 'touchcancel' . mouseenter and mouseover events are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. mouseleave and mouseout events are triggered when the cursor leaves a visible portion of the specified layer, or leaves the map canvas.
layerId
String
default:None 		The ID of a style layer. Only events whose location is within a visible feature in this layer will trigger the listener. The event will have a features property containing an array of the matching features.
listener
Function
default:None 		The function to be called when the event is fired.
Returns

This

on(type, listener): Maps.Map

Adds a listener for events of a specified type occurring on features in a specified style layer.

Parameters
Name Description
type
String
default:None 		The event type to add a listen for.
listener
Function
default:None 		The function to be called when the event is fired. The listener function is called with the data object passed to fire, extended with target and type properties.
Returns

This

once(type, listener): Maps.Map

Adds a listener that will be called only once to a specified event type. The listener will be called the first time the event fires after the listener is registered.

Parameters
Name Description
type
String
default:None 		The event type to add a listen for.
listener
Function
default:None 		The function to be called when the event is fired the first time.
Returns

This

once(type, layerId, listener): Maps.Map

Adds a listener that will be called only once to a specified event type occurring on features in a specified style layer.

Parameters
Name Description
type
String
default:None 		The event type to listen for; one of 'mousedown', 'mouseup', 'click', 'dblclick', 'mousemove', 'mouseenter', 'mouseleave', 'mouseover', 'mouseout', 'contextmenu', 'touchstart', 'touchend', or 'touchcancel'. mouseenter and mouseover events are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. mouseleave and mouseout events are triggered when the cursor leaves a visible portion of the specified layer, or leaves the map canvas.
layerId
String
default:None 		The ID of a style layer. Only events whose location is within a visible feature in this layer will trigger the listener. The event will have a features property containing an array of the matching features.
listener
Function
default:None 		The function to be called when th e event is fired the first time.
Returns

This

panTo(lnglat, [options], [eventData]): Maps.Map

Pans the map to the specified location with an animated transition.

Parameters
Name Description
lnglat
Maps.LngLat
default:None 		The location to pan the map to.
options
Object
default:None 		Animation options.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

project(lnglat): Maps.Point

Returns a Point representing pixel coordinates, relative to the map's container that correspond to the specified geographical location.
When the map is pitched and lnglat is completely behind the camera, there are no pixel coordinates corresponding to that location. In that case, the x and y components of the returned Point are set to Number.MAX_VALUE.

Parameters
Name Description
lnglat
Maps.LngLat
default:None 		The geographical location to project.
Returns

The Point corresponding to lnglat relative to the map's container.

queryRenderedFeatures([geometry], [options]): Array

Returns an array of GeoJSON Feature objects representing visible features that satisfy the query parameters. The properties value of each returned feature object contains the properties of its source feature. For GeoJSON sources, only string and numeric property values are supported (i.e. null, Array, and Object values are not supported). Each feature includes top-level layer, source, and sourceLayer properties. The layer property is an object representing the style layer to which the feature belongs. Layout and paint properties in this object contain values which are fully evaluated for the given zoom level and feature.

Only features that are currently rendered are included. Some features will not be included, like:

  • Features from layers whose visibility property is none;
  • Features from layers whose zoom range excludes the current zoom level;
  • Symbol features that have been hidden due to text or icon collision.

Features from all other layers are included, including features that may have no visible contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to 0. The topmost rendered feature appears first in the returned array, and subsequent features are sorted by descending z-order. Features that are rendered multiple times (due to wrapping across the antimeridian at low zoom levels) are returned only once (though subject to the following caveat).

Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering.

Parameters
Name Description
geometry
Object | Array
default:None 		The geometry of the query region: either a single point or southwest and northeast points describing a bounding box. Omitting this parameter (i.e. calling Map.queryRenderedFeatures with zero arguments, or with only a options argument) is equivalent to passing a bounding box encompassing the entire map viewport.
options
Object
default:None 		Object with options.
options.layers
Array
default:None 		An array of style layer IDs for the query to inspect. Only features within these layers will be returned. If this parameter is undefined, all layers will be checked.
options.filter
Array
default:None 		A filter to limit query results.
options.validate
Boolean
default:true 		Whether to check if the options.filter conforms to the Style Specification.
Returns

An array of GeoJSON feature objects.

querySourceFeatures(sourceId, [options]): Array

Returns an array of GeoJSON Feature objects . In contrast to map.queryRenderedFeatures(), this function returns all features matching the query parameters, whether or not they are rendered by the current style (i.e. visible). The domain of the query includes all currently-loaded vector tiles and GeoJSON source tiles: this function does not check tiles outside the currently visible viewport.

Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering.

Parameters
Name Description
sourceId
String
default:None 		The ID of the vector tile or GeoJSON source to query.
options
Object
default:None
options.sourceLayer
String
default:None 		The name of the source layer to query. For vector tile sources, this parameter is required. For GeoJSON sources, it is ignored.
options.filter
Array
default:None 		A filter to limit query results.
options.validate
Boolean
default:true 		Whether to check if the options.filter conforms to the Style Specification.
Returns

Returns an array of GeoJSON Feature objects representing features within the specified vector tile or GeoJSON source that satisfy the query parameters.

remove( )

Clean up and release all internal resources associated with this map. This includes DOM elements, event bindings, Web Workers, and WebGL resources. Use this method when you are done using the map and wish to ensure that it no longer consumes browser resources. Afterwards, you must not call any other methods on the map.

removeControl(plugin): Maps.Map

Removes the plugin from the map.

Parameters
Name Description
plugin
Plugin
default:None 		The plugin to remove.
Returns

Map instance

removeFeatureState(target): Maps.Map

Removes feature state, setting it back to the default behavior. If only source is specified, removes all states of that source. If target.id is also specified, removes all keys for that feature's state. If key is also specified, removes that key from that feature's state. Features are identified by their id attribute, which must be an integer or a string that can be cast to an integer.

Parameters
Name Description
target
Object
default:None 		Identifier of where to set state: can be a source, a feature, or a specific key of feature. Feature objects returned from map.queryRenderedFeatures() or event handlers can be used as feature identifiers.
target.id
String | Number
default:None 		Unique id of the feature. Optional if key is not specified. If string is being passed, it has to be castable to integer.
target.source
String
default:None 		The Id of the vector source or GeoJSON source for the feature.
target.sourceLayer
String
default:None 		For vector tile sources, the sourceLayer is required.
Returns

This

removeImage(id)

Remove an image from a style. This can be an image from the style's original sprite or any images that have been added at runtime using map.addImage().

Parameters
Name Description
id
String
default:None 		The ID of the image.

removeLayer(id)

Removes the layer with the given id from the map's style. If no such layer exists, an error event is fired.

Parameters
Name Description
id
String
default:None 		The ID of the layer to remove.

removeSource(id): Maps.Map

Removes a source from the map's style.

Parameters
Name Description
id
String
default:None 		The ID of the source to remove.
Returns

This

resetNorthPitch( )

Rotates and pitches the map so that north is up (0° bearing) and pitch is 0°, with an animated transition.

resize([eventData]): Maps.Map

Resizes the map according to the dimensions of its container element. This method must be called after the map's container is resized by another script or when the map is shown after being initially hidden with CSS.

Parameters
Name Description
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

rotateTo(bearing, [options], [eventData]): Maps.Map

Rotates the map to the specified bearing with an animated transition. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that East is up.

Example
var bounds = [[-10, 52], [10, 55]];
tt.map.rotateTo(30, {
 duration: 5000,
 easing: function(t) { return t; }
 offset: [0, 50],
 animate: true
});
Parameters
Name Description
bearing
Number
default:None 		The desired bearing.
options
ICameraOptions
default:None 		Animation options.
duration
Number
default:None 		The animation's duration measured in milliseconds.
easing
Function
default:None 		A function taking a time in the range 0..1 and returning a number where 0 is the initial state and 1 is the final state.
offset
Maps.Point
default:None 		Offset of the target center relative to the real map container center at the end of animation.
animate
Boolean
default:None 		If false, no animation will occur.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

setBearing(bearing, [eventData]): Maps.Map

Sets the map's bearing (rotation). The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that East is up. Equivalent to jumpTo({bearing: bearing}).

Parameters
Name Description
bearing
Number
default:None 		The desired bearing.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

setCenter(lnglat, [eventData]): Maps.Map

Sets the map's geographical centerpoint. Equivalent to jumpTo({center: center}).

Parameters
Name Description
lnglat
Maps.LngLat
default:None 		The centerpoint to set.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

setFeatureState(feature, state): Maps.Map

Sets the state of a feature. The state object is merged in with the existing state of the feature. Features are identified by their id attribute, which must be an integer or a string that can be cast to an integer.

Parameters
Name Description
feature
Object
default:None 		Feature identifier. Feature objects returned from map.queryRenderedFeatures() or event handlers can be used as feature identifiers.
feature.id
String | Number
default:None 		Unique id of the feature. If string is being passed, it has to be castable to integer.
feature.source
String
default:None 		The Id of the vector source or GeoJSON source for the feature.
feature.sourceLayer
String
default:None 		For vector tile sources, the sourceLayer is required.
state
Object
default:None 		A set of key-value pairs. The values should be valid JSON types. This method requires the feature.id attribute on data sets. For GeoJSON sources without feature ids, set the generateId option in the GeoJSON source specification to auto-assign them. This option assigns ids based on a feature's index in the source data. If you change feature data using map.getSource('some id').setData(..), you may need to re-apply state taking into account updated id values.
Returns

This

setFilter(layer, filter, [options={}]): Maps.Map

Sets the filter for the specified style layer.

Example
map.setFilter('my-layer', ['==', 'name', 'USA']);
Parameters
Name Description
layer
String
default:None 		The ID of the layer to which the filter will be applied.
filter
Array | Null | Undefined
default:None 		The filter, conforming to the style specification's filter definition. If null or undefined is provided, the function removes any existing filter from the layer.
options
Object
default:{}
options.validate
Object
default:true 		Whether to check if the filter conforms to the style specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
Returns

This

setGeopoliticalView(geopoliticalView)

This method sets a geopolitical view for a map. This setting will only affect map tiles and not other services, e.g., search. Providing an empty string ('') as an input value will unset this option. Supported geopolitical views can be obtained from here.

Parameters
Name Description
geopoliticalView
String
default:None

setLanguage(language)

This method sets a language for a map. This setting will affect only map tiles and not other services, e.g., search. Providing an empty string ('') as an input value will unset this option. Supported languages can be obtained from the list of: Supported Languages page.

Parameters
Name Description
language
String
default:None

setLayerZoomRange(layerId, minzoom, maxzoom): Maps.Map

The ID of the layer to which the zoom extent will be applied.

Example
map.setLayerZoomRange('my-layer', 2, 5);
Parameters
Name Description
layerId
String
default:None 		The ID of the layer to which the zoom extent will be applied.
minzoom
Number
default:None 		The minimum zoom to set (0-24).
maxzoom
Number
default:None 		The maximum zoom to set (0-24).
Returns

This

setLayoutProperty(layer, name, value, [options={}]): Maps.Map

Sets the value of a layout property in the specified style layer.

Parameters
Name Description
layer
String
default:None 		The ID of the layer to set the layout property in.
name
String
default:None 		The name of the layout property to set.
value
Any
default:None 		The value of the layout propery. Must be of a type appropriate for the property.
options
Object
default:{}
options.validate
Object
default:true 		Whether to check if the filter conforms to the style specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
Returns

This

setMaxBounds(bounds): Maps.Map

Sets or clears the map's geographical bounds. Pan and zoom operations are constrained within these bounds. If a pan or zoom is performed that would display regions outside of these bounds, the map will instead display a position and zoom level as close as possible to the operation's request while still remaining within the bounds.

Parameters
Name Description
bounds
Maps.LngLatBounds | Null | Undefined
default:None 		The maximum bounds to set. If null or undefined is provided, the function removes the map's maximum bounds.
Returns

Map instance

setMaxZoom(maxZoom): Maps.Map

Sets or clears the map's maximum zoom level. If the map's current zoom level is higher than the new maximum, the map will zoom to the new maximum.

Parameters
Name Description
maxZoom
Number | Null | Undefined
default:None 		The maximum zoom level to set. If null or undefined is provided, the function removes the current maximum zoom (sets it to 22).
Returns

Map instance

setMinZoom(minZoom): Maps.Map

Sets or clears the map's minimum zoom level. If the map's current zoom level is lower than the new minimum, the map will zoom to the new minimum.

Parameters
Name Description
minZoom
Number | Null | Undefined
default:None 		The minimum zoom level to set (0-24). If null or undefined is provided, the function removes the current minimum zoom (i.e., sets it to 0).
Returns

Map instance

setPaintProperty(layer, name, value, [options={}]): Maps.Map

Sets the value of a paint property in the specified style layer.

Parameters
Name Description
layer
String
default:None 		The ID of the layer to set the paint property in.
name
String
default:None 		The name of the paint property to set.
value
Any
default:None 		The value of the paint propery to set. Must be of a type appropriate for the property.
options
Object
default:{}
options.validate
Object
default:true 		Whether to check if the filter conforms to the style specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
Returns

This

setPitch(pitch, [eventData]): Maps.Map

Sets the map's pitch (tilt). Equivalent to jumpTo({pitch: pitch}).

Parameters
Name Description
pitch
Number
default:None 		The pitch to set, measured in degrees away from the plane of the screen (0-60).
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

setStyle(style): Maps.Map

Sets map style. Visibility of certain layers of the style is altered by options.stylesVisibility. If you modified the style in any way (e.g. by adding new layers), the changes you made won't be preserved after calling map.setStyle().

Parameters
Name Description
style
String | Object
default:None 		Map style It can be one of following types:
  • URL to the JSON object conforming to the schema described in the Map Style Specification. Provided URL should follow this pattern: https://api.tomtom.com/style/1/style/<STYLES_VERSION>&map=<MAP_STYLE>&traffic_incidents=<INCIDENTS_STYLE>&traffic_flow=<FLOW_STYLE>&poi=<POI_STYLE>
where:
* STYLES_VERSION - version number of the Map Styles
* MAP_STYLE - name of the Map Style
* INCIDENTS_STYLE - name of the Traffic Incidents Style
* FLOW_STYLE - name of the Traffic Flow Style

* POI_STYLE - name of the POI Style
  • JSON object conforming to the mentioned specification.
  • Configuration object e.g.: style: { map: 'basic_main', poi: 'poi_main', trafficIncidents: 'incidents_day', trafficFlow: 'flow_relative' }
List of styles supported provided by TomTom can be found in Map styles service (Merged style method section).
Returns

This

setZoom(zoom, [eventData]): Maps.Map

Sets the map's zoom level. Equivalent to jumpTo({zoom: zoom}).

Parameters
Name Description
zoom
Number
default:None 		The zoom level to set (0-20).
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

showPOI( )

Displays the POI layer on the map. Note: For custom POI styles, this method will work only if sources conform to given sourceName (showPOI() will only work if sourceName property for trafficFlow will be poiTiles).

showTrafficFlow( )

Displays traffic flow on the map. To see how to set a traffic style different to the default one, please have a look at the options.style parameter description.

Note: For custom traffic styles, this method will work only if sources conform to given sourceName (showTrafficFlow() will only work if sourceName property for trafficFlow will be vectorTilesFlow).

showTrafficIncidents( )

Displays a traffic incidents layer on the map. To see how to set a traffic style different to the default one, please have a look at the options.style parameter description.

Note: For custom traffic styles, this method will work only if sources conform to given sourceName (showTrafficIncidents() will only work if sourceName property for trafficIncidents will be vectorTilesIncidents).

stop( ): Maps.Map

Stops any animated transition underway.

Returns

Map instance

triggerRepaint( )

Trigger the rendering of a single frame. Use this method with custom layers to repaint the map when the layer changes. Calling this multiple times before the next frame is rendered will still result in only a single frame being rendered.

unproject(point): Maps.LngLat

Returns a LngLat representing geographical coordinates that correspond to the specified pixel coordinates.

Parameters
Name Description
point
Maps.Point
default:None 		The pixel coordinates to unproject.
Returns

The LngLat corresponding to point.

updateImage(id, image)

Parameters
Name Description
id
Object
default:None 		The ID of the image.
image
Object
default:None 		The image as an HTMLImageElement, ImageData, or object with width, height, and data properties with the same format as ImageData.

zoomTo(zoom, [options], [eventData]): Maps.Map

Zooms the map to the specified zoom level with an animated transition.

Parameters
Name Description
zoom
Number
default:None 		The zoom level to transition to.
options
Object
default:None 		Animation options.
eventData
Object
default:None 		Additional properties to be added to event objects of events triggered by this method.
Returns

Map instance

Events

All the class events are keys of the Events static member.

To learn more about how to listen events please refer to the Evented class.

boxzoomcancel : Maps.BoxZoomEvent

Fired when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold.

click : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map.

contextmenu : Maps.MapMouseEvent

Fired when the right button of the mouse is clicked or the context menu key is pressed within the map.

dataloading : Maps.MapDataEvent

Fired when any map data (style, source, tile, etc.) begins loading or changing asyncronously. All dataloading events are followed by a data or error event.

dblclick : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is clicked twice at the same point on the map.

dragend : DragEvent

Fired when a "drag to pan" interaction ends.

dragstart : DragEvent

Fired when a "drag to pan" interaction starts.

error : Object

Fired when an error occurs. This is the primary error reporting mechanism. We use an event instead of throw to better accommodate asyncronous operations. If no listeners are bound to the error event, the error will be printed to the console.

idle

Fired after the last frame rendered before the map enters an "idle" state:
  • No camera transitions are in progress.
  • All currently requested tiles have loaded.
  • All fade/transition animations have completed.

load

Fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred.

mousedown : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is pressed within the map.

mouseenter : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) enters a visible portion of a specified layer from outside that layer or outside the map canvas. This event can only be listened for via the three-argument version of Map#on, where the second argument specifies the desired layer.

mouseleave : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) leaves a visible portion of a specified layer, or leaves the map canvas. This event can only be listened for via the three-argument version of Map.on, where the second argument specifies the desired layer.

mousemove : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is moved within the map.

mouseout : Maps.MapMouseEvent

Fired when a point device (usually a mouse) leaves the map's canvas.

mouseover : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is moved within the map.

mouseup : Maps.MapMouseEvent

Fired when a pointing device (usually a mouse) is released within the map.

move : Maps.MapMouseEvent | Maps.MapTouchEvent

Fired repeatedly during an animated transition from one view to another, as the result of either user interaction or methods such as Map.flyTo.

moveend : DragEvent

Fired just after the map completes a transition from one view to another, as the result of either user interaction or methods such as Map.jumpTo.

movestart : DragEvent

Fired just before the map begins a transition from one view to another, as the result of either user interaction or methods such as Map.jumpTo.

pitch : Maps.MapEventData

Fired whenever the map's pitch (tilt) changes as the result of either user interaction or methods such as Map.flyTo.

pitchend : Maps.MapEventData

Fired immediately after the map's pitch (tilt) finishes changing as the result of either user interaction or methods such as Map.flyTo.

pitchstart : Maps.MapEventData

Fired whenever the map's pitch (tilt) begins a change as the result of either user interaction or methods such as Map.flyTo .

remove

Fired immediately after the map has been removed.

render

Fired whenever the map is drawn to the screen, as the result of:
  • A change to the map's position, zoom, pitch, or bearing.
  • A change to the map's style.
  • A change to a GeoJSON source.
  • The loading of a vector tile, GeoJSON file, glyph, or sprite.

resize

Fired immediately after the map has been resized.

sourcedata : Maps.MapDataEvent

Fired when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes.

sourcedataloading : Maps.MapDataEvent

Fired when one of the map's sources begins loading or changing asyncronously. All sourcedataloading events are followed by a sourcedata or error event.

styledataloading : Maps.MapDataEvent

Fired when the map's style begins loading or changing asyncronously. All styledataloading events are followed by a styledata or error event.

webglcontextlost

Fired when the WebGL context is lost.

webglcontextrestored

Fired when the WebGL context is restored.

zoom : Maps.MapMouseEvent | Maps.MapTouchEvent

Fired repeatedly during an animated transition from one zoom level to another, as the result of either user interaction or methods such as Map.flyTo.

zoomend : Maps.MapMouseEvent | Maps.MapTouchEvent

Fired just after the map completes a transition from one zoom level to another, as the result of either user interaction or methods such as Map.flyTo.

zoomstart : Maps.MapMouseEvent | Maps.MapTouchEvent

Fired just before the map begins a transition from one zoom level to another, as the result of either user interaction or methods such as Map.flyTo.