Maps SDK for Web
tt.Map
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:
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:
|
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.
|
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.
|
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.
|
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:
For usage please check the
Custom incident markers and popups example.
|
Properties
boxZoom: Maps.BoxZoomHandler
doubleClickZoom: Maps.DoubleClickZoomHandler
dragPan: Maps.DragPanHandler
dragRotate: Maps.DragRotateHandler
keyboard: Maps.KeyboardHandler
- = / +: 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.
scrollZoom: Maps.ScrollZoomHandler
touchPitch: Maps.TouchPitchHandler
touchZoomRotate: Maps.TouchZoomRotateHandler
Methods
addControl(plugin, [position]): Maps.Map
Add plugin to the map.
Parameters
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
getAttributionControl( ): Maps.TomTomAttributionControl
Returns a TomTomAttributionControl instance.
Returns
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
getCanvas( ): HTMLCanvasElement
Returns the map's <canvas>
element.
Returns
The map's canvas element.
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.
getCenter( ): Maps.LngLat
The map's geographical centerpoint.
Returns
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
getMaxBounds( ): Maps.LngLatBounds | Null
Returns the maximum geographical bounds the map is constrained to, or null
if none set.
Returns
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
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.
getSource(id): Maps.GeoJSONSource | Maps.ImageSource | Maps.VideoSource | | Maps.CanvasSource | Maps.VectorSource | Object
Returns the source with the specified ID in the map's style.
Parameters
Name | Description |
---|---|
id
String default:None |
The ID of the source to get. |
Returns
The style source with the specified ID, or undefined if the ID corresponds to no existing sources.
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.
moveLayer(id, [beforeId]): Maps.Map
Moves a layer to a different z-position.
Parameters
Returns
This
off(type, layerId, listener): Maps.Map
Removes an event listener previously added with Map.on.
Parameters
Returns
This
off(type, listener): Maps.Map
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
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
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
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
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
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:
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
|
Returns
This
setZoom(zoom, [eventData]): Maps.Map
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)
zoomTo(zoom, [options], [eventData]): Maps.Map
Zooms the map to the specified zoom level with an animated transition.
Parameters
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
boxzoomend : Maps.BoxZoomEvent
boxzoomstart : Maps.BoxZoomEvent
click : Maps.MapMouseEvent
contextmenu : Maps.MapMouseEvent
data : Maps.MapDataEvent
dataloading : Maps.MapDataEvent
dblclick : Maps.MapMouseEvent
drag : Maps.MapMouseEvent | Maps.MapTouchEvent
dragend : DragEvent
dragstart : DragEvent
error : Object
idle
- No camera transitions are in progress.
- All currently requested tiles have loaded.
- All fade/transition animations have completed.
load
mousedown : Maps.MapMouseEvent
mouseenter : Maps.MapMouseEvent
mouseleave : Maps.MapMouseEvent
mousemove : Maps.MapMouseEvent
mouseout : Maps.MapMouseEvent
mouseover : Maps.MapMouseEvent
mouseup : Maps.MapMouseEvent
move : Maps.MapMouseEvent | Maps.MapTouchEvent
moveend : DragEvent
movestart : DragEvent
pitch : Maps.MapEventData
pitchend : Maps.MapEventData
pitchstart : Maps.MapEventData
remove
render
- 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.