Package com.mapbox.mapboxsdk.style.sources

Contains the Mapbox Maps Android Style Sources API classes.

Types

Name Summary
CannotAddSourceException
open class CannotAddSourceException : RuntimeException
Thrown when adding a source to a map twice
CustomGeometrySource
open class CustomGeometrySource : Source
Custom Vector Source, allows using FeatureCollections.
CustomGeometrySourceOptions
open class CustomGeometrySourceOptions : HashMap<String, Any>
Builder class for composing CustomGeometrySource objects.
GeoJsonOptions
open class GeoJsonOptions : HashMap<String, Any>
Builder class for composing GeoJsonSource objects.
GeoJsonSource
@UiThread()
open class GeoJsonSource : Source
GeoJson source, allows using FeatureCollections from Json.
GeometryTileProvider
interface GeometryTileProvider
Interface that defines methods for working with CustomGeometrySource.
ImageSource
@UiThread()
open class ImageSource : Source
Image source, allows a georeferenced raster image to be shown on the map.
RasterDemSource
@UiThread()
open class RasterDemSource : Source
A raster DEM source.
RasterSource
open class RasterSource : Source
Raster source, allows using raster tiles as source.
Source
abstract class Source
Base Peer class for sources.
TileSet
open class TileSet
Tile set, allows using TileJson specification as source.
UnknownSource
@UiThread()
open class UnknownSource : Source
An unknown type of source
VectorSource
@UiThread()
open class VectorSource : Source
Vector source, allows the use of vector tiles.

CannotAddSourceException

open class CannotAddSourceException : RuntimeException

Thrown when adding a source to a map twice

Constructors

Name Summary
CannotAddSourceException open fun CannotAddSourceException(message: String)

Functions

Name Summary
addSuppressed
fun addSuppressed(exception: Throwable)
fillInStackTrace
open fun fillInStackTrace(): Throwable
getCause
open fun getCause(): Throwable
getLocalizedMessage
open fun getLocalizedMessage(): String
getMessage
open fun getMessage(): String
getStackTrace
open fun getStackTrace(): Array
getSuppressed
fun getSuppressed(): Array
initCause
open fun initCause(cause: Throwable): Throwable
printStackTrace
open fun printStackTrace()
setStackTrace
open fun setStackTrace(stackTrace: Array)
toString
open fun toString(): String

CustomGeometrySource

open class CustomGeometrySource : Source

Custom Vector Source, allows using FeatureCollections.

CustomGeometrySource uses a coalescing model for frequent data updates targeting the same tile id, which means, that the in-progress request as well as the last scheduled request are guaranteed to finish. Any requests scheduled meanwhile can be canceled.

Constructors

Name Summary
CustomGeometrySource @UiThread()
open fun CustomGeometrySource(id: String, provider: GeometryTileProvider)Create a CustomGeometrySource
CustomGeometrySource @UiThread()
open fun CustomGeometrySource(id: String, options: CustomGeometrySourceOptions, provider: GeometryTileProvider)Create a CustomGeometrySource with non-default CustomGeometrySourceOptions.

Types

Name Summary
GeometryTileRequest
open class GeometryTileRequest : Runnable
TileID
open class TileID

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
invalidateRegion
open fun invalidateRegion(bounds: LatLngBounds)
Invalidate previously provided features within a given bounds at all zoom levels.Invoking this method will result in new requests to GeometryTileProvider for regionsthat contain, include, or intersect with the provided bounds.
invalidateTile
open fun invalidateTile(zoomLevel: Int, x: Int, y: Int)
Invalidate the geometry contents of a specific tile.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
querySourceFeatures
@NonNull()
open fun querySourceFeatures(filter: Expression): List
Queries the source for features.
setDetached
open fun setDetached()
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setTileData
open fun setTileData(zoomLevel: Int, x: Int, y: Int, data: FeatureCollection)
Set or update geometry contents of a specific tile.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

Properties

Name Summary
THREAD_POOL_LIMIT val THREAD_POOL_LIMIT: Int
THREAD_PREFIX val THREAD_PREFIX: String

THREAD_POOL_LIMIT

val THREAD_POOL_LIMIT: Int

THREAD_PREFIX

val THREAD_PREFIX: String

invalidateRegion

open fun invalidateRegion(bounds: LatLngBounds)

Invalidate previously provided features within a given bounds at all zoom levels.Invoking this method will result in new requests to GeometryTileProvider for regionsthat contain, include, or intersect with the provided bounds.

Parameters
Name Summary
bounds
The region in which features should be invalidated at all zoom levels
   
   

invalidateTile

open fun invalidateTile(zoomLevel: Int, x: Int, y: Int)

Invalidate the geometry contents of a specific tile. Invoking this method will resultin new requests to GeometryTileProvider for visible tiles.

