MapboxMap

The general class to interact with in the Mapbox Maps SDK for Android. It exposes the entry point for all methods related to the Map object. You cannot instantiate MapboxMap object directly, rather, you must obtain one from the getMapboxMap() method MapView that you have added to your application.

Note: Similar to a View object, a MapboxMap should only be read and modified from the main thread.

Types

Companion
Link copied to clipboard
object Companion

A convenience object to access MapboxMap's static utilities.

Functions

addOnCameraChangeListener
Link copied to clipboard
open override fun addOnCameraChangeListener(onCameraChangeListener: OnCameraChangeListener)

Add a listener that's going to be invoked whenever map camera changes.

addOnMapIdleListener
Link copied to clipboard
open override fun addOnMapIdleListener(onMapIdleListener: OnMapIdleListener)

Add a listener that's going to be invoked whenever map has entered the idle state.

addOnMapLoadedListener
Link copied to clipboard
open override fun addOnMapLoadedListener(onMapLoadedListener: OnMapLoadedListener)

Add a listener that's going to be invoked whenever the Map's style has been fully loaded, and the Map has rendered all visible tiles.

addOnMapLoadErrorListener
Link copied to clipboard
open override fun addOnMapLoadErrorListener(onMapLoadErrorListener: OnMapLoadErrorListener)

Add a listener that's going to be invoked whenever there's a map load error.

addOnRenderFrameFinishedListener
Link copied to clipboard
open override fun addOnRenderFrameFinishedListener(onRenderFrameFinishedListener: OnRenderFrameFinishedListener)

Add a listener that's going to be invoked whenever the Map finished rendering a frame.

addOnRenderFrameStartedListener
Link copied to clipboard
open override fun addOnRenderFrameStartedListener(onRenderFrameStartedListener: OnRenderFrameStartedListener)

Add a listener that's going to be invoked whenever the Map started rendering a frame.

addOnSourceAddedListener
Link copied to clipboard
open override fun addOnSourceAddedListener(onSourceAddedListener: OnSourceAddedListener)

Add a listener that's going to be invoked whenever a source has been added with StyleManager#addStyleSource runtime API.

addOnSourceDataLoadedListener
Link copied to clipboard
open override fun addOnSourceDataLoadedListener(onSourceDataLoadedListener: OnSourceDataLoadedListener)

Add a listener that's going to be invoked whenever the source data has been loaded.

addOnSourceRemovedListener
Link copied to clipboard
open override fun addOnSourceRemovedListener(onSourceRemovedListener: OnSourceRemovedListener)

Add a listener that's going to be invoked whenever a source has been removed with StyleManager#removeStyleSource runtime API.

addOnStyleDataLoadedListener
Link copied to clipboard
open override fun addOnStyleDataLoadedListener(onStyleDataLoadedListener: OnStyleDataLoadedListener)

Add a listener that's going to be invoked whenever the requested style data been loaded. The 'type' property defines what kind of style data has been loaded.

addOnStyleImageMissingListener
Link copied to clipboard
open override fun addOnStyleImageMissingListener(onStyleImageMissingListener: OnStyleImageMissingListener)

Add a listener that's going to be invoked whenever a style has a missing image.

addOnStyleImageUnusedListener
Link copied to clipboard
open override fun addOnStyleImageUnusedListener(onStyleImageUnusedListener: OnStyleImageUnusedListener)

Add a listener that's going to be invoked whenever an image added to the Style is no longer needed and can be removed using StyleManager#removeStyleImage method.

addOnStyleLoadedListener
Link copied to clipboard
open override fun addOnStyleLoadedListener(onStyleLoadedListener: OnStyleLoadedListener)

Add a listener that's going to be invoked whenever the requested style has been fully loaded, including the style specified sprite and sources.

cameraAnimationsPlugin
Link copied to clipboard
open override fun cameraAnimationsPlugin(function: CameraAnimationsPlugin.() -> Any?): Any?

Call extension function on CameraAnimationsPlugin. In most cases should not be called directly.

