Nextbillion.ai | The Map Experience for Your Next Billion

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.
Then Nextbillion GL JS initializes the map on the page and returns your Map
object.

Constructor

Name
Map	new Map(options: MapOptions) Parameters options: MapOptions

Properties

Name	Type
repaint	boolean
showCollisionBoxes	boolean
showOverdrawInspector	boolean
showPadding	boolean
showTileBoundaries	boolean
version	string
vertices	boolean

Methods

Method
addControl	addControl(control: IControl, position: ControlPosition) Parameters control: IControl position: ControlPosition Return Value: Map Adds an IControl to the map, calling `control.onAdd(this)` .
addImage	addImage(id: string, image: ImageBitmap \| ImageData \| HTMLImageElement \| StyleImageInterface \| { data: Uint8Array \| Uint8ClampedArray,height: number,width: number }, options: Partial) Parameters id: string image: ImageBitmap \| ImageData \| HTMLImageElement \| StyleImageInterface \| { data: Uint8Array \| Uint8ClampedArray,height: number,width: number } options: Partial Return Value: Map Add an image to the style. This image can be displayed on the map like any other icon in the style's sprite using the image's ID with `icon-image` , `background-pattern` , `fill-pattern` , or `line-pattern` . A Map.event event will be fired if there is not enough space in the sprite to add this image.
addLayer	addLayer(layer: CustomLayerInterface \| { source: string \| SourceSpecification }, beforeId: string) Parameters layer: CustomLayerInterface \| { source: string \| SourceSpecification } beforeId: string Return Value: Map Adds a Nextbillion style layer to the map's style. A layer defines how data from a specified source will be styled. Read more about layer types and available paint and layout properties in the Nextbillion Style Specification. TODO: JSDoc can't pass
addSource	addSource(id: string, source: SourceSpecification) Parameters id: string source: SourceSpecification Return Value: Map Adds a source to the map's style.
addSourceType	addSourceType(name: string, SourceType: any, callback: Callback) Parameters name: string SourceType: any callback: Callback Return Value: void Adds a [custom source type](#Custom Sources), making it available for use with Map#addSource .
areTilesLoaded	areTilesLoaded() Return Value: boolean Returns a Boolean indicating whether all tiles in the viewport from all sources on the style are loaded.
calculateCameraOptionsFromTo	calculateCameraOptionsFromTo(from: LngLat, altitudeFrom: number, to: LngLat, altitudeTo: number) Parameters from: LngLat altitudeFrom: number to: LngLat altitudeTo: number Return Value: CameraOptions Calculates pitch, zoom and bearing for looking at
cameraForBounds	cameraForBounds(bounds: LngLatBoundsLike, options: CameraForBoundsOptions) Parameters bounds: LngLatBoundsLike options: CameraForBoundsOptions Return Value: CenterZoomBearing
easeTo	easeTo(options: CenterZoomBearing, eventData: any) Parameters options: CenterZoomBearing eventData: any Return Value: Map Changes any combination of `center` , `zoom` , `bearing` , `pitch` , and `padding` with an animated transition between old and new values. The map will retain its current values for any details not specified in `options` . Note: The transition will happen instantly if the user has enabled the `reduced motion` accesibility feature enabled in their operating system, unless `options` includes `essential: true` .
fire	fire(event: string \| Event, properties: any) Parameters event: string \| Event properties: any Return Value: Map
fitBounds	fitBounds(bounds: LngLatBoundsLike, options: FitBoundsOptions, eventData: any) Parameters bounds: LngLatBoundsLike options: FitBoundsOptions eventData: any Return Value: 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 bearing is nonzero.
fitScreenCoordinates	fitScreenCoordinates(p0: PointLike, p1: PointLike, bearing: number, options: FitBoundsOptions, eventData: any) Parameters p0: PointLike p1: PointLike bearing: number options: FitBoundsOptions eventData: any Return Value: Map Pans, rotates and zooms the map to to fit the box made by points p0 and p1 once the map is rotated to the specified bearing. To zoom without rotating, pass in the current map bearing.
flyTo	flyTo(options: FlyToOptions, eventData: any) Parameters options: FlyToOptions eventData: any Return Value: 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 the user maintain her bearings even after traversing a great distance. Note: The animation will be skipped, and this will behave equivalently to `jumpTo` if the user has the `reduced motion` accesibility feature enabled in their operating system, unless 'options' includes `essential: true` .
getBearing	getBearing() Return Value: 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.
getBounds	getBounds() Return Value: 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.
getCanvas	getCanvas() Return Value: HTMLCanvasElement Returns the map's `<canvas>` element.
getCanvasContainer	getCanvasContainer() Return Value: 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.
getCenter	getCenter() Return Value: LngLat Returns the map's geographical centerpoint.
getContainer	getContainer() Return Value: HTMLElement Returns the map's containing HTML element.
getFeatureState	getFeatureState(feature: FeatureIdentifier) Parameters feature: FeatureIdentifier Return Value: any Gets the `state` of a feature. A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime. Features are identified by their `feature.id` attribute, which can be any number or string. Note: To access the values in a feature's state object for the purposes of styling the feature, use the `feature-state` expression.
getFilter	getFilter(layerId: string) Parameters layerId: string Return Value: none Returns the filter applied to the specified style layer.
getLayer	getLayer(id: string) Parameters id: string Return Value: StyleLayer Returns the layer with the specified ID in the map's style.
getLayoutProperty	getLayoutProperty(layerId: string, name: string) Parameters layerId: string name: string Return Value: any Returns the value of a layout property in the specified style layer.
getLight	getLight() Return Value: any Returns the value of the light object.
getMaxBounds	getMaxBounds() Return Value: LngLatBounds Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
getMaxPitch	getMaxPitch() Return Value: number Returns the map's maximum allowable pitch.
getMaxZoom	getMaxZoom() Return Value: number Returns the map's maximum allowable zoom level.
getMinPitch	getMinPitch() Return Value: number Returns the map's minimum allowable pitch.
getMinZoom	getMinZoom() Return Value: number Returns the map's minimum allowable zoom level.
getPadding	getPadding() Return Value: PaddingOptions Returns the current padding applied around the map viewport.
getPaintProperty	getPaintProperty(layerId: string, name: string) Parameters layerId: string name: string Return Value: unknown Returns the value of a paint property in the specified style layer.
getPitch	getPitch() Return Value: number Returns the map's current pitch (tilt).
getPixelRatio	getPixelRatio() Return Value: number Returns the map's pixel ratio.
getRenderWorldCopies	getRenderWorldCopies() Return Value: boolean Returns the state of `renderWorldCopies` . If `true` , multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false` : - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude. - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level.
getSource	getSource(id: string) Parameters id: string Return Value: Source Returns the source with the specified ID in the map's style. This method is often used to update a source using the instance members for the relevant source type as defined in Sources. For example, setting the `data` for a GeoJSON source or updating the `url` and `coordinates` of an image source.
getStyle	getStyle() Return Value: StyleSpecification Returns the map's Nextbillion style object, a JSON object which can be used to recreate the map's style.
getTerrain	getTerrain() Return Value: TerrainSpecification Get the terrain-options if terrain is loaded
getZoom	getZoom() Return Value: number Returns the map's current zoom level.
hasControl	hasControl(control: IControl) Parameters control: IControl Return Value: boolean Checks if a control exists on the map.
hasImage	hasImage(id: string) Parameters id: string Return Value: boolean Check whether or not an image with a specific ID exists in the style. This checks both images in the style's original sprite and any images that have been added at runtime using Map#addImage .
isEasing	isEasing() Return Value: boolean
isMoving	isMoving() Return Value: boolean Returns true if the map is panning, zooming, rotating, or pitching due to a camera animation or user gesture.
isRotating	isRotating() Return Value: boolean Returns true if the map is rotating due to a camera animation or user gesture.
isSourceLoaded	isSourceLoaded(id: string) Parameters id: string Return Value: boolean Returns a Boolean indicating whether the source is loaded. Returns `true` if the source with the given ID in the map's style has no outstanding network requests, otherwise `false` .
isStyleLoaded	isStyleLoaded() Return Value: none Returns a Boolean indicating whether the map's style is fully loaded.
isZooming	isZooming() Return Value: boolean Returns true if the map is zooming due to a camera animation or user gesture.
jumpTo	jumpTo(options: JumpToOptions, eventData: any) Parameters options: JumpToOptions eventData: any Return Value: 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` .
listImages	listImages() Return Value: none 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 .
listens	listens(type: string) Parameters type: string Return Value: any Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type.
loadImage	loadImage(url: string, callback: GetImageCallback) Parameters url: string callback: GetImageCallback Return Value: void Load an image from an external URL to be used with Map#addImage . External domains must support CORS.
loaded	loaded() Return Value: 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.
moveLayer	moveLayer(id: string, beforeId: string) Parameters id: string beforeId: string Return Value: Map Moves a layer to a different z-position.
off	off(type: T, layer: string, listener: Function) Parameters type: T layer: string listener: Function Return Value: Map Removes an event listener for layer-specific events previously added with `Map#on` .
on	on(type: T, layer: string, listener: Function) Parameters type: T layer: string listener: Function Return Value: Map Adds a listener for events of a specified type, optionally limited to features in a specified style layer.
once	once(type: T, layer: string, listener: Function) Parameters type: T layer: string listener: Function Return Value: Map Adds a listener that will be called only once to a specified event type occurring on features in a specified style layer.
panBy	panBy(offset: PointLike, options: AnimationOptions, eventData: any) Parameters offset: PointLike options: AnimationOptions eventData: any Return Value: Map Pans the map by the specified offset.
panTo	panTo(lnglat: LngLatLike, options: AnimationOptions, eventData: any) Parameters lnglat: LngLatLike options: AnimationOptions eventData: any Return Value: Map Pans the map to the specified location with an animated transition.
project	project(lnglat: LngLatLike) Parameters lnglat: LngLatLike Return Value: Point Returns a Point representing pixel coordinates, relative to the map's `container` , that correspond to the specified geographical location.
queryRenderedFeatures	queryRenderedFeatures(geometry: PointLike \| , options: any) Parameters geometry: PointLike \| options: any Return Value: none Returns an array of MapGeoJSONFeature objects representing visible features that satisfy the query parameters.
querySourceFeatures	querySourceFeatures(sourceId: string, parameters: { filter: Array<any>,sourceLayer: string,validate: boolean }) Parameters sourceId: string parameters: { filter: Array<any>,sourceLayer: string,validate: boolean } Return Value: none Returns an array of MapGeoJSONFeature objects representing features within the specified vector tile or GeoJSON source that satisfy the query parameters.
redraw	redraw() Return Value: Map Force a synchronous redraw of the map.
remove	remove() Return Value: void 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	removeControl(control: IControl) Parameters control: IControl Return Value: Map Removes the control from the map.
removeFeatureState	removeFeatureState(target: FeatureIdentifier, key: string) Parameters target: FeatureIdentifier key: string Return Value: Map Removes the `state` of a feature, setting it back to the default behavior. If only a `target.source` is specified, it will remove the state for all features from that source. If `target.id` is also specified, it will remove all keys for that feature's state. If `key` is also specified, it removes only that key from that feature's state. Features are identified by their `feature.id` attribute, which can be any number or string.
removeImage	removeImage(id: string) Parameters id: string Return Value: void 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 .
removeLayer	removeLayer(id: string) Parameters id: string Return Value: Map Removes the layer with the given ID from the map's style. If no such layer exists, an `error` event is fired.
removeSource	removeSource(id: string) Parameters id: string Return Value: Map Removes a source from the map's style.
resetNorth	resetNorth(options: AnimationOptions, eventData: any) Parameters options: AnimationOptions eventData: any Return Value: Map Rotates the map so that north is up (0° bearing), with an animated transition.
resetNorthPitch	resetNorthPitch(options: AnimationOptions, eventData: any) Parameters options: AnimationOptions eventData: any Return Value: Map Rotates and pitches the map so that north is up (0° bearing) and pitch is 0°, with an animated transition.
resize	resize(eventData: any) Parameters eventData: any Return Value: Map Resizes the map according to the dimensions of its `container` element. Checks if the map container size changed and updates the map if it has changed. This method must be called after the map's `container` is resized programmatically or when the map is shown after being initially hidden with CSS.
rotateTo	rotateTo(bearing: number, options: AnimationOptions, eventData: any) Parameters bearing: number options: AnimationOptions eventData: any Return Value: 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.
setBearing	setBearing(bearing: number, eventData: any) Parameters bearing: number eventData: any Return Value: 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})` .
setCenter	setCenter(center: LngLatLike, eventData: any) Parameters center: LngLatLike eventData: any Return Value: Map Sets the map's geographical centerpoint. Equivalent to `jumpTo({center: center})` .
setEventedParent	setEventedParent(parent: Evented, data: any) Parameters parent: Evented data: any Return Value: Map Bubble all events fired by this instance of Evented to this parent instance of Evented.
setFeatureState	setFeatureState(feature: FeatureIdentifier, state: any) Parameters feature: FeatureIdentifier state: any Return Value: Map Sets the `state` of a feature. A feature's `state` is a set of user-defined key-value pairs that are assigned to a feature at runtime. When using this method, the `state` object is merged with any existing key-value pairs in the feature's state. Features are identified by their `feature.id` attribute, which can be any number or string. This method can only be used with sources that have a `feature.id` attribute. The `feature.id` attribute can be defined in three ways: - For vector or GeoJSON sources, including an `id` attribute in the original data file. - For vector or GeoJSON sources, using the `promoteId` option at the time the source is defined. - For GeoJSON sources, using the `generateId` option to auto-assign an `id` based on the 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. Note: You can use the `feature-state` expression to access the values in a feature's state object for the purposes of styling.
setFilter	setFilter(layerId: string, filter: FilterSpecification, options: StyleSetterOptions) Parameters layerId: string filter: FilterSpecification options: StyleSetterOptions Return Value: Map Sets the filter for the specified style layer. Filters control which features a style layer renders from its source. Any feature for which the filter expression evaluates to `true` will be rendered on the map. Those that are false will be hidden. Use `setFilter` to show a subset of your source data. To clear the filter, pass `null` or `undefined` as the second parameter.
setLayerZoomRange	setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number) Parameters layerId: string minzoom: number maxzoom: number Return Value: Map Sets the zoom extent for the specified style layer. The zoom extent includes the minimum zoom level and maximum zoom level) at which the layer will be rendered. Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the minimum zoom level of the source layer because the data does not exist at those zoom levels. If the minimum zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style layer will not be rendered at all zoom levels in the zoom range.
setLayoutProperty	setLayoutProperty(layerId: string, name: string, value: any, options: StyleSetterOptions) Parameters layerId: string name: string value: any options: StyleSetterOptions Return Value: Map Sets the value of a layout property in the specified style layer.
setLight	setLight(light: LightSpecification, options: StyleSetterOptions) Parameters light: LightSpecification options: StyleSetterOptions Return Value: Map Sets the any combination of light values.
setMaxBounds	setMaxBounds(bounds: LngLatBoundsLike) Parameters bounds: LngLatBoundsLike Return Value: 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 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.
setMaxPitch	setMaxPitch(maxPitch: number) Parameters maxPitch: number Return Value: Map Sets or clears the map's maximum pitch. If the map's current pitch is higher than the new maximum, the map will pitch to the new maximum.
setMaxZoom	setMaxZoom(maxZoom: number) Parameters maxZoom: number Return Value: 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.
setMinPitch	setMinPitch(minPitch: number) Parameters minPitch: number Return Value: Map Sets or clears the map's minimum pitch. If the map's current pitch is lower than the new minimum, the map will pitch to the new minimum.
setMinZoom	setMinZoom(minZoom: number) Parameters minZoom: number Return Value: 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. It is not always possible to zoom out and reach the set `minZoom` . Other factors such as map height may restrict zooming. For example, if the map is 512px tall it will not be possible to zoom below zoom 0 no matter what the `minZoom` is set to.
setPadding	setPadding(padding: PaddingOptions, eventData: any) Parameters padding: PaddingOptions eventData: any Return Value: Map Sets the padding in pixels around the viewport. Equivalent to `jumpTo({padding: padding})` .
setPaintProperty	setPaintProperty(layerId: string, name: string, value: any, options: StyleSetterOptions) Parameters layerId: string name: string value: any options: StyleSetterOptions Return Value: Map Sets the value of a paint property in the specified style layer.
setPitch	setPitch(pitch: number, eventData: any) Parameters pitch: number eventData: any Return Value: Map Sets the map's pitch (tilt). Equivalent to `jumpTo({pitch: pitch})` .
setPixelRatio	setPixelRatio(pixelRatio: number) Parameters pixelRatio: number Return Value: void Sets the map's pixel ratio. This allows to override `devicePixelRatio` . After this call, the canvas' `width` attribute will be `container.clientWidth * pixelRatio` and its height attribute will be `container.clientHeight * pixelRatio` .
setRenderWorldCopies	setRenderWorldCopies(renderWorldCopies: boolean) Parameters renderWorldCopies: boolean Return Value: Map Sets the state of `renderWorldCopies` .
setStyle	setStyle(style: string \| StyleSpecification, options: StyleOptions) Parameters style: string \| StyleSpecification options: StyleOptions Return Value: Map Updates the map's Nextbillion style object with a new value. If a style is already set when this is used and options.diff is set to true, the map renderer will attempt to compare the given style against the map's current state and perform only the changes necessary to make the map style match the desired state. Changes in sprites (images used for icons and patterns) and glyphs (fonts for label text) cannot be diffed. If the sprites or fonts used in the current style and the given style are different in any way, the map renderer will force a full update, removing the current style and building the given one from scratch.
setTerrain	setTerrain(options: TerrainSpecification) Parameters options: TerrainSpecification Return Value: Map Loads a 3D terrain mesh, based on a "raster-dem" source.
setTransformRequest	setTransformRequest(transformRequest: RequestTransformFunction) Parameters transformRequest: RequestTransformFunction Return Value: Map Updates the requestManager's transform request with a new function
setZoom	setZoom(zoom: number, eventData: any) Parameters zoom: number eventData: any Return Value: Map Sets the map's zoom level. Equivalent to `jumpTo({zoom: zoom})` .
snapToNorth	snapToNorth(options: AnimationOptions, eventData: any) Parameters options: AnimationOptions eventData: any Return Value: Map Snaps the map so that north is up (0° bearing), if the current bearing is close enough to it (i.e. within the `bearingSnap` threshold).
stop	stop() Return Value: Map Stops any animated transition underway.
triggerRepaint	triggerRepaint() Return Value: void 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	unproject(point: PointLike) Parameters point: PointLike Return Value: LngLat Returns a LngLat representing geographical coordinates that correspond to the specified pixel coordinates.
updateImage	updateImage(id: string, image: ImageBitmap \| ImageData \| HTMLImageElement \| StyleImageInterface \| { data: Uint8Array \| Uint8ClampedArray,height: number,width: number }) Parameters id: string image: ImageBitmap \| ImageData \| HTMLImageElement \| StyleImageInterface \| { data: Uint8Array \| Uint8ClampedArray,height: number,width: number } Return Value: Map Update an existing image in a style. This image can be displayed on the map like any other icon in the style's sprite using the image's ID with `icon-image` , `background-pattern` , `fill-pattern` , or `line-pattern` .
zoomIn	zoomIn(options: AnimationOptions, eventData: any) Parameters options: AnimationOptions eventData: any Return Value: Map Increases the map's zoom level by 1.
zoomOut	zoomOut(options: AnimationOptions, eventData: any) Parameters options: AnimationOptions eventData: any Return Value: Map Decreases the map's zoom level by 1.
zoomTo	zoomTo(zoom: number, options: AnimationOptions, eventData: any) Parameters zoom: number options: AnimationOptions eventData: any Return Value: Map Zooms the map to the specified zoom level, with an animated transition.

Example

1
var map = new nextbillion.maps.Map({
2
  container: 'map',
3
  center: [-122.420679, 37.772537],
4
  zoom: 13,
5
  style: style_object,
6
  hash: true,
7
  transformRequest: (url, resourceType)=> {
8
    if(resourceType === 'Source' && url.startsWith('http://myHost')) {
9
      return {
10
       url: url.replace('http', 'https'),
11
       headers: { 'my-custom-header': true},
12
       credentials: 'include'  // Include cookies for cross-origin requests
13
     }
14
    }
15
  }
16
});