Parameters
Name Summary
zoomLevel
Tile zoom level.
x
Tile X coordinate.
y
Tile Y coordinate.
   
   

querySourceFeatures

@NonNull()

open fun querySourceFeatures(filter: Expression): List

Queries the source for features.

Return

the features

Parameters
Name Summary
filter
an optional filter expression to filter the returned Features
   
   

setTileData

open fun setTileData(zoomLevel: Int, x: Int, y: Int, data: FeatureCollection)

Set or update geometry contents of a specific tile. Use this method to update tilesfor which GeometryTileProvider was previously invoked. This method can be called frombackground threads.

Parameters
Name Summary
zoomLevel
Tile zoom level.
x
Tile X coordinate.
y
Tile Y coordinate.
data
Feature collection for the tile.
   
   

GeometryTileRequest

open class GeometryTileRequest : Runnable

Constructors

Name Summary
GeometryTileRequest open fun GeometryTileRequest(_id: CustomGeometrySource.TileID, p: GeometryTileProvider, awaiting: Map<CustomGeometrySource.TileID, CustomGeometrySource.GeometryTileRequest>, m: Map<CustomGeometrySource.TileID, AtomicBoolean>,_source: CustomGeometrySource, _cancelled: AtomicBoolean)

Functions

Name Summary
equals
open fun equals(o: Any): Boolean
run
open fun run()
abstract fun run()

equals

open fun equals(o: Any): Boolean

run

open fun run()

TileID

open class TileID

Constructors

Name Summary
TileID open fun TileID(_z: Int,_x: Int, _y: Int)

Functions

Name Summary
equals
open fun equals(object: Any): Boolean
hashCode
open fun hashCode(): Int

Properties

Name Summary
x open val x: Int
y open val y: Int
z open val z: Int

equals

open fun equals(object: Any): Boolean

hashCode

open fun hashCode(): Int

x

open val x: Int

y

open val y: Int

z

open val z: Int

CustomGeometrySourceOptions

open class CustomGeometrySourceOptions : HashMap<String, Any>

Builder class for composing CustomGeometrySource objects.

Functions

Name Summary
clear
open fun clear()
clone
open fun clone(): Any
compute
open fun compute(key: K, remappingFunction: BiFunction<out Any, out Any, out V>): V
computeIfAbsent
open fun computeIfAbsent(key: K, mappingFunction: (out Any) -> out V): V
computeIfPresent
open fun computeIfPresent(key: K, remappingFunction: BiFunction<out Any, out Any, out V>): V
containsKey
open fun containsKey(key: Any): Boolean
containsValue
open fun containsValue(value: Any): Boolean
entrySet
open fun entrySet(): Set<Map.Entry<K, V»
equals
open fun equals(o: Any): Boolean
forEach
open fun forEach(action: BiConsumer<out Any, out Any>)
get
open fun get(key: Any): V
getOrDefault
open fun getOrDefault(key: Any, defaultValue: V): V
hashCode
open fun hashCode(): Int
isEmpty
open fun isEmpty(): Boolean
keySet
open fun keySet(): Set<K>
merge
open fun merge(key: K, value: V, remappingFunction: BiFunction<out Any, out Any, out V>): V
put
open fun put(key: K, value: V): V
putAll
open fun putAll(m: Map<out K, out V>)
putIfAbsent
open fun putIfAbsent(key: K, value: V): V
remove
open fun remove(key: Any): V
open fun remove(key: Any, value: Any): Boolean
replace
open fun replace(key: K, value: V): V
open fun replace(key: K, oldValue: V, newValue: V): Boolean
replaceAll
open fun replaceAll(function: BiFunction<out Any, out Any, out V>)
size
open fun size(): Int
toString
open fun toString(): String
values
open fun values(): Collection
withBuffer
@NonNull()
open fun withBuffer(buffer: Int): CustomGeometrySourceOptions
Tile buffer size on each side (measured in 1/512ths of a tile; higher means fewer rendering artifacts near tileedges but slower performance).
withClip
@NonNull()
open fun withClip(clip: Boolean): CustomGeometrySourceOptions
If the data includes geometry outside the tile boundaries, setting this to true clips the geometryto the tile boundaries.
withMaxZoom
@NonNull()
open fun withMaxZoom(maxZoom: Int): CustomGeometrySourceOptions
Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).
withMinZoom
@NonNull()
open fun withMinZoom(minZoom: Int): CustomGeometrySourceOptions
Minimum zoom level at which to create vector tiles (lower means more field of view detail at low zoom levels).
withTolerance
@NonNull()
open fun withTolerance(tolerance: Float): CustomGeometrySourceOptions
Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).
withWrap
@NonNull()
open fun withWrap(wrap: Boolean): CustomGeometrySourceOptions
If the data includes wrapped coordinates, setting this to true unwraps the coordinates.

withBuffer

@NonNull()