cameraForCoordinateBounds
Link copied to clipboard
open override fun cameraForCoordinateBounds(bounds: CoordinateBounds, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions

Convert to a camera options from a given LatLngBounds, padding, bearing and pitch values.

cameraForCoordinates
Link copied to clipboard
open override fun cameraForCoordinates(coordinates: List<Point>, camera: CameraOptions, box: ScreenBox): CameraOptions

Convenience method that returns the camera options object for given arguments

open override fun cameraForCoordinates(coordinates: List<Point>, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions

Convert to a camera options from a given list of points, padding, bearing and pitch values.

cameraForGeometry
Link copied to clipboard
open override fun cameraForGeometry(geometry: Geometry, padding: EdgeInsets, bearing: Double?, pitch: Double?): CameraOptions

Convert to a camera options from a given geometry, padding, bearing and pitch values.

clearData
Link copied to clipboard
fun clearData(callback: AsyncOperationResultCallback)

Clears temporary map data.

coordinateBoundsForCamera
Link copied to clipboard
open override fun coordinateBoundsForCamera(camera: CameraOptions): CoordinateBounds

Returns the CoordinateBounds for a given camera.

coordinateBoundsForCameraUnwrapped
Link copied to clipboard
open override fun coordinateBoundsForCameraUnwrapped(camera: CameraOptions): CoordinateBounds

Returns the CoordinateBounds for a given camera.

coordinateBoundsZoomForCamera
Link copied to clipboard
open override fun coordinateBoundsZoomForCamera(camera: CameraOptions): CoordinateBoundsZoom

Returns the coordinate bounds and zoom for a given camera.

coordinateBoundsZoomForCameraUnwrapped
Link copied to clipboard
open override fun coordinateBoundsZoomForCameraUnwrapped(camera: CameraOptions): CoordinateBoundsZoom

Returns the unwrapped coordinate bounds and zoom for a given camera.

coordinateForPixel
Link copied to clipboard
open override fun coordinateForPixel(pixel: ScreenCoordinate): Point

Calculate a geographical coordinate(i.e., longitude-latitude pair) that corresponds to a screen coordinate.

coordinateForProjectedMeters
Link copied to clipboard
open override fun coordinateForProjectedMeters(projectedMeters: ProjectedMeters): Point

Calculate a longitude-latitude pair for a Spherical Mercator projected meters.

coordinatesForPixels
Link copied to clipboard
open override fun coordinatesForPixels(pixels: List<ScreenCoordinate>): List<Point>

Calculate geographical coordinates(i.e., longitude-latitude pair) that corresponds to screen coordinates.

dragEnd
Link copied to clipboard
open override fun dragEnd()

Ends the ongoing drag gesture. This function should be called always after the user has ended a drag gesture initiated by dragStart.

dragStart
Link copied to clipboard
open override fun dragStart(point: ScreenCoordinate)

Prepares the drag gesture to use the provided screen coordinate as a pivot point. This function should be called each time when user starts a dragging action (e.g. by clicking on the map). The following dragging will be relative to the pivot.

executeOnRenderThread
Link copied to clipboard
open override fun executeOnRenderThread(runnable: Runnable)

In some cases querying source / render features is expected to be a blocking operation e.g. performing this action on map click. In this case in order to avoid deadlock on main thread querying could be performed on render thread and in that case querying result will be also delivered on render thread not leading to the main thread deadlock. Example:

gesturesPlugin
Link copied to clipboard
open override fun gesturesPlugin(function: GesturesPlugin.() -> Any?): Any?

Call extension function on GesturesPlugin. In most cases should not be called directly.

getBounds
Link copied to clipboard
open override fun getBounds(): CameraBounds

Get the map bounds options.

getDebug
Link copied to clipboard
fun getDebug(): List<MapDebugOptions>

Get debug options

getDragCameraOptions
Link copied to clipboard
open override fun getDragCameraOptions(fromPoint: ScreenCoordinate, toPoint: ScreenCoordinate): CameraOptions

Calculates target point where camera should move after drag. The method should be called after dragStart and before dragEnd.

getElevation
Link copied to clipboard
fun getElevation(coordinate: Point): Double?

Get elevation for given coordinate. Value is available only for the visible region on the screen, if terrain (DEM) tile is available.

getFeatureState
Link copied to clipboard
fun getFeatureState(sourceId: String, sourceLayerId: String? = null, featureId: String, callback: QueryFeatureStateCallback)

Get the state map of a feature within a style source.

getFreeCameraOptions
Link copied to clipboard
open override fun getFreeCameraOptions(): FreeCameraOptions

Get the map's current free camera options. After mutation, it should be set back to the map.

getGeoJsonClusterChildren
Link copied to clipboard
fun getGeoJsonClusterChildren(sourceIdentifier: String, cluster: Feature, callback: QueryFeatureExtensionCallback)

Returns the children (original points or clusters) of a cluster (on the next zoom level) given its id (cluster_id value from feature properties) from a GeoJsonSource.

getGeoJsonClusterExpansionZoom
Link copied to clipboard
fun getGeoJsonClusterExpansionZoom(sourceIdentifier: String, cluster: Feature, callback: QueryFeatureExtensionCallback)

Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster's cluster_id (cluster_id value from feature properties) from a GeoJsonSource.

getGeoJsonClusterLeaves
Link copied to clipboard
fun getGeoJsonClusterLeaves(sourceIdentifier: String, cluster: Feature, limit: Long = QFE_DEFAULT_LIMIT, offset: Long = QFE_DEFAULT_OFFSET, callback: QueryFeatureExtensionCallback)

Returns all the leaves (original points) of a cluster (given its cluster_id) from a GeoJsonSource, with pagination support: limit is the number of leaves to return (set to Infinity for all points), and offset is the amount of points to skip (for pagination).

getMapOptions
Link copied to clipboard
open override fun getMapOptions(): MapOptions

Get map options.

getMetersPerPixelAtLatitude
Link copied to clipboard
open override fun getMetersPerPixelAtLatitude(latitude: Double): Double

Calculate distance spanned by one pixel at the specified latitude at current zoom level.

open override fun getMetersPerPixelAtLatitude(latitude: Double, zoom: Double): Double

Calculate distance spanned by one pixel at the specified latitude and zoom level.

getPrefetchZoomDelta
Link copied to clipboard
fun getPrefetchZoomDelta(): Byte

Get the prefetch zoom delta

getRenderCacheOptions
Link copied to clipboard
fun getRenderCacheOptions(): RenderCacheOptions

Get the current RenderCacheOptions.

getRenderWorldCopies
Link copied to clipboard
fun getRenderWorldCopies(): Boolean

Returns whether multiple copies of the world are being rendered side by side beyond -180 and 180 degrees longitude.

getResourceOptions
Link copied to clipboard
fun getResourceOptions(): ResourceOptions

Get the ResourceOptions the map was initialized with.

getSize
Link copied to clipboard
open override fun getSize(): Size

Gets the size of the map.

getStyle
Link copied to clipboard
fun getStyle(): Style?

Get the Style of the map synchronously, will return null is style is not loaded yet.

fun getStyle(onStyleLoaded: Style.OnStyleLoaded)

Get the Style of the map asynchronously.

isFullyLoaded
Link copied to clipboard
open override fun isFullyLoaded(): Boolean

Returns if the style has been fully loaded.

isGestureInProgress
Link copied to clipboard
open override fun isGestureInProgress(): Boolean

Returns if a gesture is in progress.

isUserAnimationInProgress
Link copied to clipboard
open override fun isUserAnimationInProgress(): Boolean

Returns if user animation is currently in progress.

isValid
Link copied to clipboard
fun isValid(): Boolean

Whether the MapboxMap instance is valid.

loadStyle
Link copied to clipboard
fun loadStyle(styleExtension: StyleContract.StyleExtension)
fun loadStyle(styleExtension: StyleContract.StyleExtension, onStyleLoaded: Style.OnStyleLoaded)
fun loadStyle(styleExtension: StyleContract.StyleExtension, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)
fun loadStyle(styleExtension: StyleContract.StyleExtension, transitionOptions: TransitionOptions? = null, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)

Load the style from Style Extension.

loadStyleJson
Link copied to clipboard
fun loadStyleJson(styleJson: String)
fun loadStyleJson(styleJson: String, onStyleLoaded: Style.OnStyleLoaded)

Load style JSON.

fun loadStyleJson(styleJson: String, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)
fun loadStyleJson(styleJson: String, styleTransitionOptions: TransitionOptions? = null, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)

Load style JSON

loadStyleUri
Link copied to clipboard
fun loadStyleUri(styleUri: String)
fun loadStyleUri(styleUri: String, onStyleLoaded: Style.OnStyleLoaded)
fun loadStyleUri(styleUri: String, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)
fun loadStyleUri(styleUri: String, styleTransitionOptions: TransitionOptions? = null, onStyleLoaded: Style.OnStyleLoaded? = null, onMapLoadErrorListener: OnMapLoadErrorListener? = null)

Will load a new map style asynchronous from the specified URI.

pixelForCoordinate
Link copied to clipboard
open override fun pixelForCoordinate(coordinate: Point): ScreenCoordinate

Calculate a screen coordinate that corresponds to a geographical coordinate (i.e., longitude-latitude pair).

pixelsForCoordinates
Link copied to clipboard
open override fun pixelsForCoordinates(coordinates: List<Point>): List<ScreenCoordinate>

Calculate screen coordinates that corresponds to geographical coordinates (i.e., longitude-latitude pair).

project
Link copied to clipboard
open override fun project(point: Point, zoomScale: Double): MercatorCoordinate

Calculate a point on the map in Mercator Projection for a given coordinate at the specified zoom scale.

projectedMetersForCoordinate
Link copied to clipboard
open override fun projectedMetersForCoordinate(point: Point): ProjectedMeters

Calculate Spherical Mercator ProjectedMeters coordinates.

queryFeatureExtensions
Link copied to clipboard
fun queryFeatureExtensions(sourceIdentifier: String, feature: Feature, extension: String, extensionField: String, args: HashMap<String, Value>?, callback: QueryFeatureExtensionCallback)

Queries for feature extension values in a GeoJSON source.

queryRenderedFeatures
Link copied to clipboard
open override fun queryRenderedFeatures(geometry: RenderedQueryGeometry, options: RenderedQueryOptions, callback: QueryFeaturesCallback): Cancelable
open override fun queryRenderedFeatures(box: ScreenBox, options: RenderedQueryOptions, callback: QueryFeaturesCallback)
open override fun queryRenderedFeatures(pixel: ScreenCoordinate, options: RenderedQueryOptions, callback: QueryFeaturesCallback)
open override fun queryRenderedFeatures(shape: List<ScreenCoordinate?>, options: RenderedQueryOptions, callback: QueryFeaturesCallback)

Queries the map for rendered features.

querySourceFeatures
Link copied to clipboard
open override fun querySourceFeatures(sourceId: String, options: SourceQueryOptions, callback: QueryFeaturesCallback)

Queries the map for source features.

reduceMemoryUse
Link copied to clipboard
fun reduceMemoryUse()

Reduce memory use. Useful to call when the application gets paused or sent to background.

removeFeatureState
Link copied to clipboard
fun removeFeatureState(sourceId: String, sourceLayerId: String? = null, featureId: String, stateKey: String? = null)

Remove entries from a feature state map.

removeOnCameraChangeListener
Link copied to clipboard
open override fun removeOnCameraChangeListener(onCameraChangeListener: OnCameraChangeListener)

Remove the camera change listener.

removeOnMapIdleListener
Link copied to clipboard
open override fun removeOnMapIdleListener(onMapIdleListener: OnMapIdleListener)

Remove the map idle listener.

removeOnMapLoadedListener
Link copied to clipboard
open override fun removeOnMapLoadedListener(onMapLoadedListener: OnMapLoadedListener)

Remove the map loaded listener.

removeOnMapLoadErrorListener
Link copied to clipboard
open override fun removeOnMapLoadErrorListener(onMapLoadErrorListener: OnMapLoadErrorListener)

Remove the map error listener.

removeOnRenderFrameFinishedListener
Link copied to clipboard
open override fun removeOnRenderFrameFinishedListener(onRenderFrameFinishedListener: OnRenderFrameFinishedListener)

Remove the render frame finished listener.

removeOnRenderFrameStartedListener
Link copied to clipboard
open override fun removeOnRenderFrameStartedListener(onRenderFrameStartedListener: OnRenderFrameStartedListener)

Remove the render frame started listener.

removeOnSourceAddedListener
Link copied to clipboard
open override fun removeOnSourceAddedListener(onSourceAddedListener: OnSourceAddedListener)

Remove the source added listener.

removeOnSourceDataLoadedListener
Link copied to clipboard
open override fun removeOnSourceDataLoadedListener(onSourceDataLoadedListener: OnSourceDataLoadedListener)

Remove the source data loaded listener.

removeOnSourceRemovedListener
Link copied to clipboard
open override fun removeOnSourceRemovedListener(onSourceRemovedListener: OnSourceRemovedListener)

Remove the source removed listener.

removeOnStyleDataLoadedListener
Link copied to clipboard
open override fun removeOnStyleDataLoadedListener(onStyleDataLoadedListener: OnStyleDataLoadedListener)

Remove the style data loaded listener

removeOnStyleImageMissingListener
Link copied to clipboard
open override fun removeOnStyleImageMissingListener(onStyleImageMissingListener: OnStyleImageMissingListener)

Remove the style image missing listener.

removeOnStyleImageUnusedListener
Link copied to clipboard
open override fun removeOnStyleImageUnusedListener(onStyleImageUnusedListener: OnStyleImageUnusedListener)

Remove the style image unused listener.

removeOnStyleLoadedListener
Link copied to clipboard
open override fun removeOnStyleLoadedListener(onStyleLoadedListener: OnStyleLoadedListener)

Remove the style loaded listener.

setBounds
Link copied to clipboard
open override fun setBounds(options: CameraBoundsOptions): Expected<String, None>

Set the map bounds.

setCamera
Link copied to clipboard
open override fun setCamera(cameraOptions: CameraOptions)

Changes the map view by any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not passed via the camera options argument. It is not guaranteed that the provided CameraOptions will be set, the map may apply constraints resulting in a different CameraState.

open override fun setCamera(freeCameraOptions: FreeCameraOptions)

Sets the map view with the free camera options.

setConstrainMode
Link copied to clipboard
open override fun setConstrainMode(constrainMode: ConstrainMode)

Set the map constrain mode

setDebug
Link copied to clipboard
fun setDebug(debugOptions: List<MapDebugOptions>, enabled: Boolean)

Set debug options

setFeatureState
Link copied to clipboard
fun setFeatureState(sourceId: String, sourceLayerId: String? = null, featureId: String, state: Value)

Update the state map of a feature within a style source.

setGestureInProgress
Link copied to clipboard
open override fun setGestureInProgress(inProgress: Boolean)

Notify map about gesture being in progress.

setMemoryBudget
Link copied to clipboard
fun setMemoryBudget(memoryBudget: MapMemoryBudget?)

The memory budget hint to be used by the map. The budget can be given in tile units or in megabytes. A Map will do the best effort to keep memory allocations for a non essential resources within the budget.

setNorthOrientation
Link copied to clipboard
open override fun setNorthOrientation(northOrientation: NorthOrientation)

Set the map north orientation

setPrefetchZoomDelta
Link copied to clipboard
fun setPrefetchZoomDelta(delta: Byte)

Set the prefetch zoom delta

setRenderCacheOptions
Link copied to clipboard
fun setRenderCacheOptions(options: RenderCacheOptions)

Enables or disables the experimental render cache feature.

setRenderWorldCopies
Link copied to clipboard
fun setRenderWorldCopies(renderWorldCopies: Boolean)

Sets whether multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If disabled, 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. In this case, 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.

setUserAnimationInProgress
Link copied to clipboard
open override fun setUserAnimationInProgress(inProgress: Boolean)

Tells the map rendering engine that the animation is currently performed by the user (e.g. with a setCamera() calls series). It adjusts the engine for the animation use case. In particular, it brings more stability to symbol placement and rendering.

setViewportMode
Link copied to clipboard
open override fun setViewportMode(viewportMode: ViewportMode)

Set the map viewport mode

subscribe
Link copied to clipboard
open override fun subscribe(observer: Observer, events: List<String>)

Subscribes an Observer to a provided list of event types. Observable will hold a strong reference to an \sa Observer instance, therefore, in order to stop receiving notifications, caller must call unsubscribe with an \sa Observer instance used for an initial subscription.

triggerRepaint
Link copied to clipboard
fun triggerRepaint()

Triggers a repaint of the map.

unproject
Link copied to clipboard
open override fun unproject(coordinate: MercatorCoordinate, zoomScale: Double): Point

Calculate a coordinate for a given point on the map in Mercator Projection.

unsubscribe
Link copied to clipboard
open override fun unsubscribe(observer: Observer)

Unsubscribes an Observer from all events.

open override fun unsubscribe(observer: Observer, events: List<String>)

Unsubscribes an Observer from a provided list of event types.

Properties

cameraState
Link copied to clipboard
open override val cameraState: CameraState

Represents current camera state.