open fun withBuffer(buffer: Int): CustomGeometrySourceOptions

Tile buffer size on each side (measured in 1/512ths of a tile; higher means fewer rendering artifacts near tileedges but slower performance).

Return

the current instance for chaining

Parameters
Name Summary
buffer
the buffer size - Defaults to 128.
   
   

withClip

@NonNull()

open fun withClip(clip: Boolean): CustomGeometrySourceOptions

If the data includes geometry outside the tile boundaries, setting this to true clips the geometryto the tile boundaries.

Return

the current instance for chaining

Parameters
Name Summary
clip
defaults to false
   
   

withMaxZoom

@NonNull()

open fun withMaxZoom(maxZoom: Int): CustomGeometrySourceOptions

Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).

Return

the current instance for chaining

Parameters
Name Summary
maxZoom
the maximum zoom - Defaults to 25.5
   
   

withMinZoom

@NonNull()

open fun withMinZoom(minZoom: Int): CustomGeometrySourceOptions

Minimum zoom level at which to create vector tiles (lower means more field of view detail at low zoom levels).

Return

the current instance for chaining

Parameters
Name Summary
minZoom
the minimum zoom - Defaults to 0.
   
   

withTolerance

@NonNull()

open fun withTolerance(tolerance: Float): CustomGeometrySourceOptions

Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).

Return

the current instance for chaining

Parameters
Name Summary
tolerance
the tolerance - Defaults to 0.375
   
   

withWrap

@NonNull()

open fun withWrap(wrap: Boolean): CustomGeometrySourceOptions

If the data includes wrapped coordinates, setting this to true unwraps the coordinates.

Return

the current instance for chaining

Parameters
Name Summary
wrap
defaults to false
   
   

GeoJsonOptions

open class GeoJsonOptions : HashMap<String, Any>

Builder class for composing GeoJsonSource objects.

See also

Name Summary
com.mapbox.mapboxsdk.style.sources.GeoJsonSource  
The online documentation
The online documentation
   

Functions

Name Summary
clear
open fun clear()
clone
open fun clone(): Any
compute
open fun compute(key: K, remappingFunction: BiFunction<out Any, out Any, out V>): V
computeIfAbsent
open fun computeIfAbsent(key: K, mappingFunction: (out Any) -> out V): V
computeIfPresent
open fun computeIfPresent(key: K, remappingFunction: BiFunction<out Any, out Any, out V>): V
containsKey
open fun containsKey(key: Any): Boolean
containsValue
open fun containsValue(value: Any): Boolean
entrySet
open fun entrySet(): Set<Map.Entry<K, V»
equals
open fun equals(o: Any): Boolean
forEach
open fun forEach(action: BiConsumer<out Any, out Any>)
get
open fun get(key: Any): V
getOrDefault
open fun getOrDefault(key: Any, defaultValue: V): V
hashCode
open fun hashCode(): Int
isEmpty
open fun isEmpty(): Boolean
keySet
open fun keySet(): Set<K>
merge
open fun merge(key: K, value: V, remappingFunction: BiFunction<out Any, out Any, out V>): V
put
open fun put(key: K, value: V): V
putAll
open fun putAll(m: Map<out K, out V>)
putIfAbsent
open fun putIfAbsent(key: K, value: V): V
remove
open fun remove(key: Any): V
open fun remove(key: Any, value: Any): Boolean
replace
open fun replace(key: K, value: V): V
open fun replace(key: K, oldValue: V, newValue: V): Boolean
replaceAll
open fun replaceAll(function: BiFunction<out Any, out Any, out V>)
size
open fun size(): Int
toString
open fun toString(): String
values
open fun values(): Collection
withBuffer
@NonNull()
open fun withBuffer(buffer: Int): GeoJsonOptions
Tile buffer size on each side (measured in 1/512ths of a tile; higher means fewer rendering artifacts near tileedges but slower performance).
withCluster
@NonNull()
open fun withCluster(cluster: Boolean): GeoJsonOptions
If the data is a collection of point features, setting this to true clusters the points by radius into groups.
withClusterMaxZoom
@NonNull()
open fun withClusterMaxZoom(clusterMaxZoom: Int): GeoJsonOptions
Max zoom to cluster points on.
withClusterProperty
@NonNull()
open fun withClusterProperty(propertyName: String, operatorExpr: Expression, mapExpr: Expression): GeoJsonOptions
An object defining custom properties on the generated clusters if clustering is enabled,aggregating values from clustered points.
withClusterRadius
@NonNull()
open fun withClusterRadius(clusterRadius: Int): GeoJsonOptions
Radius of each cluster when clustering points, measured in 1/512ths of a tile.
withLineMetrics
@NonNull()
open fun withLineMetrics(lineMetrics: Boolean): GeoJsonOptions
Initialises whether to calculate line distance metrics.
withMaxZoom
@NonNull()
open fun withMaxZoom(maxZoom: Int): GeoJsonOptions
Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).
withMinZoom
@NonNull()
open fun withMinZoom(minZoom: Int): GeoJsonOptions
Minimum zoom level at which to create vector tiles (lower means more field of view detail at low zoom levels).
withTolerance
@NonNull()
open fun withTolerance(tolerance: Float): GeoJsonOptions
Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).

withBuffer

@NonNull()

open fun withBuffer(buffer: Int): GeoJsonOptions

Tile buffer size on each side (measured in 1/512ths of a tile; higher means fewer rendering artifacts near tileedges but slower performance).

Return

the current instance for chaining

Parameters
Name Summary
buffer
the buffer size - Defaults to 128.
   
   

withClusterMaxZoom

@NonNull()

open fun withClusterMaxZoom(clusterMaxZoom: Int): GeoJsonOptions

Max zoom to cluster points on.

Return

the current instance for chaining

Parameters
Name Summary
clusterMaxZoom
clusterMaxZoom cluster maximum zoom - Defaults to one zoom less than maxzoom (so that lastzoom features are not clustered)
   
   

withClusterProperty

@NonNull()

open fun withClusterProperty(propertyName: String, operatorExpr: Expression, mapExpr: Expression): GeoJsonOptions

An object defining custom properties on the generated clusters if clustering is enabled,aggregating values from clustered points. Has the form {“property_name”: [operator, [map_expression]]} or {“property_name”: [[operator, accumulated, expression], [map_expression]]}

Return

the current instance for chaining

Parameters
Name Summary
propertyName
name of the property
operatorExpr
operatorExpr is any expression function that accepts at least 2 operands (e.g. “+” or “max”).It accumulates the property value from clusters/points the cluster contains. It can either bea literal with single operator, or be a valid expression
mapExpr
map expression produces the value of a single point, it shall be a valid expression
   
   

withClusterRadius

@NonNull()

open fun withClusterRadius(clusterRadius: Int): GeoJsonOptions

Radius of each cluster when clustering points, measured in 1/512ths of a tile.

Return

the current instance for chaining

Parameters
Name Summary
clusterRadius
cluster radius - Defaults to 50
   
   

withCluster

@NonNull()

open fun withCluster(cluster: Boolean): GeoJsonOptions

If the data is a collection of point features, setting this to true clusters the points by radius into groups.

Return

the current instance for chaining

Parameters
Name Summary
cluster
cluster? - Defaults to false
   
   

withLineMetrics

@NonNull()

open fun withLineMetrics(lineMetrics: Boolean): GeoJsonOptions

Initialises whether to calculate line distance metrics.

Return

the current instance for chaining

Parameters
Name Summary
lineMetrics
true to calculate line distance metrics.
   
   

withMaxZoom

@NonNull()

open fun withMaxZoom(maxZoom: Int): GeoJsonOptions

Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).

Return

the current instance for chaining

Parameters
Name Summary
maxZoom
the maximum zoom - Defaults to 25.5
   
   

withMinZoom

@NonNull()

open fun withMinZoom(minZoom: Int): GeoJsonOptions

Minimum zoom level at which to create vector tiles (lower means more field of view detail at low zoom levels).

Return

the current instance for chaining

Parameters
Name Summary
minZoom
the minimum zoom - Defaults to 0.
   
   

withTolerance

@NonNull()

open fun withTolerance(tolerance: Float): GeoJsonOptions

Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).

Return

the current instance for chaining

Parameters
Name Summary
tolerance
the tolerance - Defaults to 0.375
   
   

GeoJsonSource

@UiThread()

open class GeoJsonSource : Source

GeoJson source, allows using FeatureCollections from Json.

See also

Name Summary
the style specification
the style specification
   

Constructors

Name Summary
GeoJsonSource open fun GeoJsonSource(nativePtr: Long)Internal use
GeoJsonSource open fun GeoJsonSource(id: String)Create an empty GeoJsonSource
GeoJsonSource open fun GeoJsonSource(id: String, options: GeoJsonOptions)Create an empty GeoJsonSource with non-default GeoJsonOptions.
GeoJsonSource open fun GeoJsonSource(id: String, geoJson: String)Create a GeoJsonSource from a raw json string
GeoJsonSource open fun GeoJsonSource(id: String, geoJson: String, options: GeoJsonOptions)Create a GeoJsonSource from a raw json string and non-default GeoJsonOptions
GeoJsonSource open fun GeoJsonSource(id: String, uri: URI)Create a GeoJsonSource from a geo json URIAn URI is a combination of a protocol and a resource path.
GeoJsonSource open fun GeoJsonSource(id: String, uri: URI, options: GeoJsonOptions)Create a GeoJsonSource from a geo json URI and non-default GeoJsonOptionsAn URI is a combination of a protocol and a resource path.
GeoJsonSource open fun GeoJsonSource(id: String, features: FeatureCollection)Create a GeoJsonSource from a FeatureCollection.
GeoJsonSource open fun GeoJsonSource(id: String, features: FeatureCollection, options: GeoJsonOptions)Create a GeoJsonSource from a FeatureCollection and non-default GeoJsonOptions.
GeoJsonSource open fun GeoJsonSource(id: String, feature: Feature)Create a GeoJsonSource from a Feature
GeoJsonSource open fun GeoJsonSource(id: String, feature: Feature, options: GeoJsonOptions)Create a GeoJsonSource from a Feature and non-default GeoJsonOptions
GeoJsonSource open fun GeoJsonSource(id: String, geometry: Geometry)Create a GeoJsonSource from a Geometry
GeoJsonSource open fun GeoJsonSource(id: String, geometry: Geometry, options: GeoJsonOptions)Create a GeoJsonSource from a Geometry and non-default GeoJsonOptions

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getClusterChildren
@NonNull()
open fun getClusterChildren(cluster: Feature): FeatureCollection
Returns the children of a cluster (on the next zoom level) given its id (cluster_id value from feature properties).
getClusterExpansionZoom
open fun getClusterExpansionZoom(cluster: Feature): Int
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).
getClusterLeaves
@NonNull()
open fun getClusterLeaves(cluster: Feature, limit: Long, offset: Long): FeatureCollection
Returns all the leaves of a cluster (given its cluster_id), with pagination support: limit is the number of leavesto return (set to Infinity for all points), and offset is the amount of points to skip (for pagination).
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
getUri
@Nullable()
open fun getUri(): String
Get the URI of the source.
getUrl
@Nullable()
open fun getUrl(): String
The url or null
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
querySourceFeatures
@NonNull()
open fun querySourceFeatures(filter: Expression): List
Queries the source for features.
setDetached
open fun setDetached()
setGeoJson
open fun setGeoJson(feature: Feature)
Updates the GeoJson with a single feature.
open fun setGeoJson(featureCollection: FeatureCollection)
open fun setGeoJson(json: String)
Updates the GeoJson.
open fun setGeoJson(geometry: Geometry)
Updates the GeoJson with a single geometry.
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setUri
open fun setUri(uri: String)
open fun setUri(uri: URI)
Updates the URI of the source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

getClusterChildren

@NonNull()

open fun getClusterChildren(cluster: Feature): FeatureCollection

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

Requires configuring this source as a cluster by calling withCluster.

Return

a list of features for the underlying children

Parameters
Name Summary
cluster
cluster from which to retrieve children from
   
   

getClusterExpansionZoom

open fun getClusterExpansionZoom(cluster: Feature): Int

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).

Requires configuring this source as a cluster by calling withCluster.

Return

the zoom on which the cluster expands into several children

Parameters
Name Summary
cluster
cluster from which to retrieve the expansion zoom from
   
   

getClusterLeaves

@NonNull()

open fun getClusterLeaves(cluster: Feature, limit: Long, offset: Long): FeatureCollection

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

Requires configuring this source as a cluster by calling withCluster.

Return

a list of features for the underlying leaves

Parameters
Name Summary
cluster
cluster from which to retrieve leaves from
limit
limit is the number of points to return
offset
offset is the amount of points to skip (for pagination)
   
   

getUri

@Nullable()

open fun getUri(): String

Get the URI of the source.

Return

The uri or null

getUrl

@Nullable()

open fun getUrl(): String

Return

The url or null

Deprecated

use getUri instead

querySourceFeatures

@NonNull()

open fun querySourceFeatures(filter: Expression): List

Queries the source for features.

Return

the features

Parameters
Name Summary
filter
an optional filter expression to filter the returned Features
   
   

setGeoJson

open fun setGeoJson(feature: Feature)

Updates the GeoJson with a single feature. The update is performed asynchronously,so the data won’t be immediately visible or available to query when this method returns.

Parameters
Name Summary
feature
the GeoJSON Feature to set
   
   

open fun setGeoJson(geometry: Geometry)

Updates the GeoJson with a single geometry. The update is performed asynchronously,so the data won’t be immediately visible or available to query when this method returns.

Parameters
Name Summary
geometry
the GeoJSON Geometry to set
   
   

open fun setGeoJson(featureCollection: FeatureCollection)

Updates the GeoJson. The update is performed asynchronously,so the data won’t be immediately visible or available to query when this method returns.

Parameters
Name Summary
featureCollection
the GeoJSON FeatureCollection
   
   

open fun setGeoJson(json: String)

Updates the GeoJson. The update is performed asynchronously,so the data won’t be immediately visible or available to query when this method returns.

Parameters
Name Summary
json
the raw GeoJson FeatureCollection string
   
   

setUri

open fun setUri(uri: URI)

Updates the URI of the source.

An URI is a combination of a protocol and a resource path.The following URI protocol schemes are supported:

  • http://
    • load resources using HyperText Transfer Protocol
  • file://
    • load resources from the Android file system
  • asset://
    • load resources from the binary packaged assets folder
Parameters
Name Summary
uri
the GeoJSON FeatureCollection uri
   
   

open fun setUri(uri: String)

Updates the URI of the source.

An URI is a combination of a protocol and a resource path.The following URI protocol schemes are supported:

  • http://
    • load resources using HyperText Transfer Protocol
  • file://
    • load resources from the Android file system
  • asset://
    • load resources from the binary packaged assets folder
Parameters
Name Summary
uri
the GeoJSON FeatureCollection uri
   
   

GeometryTileProvider

interface GeometryTileProvider

Interface that defines methods for working with CustomGeometrySource.

Functions

Name Summary
getFeaturesForBounds
@WorkerThread()
abstract fun getFeaturesForBounds(bounds: LatLngBounds, zoomLevel: Int): FeatureCollection
*Interface method called by CustomGeometrySource to request features for a tile.

getFeaturesForBounds

@WorkerThread()

abstract fun getFeaturesForBounds(bounds: LatLngBounds, zoomLevel: Int): FeatureCollection

*Interface method called by CustomGeometrySource to request features for a tile.

Return

Return a @{link FeatureCollection} to be displayed in the requested tile.

Parameters
Name Summary
bounds
LatLngBounds of the tile.
zoomLevel
Tile zoom level.
   
   

ImageSource

@UiThread()

open class ImageSource : Source

Image source, allows a georeferenced raster image to be shown on the map.

The georeferenced image scales and rotates as the user zooms and rotates the map. The geographic location of the raster image content, supplied with LatLngQuad, can be non-axis aligned.

Constructors

Name Summary
ImageSource open fun ImageSource(nativePtr: Long)Internal use
ImageSource open fun ImageSource(id: String, coordinates: LatLngQuad, uri: URI)Create an ImageSource from coordinates and an image URIAn URI is a combination of a protocol and a resource path.
ImageSource open fun ImageSource(id: String, coordinates: LatLngQuad, bitmap: Bitmap)Create an ImageSource from coordinates and a bitmap image
ImageSource open fun ImageSource(id: String, coordinates: LatLngQuad, resourceId: Int)Create an ImageSource from coordinates and a bitmap image resource

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
getUri
@Nullable()
open fun getUri(): String
Get the source URI.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
setCoordinates
open fun setCoordinates(latLngQuad: LatLngQuad)
Updates the latitude and longitude of the four corners of the image
setDetached
open fun setDetached()
setImage
open fun setImage(bitmap: Bitmap)
Updates the source image to a bitmap
open fun setImage(resourceId: Int)
Updates the source image to a bitmap image resource
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setUri
open fun setUri(uri: String)
open fun setUri(uri: URI)
Updates the source image URI.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

getUri

@Nullable()

open fun getUri(): String

Get the source URI.

Return

The uri or null

setCoordinates

open fun setCoordinates(latLngQuad: LatLngQuad)

Updates the latitude and longitude of the four corners of the image

Parameters
Name Summary
latLngQuad
latitude and longitude of the four corners of the image
   
   

setImage

open fun setImage(bitmap: Bitmap)

Updates the source image to a bitmap

Parameters
Name Summary
bitmap
A Bitmap image
   
   

open fun setImage(resourceId: Int)

Updates the source image to a bitmap image resource

Parameters
Name Summary
resourceId
The resource ID of a Bitmap image
   
   

setUri

open fun setUri(uri: URI)

Updates the source image URI.

An URI is a combination of a protocol and a resource path.The following URI protocol schemes are supported:

  • http://
    • load resources using HyperText Transfer Protocol
  • file://
    • load resources from the Android file system
  • asset://
    • load resources from the binary packaged assets folder
Parameters
Name Summary
uri
An Image uri
   
   

open fun setUri(uri: String)

Updates the source image URI.

An URI is a combination of a protocol and a resource path.The following URI protocol schemes are supported:

  • http://
    • load resources using HyperText Transfer Protocol
  • file://
    • load resources from the Android file system
  • asset://
    • load resources from the binary packaged assets folder
Parameters
Name Summary
uri
An image uri
   
   

RasterDemSource

@UiThread()

open class RasterDemSource : Source

A raster DEM source. Currently only supports Mapbox Terrain RGB (mapbox://mapbox.terrain-rgb)

See also

Name Summary
The style specification
The style specification
   

Constructors

Name Summary
RasterDemSource open fun RasterDemSource(nativePtr: Long)Internal use
RasterDemSource open fun RasterDemSource(id: String, uri: URI)Create the raster dem source from an URI.
RasterDemSource open fun RasterDemSource(id: String, uri: String)Create the raster dem source from an URIAn URI is a combination of a protocol and a resource path.
RasterDemSource open fun RasterDemSource(id: String, uri: String, tileSize: Int)Create the raster source from an URL with a specific tile sizeAn URI is a combination of a protocol and a resource path.
RasterDemSource open fun RasterDemSource(id: String, tileSet: TileSet)Create the raster dem source from a TileSet
RasterDemSource open fun RasterDemSource(id: String, tileSet: TileSet, tileSize: Int)Create the raster source from a TileSet with a specific tile size

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
getUri
@Nullable()
open fun getUri(): String
Get the source URI.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
setDetached
open fun setDetached()
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

Properties

Name Summary
DEFAULT_TILE_SIZE val DEFAULT_TILE_SIZE: Int

DEFAULT_TILE_SIZE

val DEFAULT_TILE_SIZE: Int

getUri

@Nullable()

open fun getUri(): String

Get the source URI.

Return

The uri or null

RasterSource

open class RasterSource : Source

Raster source, allows using raster tiles as source.

See also

Name Summary
The style specification
The style specification
   

Constructors

Name Summary
RasterSource open fun RasterSource(nativePtr: Long)Internal use
RasterSource open fun RasterSource(id: String, url: URL)Create the raster source from an URL
RasterSource open fun RasterSource(id: String, uri: URI)Create the raster source from an URI.
RasterSource open fun RasterSource(id: String, uri: String)Create the raster source from an URI.
RasterSource open fun RasterSource(id: String, uri: String, tileSize: Int)Create the raster source from an URI with a specific tile size.
RasterSource open fun RasterSource(id: String, tileSet: TileSet)Create the raster source from a TileSet
RasterSource open fun RasterSource(id: String, tileSet: TileSet, tileSize: Int)Create the raster source from a TileSet with a specific tile size

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
getUri
@Nullable()
open fun getUri(): String
Get the source URI.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
setDetached
open fun setDetached()
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

Properties

Name Summary
DEFAULT_TILE_SIZE val DEFAULT_TILE_SIZE: Int

DEFAULT_TILE_SIZE

val DEFAULT_TILE_SIZE: Int

getUri

@Nullable()

open fun getUri(): String

Get the source URI.

Return

The uri or null

Source

abstract class Source

Base Peer class for sources. see source.hpp for the other half of the peer.

Constructors

Name Summary
Source open fun Source()

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

Properties

Name Summary
nativePtr private open val nativePtr: Long

Inheritors

Name
CustomGeometrySource
GeoJsonSource
ImageSource
RasterDemSource
RasterSource
UnknownSource
VectorSource

getAttribution

@NonNull()

open fun getAttribution(): String

Retrieve the source attribution.

Will return an empty String if no attribution is available.

Return

the string representation of the attribution in html format

getId

@NonNull()

open fun getId(): String

Retrieve the source id

Return

the source id

getMaxOverscaleFactorForParentTiles

@Nullable()

open fun getMaxOverscaleFactorForParentTiles(): Integer

Retrieve current maximum overscale factor for parent tiles.

Return

current maximum overscale factor or null if not set.

getMinimumTileUpdateInterval

@NonNull()

open fun getMinimumTileUpdateInterval(): Long

Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.

Return

the update interval in milliseconds, default valuse is 0.

getPrefetchZoomDelta

@Nullable()

open fun getPrefetchZoomDelta(): Integer

Retrieve current pre-fetching zoom delta.

Return

current zoom delta or null if not set.

isVolatile

@NonNull()

open fun isVolatile(): Boolean

Retrieve whether or not the fetched tiles for the given source should be stored in the local cache

Return

true if tiles are volatile, false if they will be stored in local cache. Default value is false.

nativePtr

private open val nativePtr: Long

setMaxOverscaleFactorForParentTiles

open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)

When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead. This might introduce unwanted rendering side-effects, especiallyfor raster tiles that are overscaled multiple times. This method sets the maximumlimit for how much a parent tile can be overscaled.

Parameters
Name Summary
maxOverscaleFactor
maximum overscale factor
   
   

setMinimumTileUpdateInterval

open fun setMinimumTileUpdateInterval(interval: Long)

Sets the minimum tile update interval, which is used to throttle the tile update network requests.

Parameters
Name Summary
interval
the update interval in milliseconds.
   
   

setPrefetchZoomDelta

open fun setPrefetchZoomDelta(delta: Integer)

Set the tile pre-fetching zoom delta for current source. Pre-fetching makes sure that a low-resolutiontile at the (current_zoom_level - delta) is rendered as soon as possible at theexpense of a little bandwidth.If delta has not been set or set to null, it will use the value in MapboxMap instance.

Parameters
Name Summary
delta
zoom delta
   
   

setVolatile

open fun setVolatile(value: Boolean)

Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

Parameters
Name Summary
value
current setting for volatile.
   
   

TileSet

open class TileSet

Tile set, allows using TileJson specification as source. Note that encoding is only relevant to raster-dem sources, and is not supported in the TileJson spec.

See also

Name Summary
The tileset specification
The tileset specification
   

Constructors

Name Summary
TileSet open fun TileSet(tilejson: String, tiles: Array)A semver.org style version number.

Functions

Name Summary
toValueObject
@NonNull()
open fun toValueObject(): Map<String, Any>

Properties

Name Summary
attribution private open var attribution: String
bounds private open var bounds: Array
center private open var center: Array
data private open var data: Array
description private open var description: String
encoding private open var encoding: String
grids private open var grids: Array
legend private open var legend: String
maxZoom private open var maxZoom: Float
minZoom private open var minZoom: Float
name private open var name: String
scheme private open var scheme: String
template private open var template: String
tilejson private val tilejson: String
tiles private val tiles: Array
version private open var version: String

attribution

private open var attribution: String

bounds

private open var bounds: Array

center

private open var center: Array

data

private open var data: Array

description

private open var description: String

encoding

private open var encoding: String

grids

private open var grids: Array

legend

private open var legend: String

maxZoom

private open var maxZoom: Float

minZoom

private open var minZoom: Float

name

private open var name: String

scheme

private open var scheme: String

template

private open var template: String

tilejson

private val tilejson: String

tiles

private val tiles: Array

toValueObject

@NonNull()

open fun toValueObject(): Map<String, Any>

version

private open var version: String

UnknownSource

@UiThread()

open class UnknownSource : Source

An unknown type of source

Constructors

Name Summary
UnknownSource open fun UnknownSource(nativePtr: Long)Creates a UnknownSource.

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
setDetached
open fun setDetached()
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

VectorSource

@UiThread()

open class VectorSource : Source

Vector source, allows the use of vector tiles.

See also

Name Summary
the style specification
the style specification
   

Constructors

Name Summary
VectorSource open fun VectorSource(nativePtr: Long)Internal use
VectorSource open fun VectorSource(id: String, uri: Uri)Create a vector source from an URI.
VectorSource open fun VectorSource(id: String, uri: String)Create a vector source from an URI.
VectorSource open fun VectorSource(id: String, tileSet: TileSet)Create a vector source from a tileset

Functions

Name Summary
getAttribution
@NonNull()
open fun getAttribution(): String
Retrieve the source attribution.
getId
@NonNull()
open fun getId(): String
Retrieve the source id
getMaxOverscaleFactorForParentTiles
@Nullable()
open fun getMaxOverscaleFactorForParentTiles(): Integer
Retrieve current maximum overscale factor for parent tiles.
getMinimumTileUpdateInterval
@NonNull()
open fun getMinimumTileUpdateInterval(): Long
Retrieve the minimum tile update interval, which is used to throttle the tile update network requests.
getNativePtr
open fun getNativePtr(): Long
Internal use
getPrefetchZoomDelta
@Nullable()
open fun getPrefetchZoomDelta(): Integer
Retrieve current pre-fetching zoom delta.
getUri
@Nullable()
open fun getUri(): String
Get the source URI.
isVolatile
@NonNull()
open fun isVolatile(): Boolean
Retrieve whether or not the fetched tiles for the given source should be stored in the local cache
querySourceFeatures
@NonNull()
open fun querySourceFeatures(sourceLayerIds: Array, filter: [Expression](../com.mapbox.mapboxsdk.style.expressions/#expression)): List
Queries the source for features.
setDetached
open fun setDetached()
setMaxOverscaleFactorForParentTiles
open fun setMaxOverscaleFactorForParentTiles(maxOverscaleFactor: Integer)
When a set of tiles for a current zoom level is being rendered and some of theideal tiles that cover the screen are not yet loaded, parent tile could beused instead.
setMinimumTileUpdateInterval
open fun setMinimumTileUpdateInterval(interval: Long)
Sets the minimum tile update interval, which is used to throttle the tile update network requests.
setPrefetchZoomDelta
open fun setPrefetchZoomDelta(delta: Integer)
Set the tile pre-fetching zoom delta for current source.
setVolatile
open fun setVolatile(value: Boolean)
Set a flag defining whether or not the fetched tiles for the given source should be stored in the local cache

getUri

@Nullable()

open fun getUri(): String

Get the source URI.

Return

The uri or null

querySourceFeatures

@NonNull()

open fun querySourceFeatures(sourceLayerIds: Array, filter: [Expression](../com.mapbox.mapboxsdk.style.expressions/#expression)): List

Queries the source for features.

Return

the features

Parameters
Name Summary
sourceLayerIds
the source layer identifiers. At least one must be specified.
filter
an optional filter expression to filter the returned Features