Sources
A map or layer source states which data the map should display. Specify the type of source with the "type"
property, which must be one of vector, raster, raster-array, raster-dem, geojson, image, video.
A source provides map data that Mapbox GL JS can use with a style document to render a visual representation of that data. This delegation makes it possible to style the same source in different ways, as you might do to differentiate the appearances of different types of roads in a highways layer.
Adding a source to a map or layer isn't enough to make data appear on the map. You must also specify a style to provide properties like color or width for each feature.
Tiled sources
Tiled sources (vector and raster) must specify their details according to the TileJSON specification. There are several ways to do so:
- By supplying TileJSON properties such as
"tiles"
,"minzoom"
, and"maxzoom"
directly in the source:
"mapbox-streets": {
"type": "vector",
"tiles": [
"http://a.example.com/tiles/{z}/{x}/{y}.pbf",
"http://b.example.com/tiles/{z}/{x}/{y}.pbf"
],
"maxzoom": 14
}
- By providing a
"url"
to a TileJSON resource:
"mapbox-streets": {
"type": "vector",
"url": "http://api.example.com/tilejson.json"
}
- By providing a URL to a WMS server that supports EPSG:3857 (or EPSG:900913) as a source of tiled data. The server URL should contain a
"{bbox-epsg-3857}"
replacement token to supply thebbox
parameter.
"wms-imagery": {
"type": "raster",
"tiles": [
"http://a.example.com/wms?bbox={bbox-epsg-3857}&format=image/png&service=WMS&version=1.1.1&request=GetMap&srs=EPSG:3857&width=256&height=256&layers=example"
],
"tileSize": 256
}
vector
A vector tile source. Tiles must be in Mapbox Vector Tile format. All geometric coordinates in vector tiles must be between -1 * extent
and (extent * 2) - 1
inclusive. All layers that use a vector source must specify a "source-layer"
value. For vector tiles hosted by Mapbox, the "url"
value should be of the form mapbox://tilesetid
.
"mapbox-streets": {
"type": "vector",
"url": "mapbox://mapbox.mapbox-streets-v6"
}
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 |
attribution
Contains an attribution to be displayed when the map is shown to a user.
bounds
An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: [sw.lng, sw.lat, ne.lng, ne.lat]
. When this property is included in a source, no tiles outside of the given bounds are requested by Mapbox GL.
maxzoom
22
. Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.
minzoom
0
. Minimum zoom level for which tiles are available, as in the TileJSON spec.
promoteId
A property to use as a feature id (for feature state). Either a property name, or an object of the form {<sourceLayer>: <propertyName>}
. If specified as a string for a vector tile source, the same property is used across all its source layers. If specified as an object only specified source layers will have id overriden, others will fallback to original feature id
scheme
Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.
"xyz"
:Slippy map tilenames scheme.
"tms"
:OSGeo spec scheme.
tiles
An array of one or more tile source URLs, as in the TileJSON spec. Required if url
is not provided.
url
A URL to a TileJSON resource. Supported protocols are http:
, https:
, and mapbox://<Tileset ID>
. Required if tiles
is not provided.
volatile
false
. A setting to determine whether a source's tiles are cached locally.
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | Not yet supported | >= 9.3.0 | >= 5.10.0 |
raster
A raster tile source. For raster tiles hosted by Mapbox, the "url"
value should be of the form mapbox://tilesetid
.
"mapbox-satellite": {
"type": "raster",
"url": "mapbox://mapbox.satellite",
"tileSize": 256
}
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 |
attribution
Contains an attribution to be displayed when the map is shown to a user.
bounds
An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: [sw.lng, sw.lat, ne.lng, ne.lat]
. When this property is included in a source, no tiles outside of the given bounds are requested by Mapbox GL.
maxzoom
22
. Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.
minzoom
0
. Minimum zoom level for which tiles are available, as in the TileJSON spec.
scheme
Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.
"xyz"
:Slippy map tilenames scheme.
"tms"
:OSGeo spec scheme.
tiles
An array of one or more tile source URLs, as in the TileJSON spec. Required if url
is not provided.
tileSize
512
. The minimum visual size to display tiles for this layer. Only configurable for raster layers.
url
A URL to a TileJSON resource. Supported protocols are http:
, https:
, and mapbox://<Tileset ID>
. Required if tiles
is not provided.
volatile
false
. A setting to determine whether a source's tiles are cached locally.
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | Not yet supported | >= 9.3.0 | >= 5.10.0 |
raster-array
A raster-array tile source. Use this source with Mapbox Tiling Service (MTS) tilesets.
"gfs-wind": {
"type": "raster-array",
"url": "mapbox://mapbox.gfs-winds",
"tileSize": 512
}
attribution
Contains an attribution to be displayed when the map is shown to a user.
bounds
An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: [sw.lng, sw.lat, ne.lng, ne.lat]
. When this property is included in a source, no tiles outside of the given bounds are requested by Mapbox GL.
experimental
maxzoom
22
. Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.
minzoom
0
. Minimum zoom level for which tiles are available, as in the TileJSON spec.
rasterLayers
Contains the description of the raster data layers and the bands contained within the tiles.
tiles
An array of one or more tile source URLs, as in the TileJSON spec. Required if url
is not provided.
tileSize
512
. The minimum visual size to display tiles for this layer. Only configurable for raster layers.
url
A URL to a TileJSON resource. Supported protocols are http:
, https:
, and mapbox://<Tileset ID>
. Required if tiles
is not provided.
volatile
false
. A setting to determine whether a source's tiles are cached locally.
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | Not yet supported | >= 9.3.0 | >= 5.10.0 |
raster-dem
A raster DEM source. Only supports Mapbox Terrain-DEM (mapbox://mapbox.mapbox-terrain-dem-v1
):
"mapbox-terrain-dem-v1": {
"type": "raster-dem",
"url": "mapbox://mapbox.mapbox-terrain-dem-v1"
}
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | >= 0.43.0 | Not yet supported | Not yet supported |
attribution
Contains an attribution to be displayed when the map is shown to a user.
bounds
An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: [sw.lng, sw.lat, ne.lng, ne.lat]
. When this property is included in a source, no tiles outside of the given bounds are requested by Mapbox GL.
encoding
The encoding used by this source. Mapbox Terrain RGB is used by default
"terrarium"
:Terrarium format PNG tiles. See https://aws.amazon.com/es/public-datasets/terrain/ for more info.
"mapbox"
:Mapbox Terrain RGB tiles. See https://www.mapbox.com/help/access-elevation-data/#mapbox-terrain-rgb for more info.
maxzoom
22
. Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.
minzoom
0
. Minimum zoom level for which tiles are available, as in the TileJSON spec.
tiles
An array of one or more tile source URLs, as in the TileJSON spec. Required if url
is not provided.
tileSize
512
. The minimum visual size to display tiles for this layer. Only configurable for raster layers.
url
A URL to a TileJSON resource. Supported protocols are http:
, https:
, and mapbox://<Tileset ID>
. Required if tiles
is not provided.
volatile
false
. A setting to determine whether a source's tiles are cached locally.
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | Not yet supported | >= 9.3.0 | >= 5.10.0 |
geojson
A GeoJSON source. Data must be provided via a "data"
property, whose value can be a URL or inline GeoJSON.
"geojson-marker": {
"type": "geojson",
"data": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-77.0323, 38.9131]
},
"properties": {
"title": "Mapbox DC",
"marker-symbol": "monument"
}
}
}
This example of a GeoJSON source refers to an external GeoJSON document via its URL. The GeoJSON document must be on the same domain or accessible using CORS.
"geojson-lines": {
"type": "geojson",
"data": "./lines.geojson"
}
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 |
clustering | >= 0.14.0 | >= 4.2.0 | >= 3.4.0 |
line distance metrics | >= 0.45.0 | >= 6.5.0 | >= 4.4.0 |
attribution
Contains an attribution to be displayed when the map is shown to a user.
buffer
Size of the tile buffer on each side. A value of 0 produces no buffer. A value of 512 produces a buffer as wide as the tile itself. Larger values produce fewer rendering artifacts near tile edges and slower performance.
cluster
false
. If the data is a collection of point features, setting this to true clusters the points by radius into groups. Cluster groups become new Point
features in the source with additional properties:
cluster
Istrue
if the point is a clustercluster_id
A unqiue id for the cluster to be used in conjunction with the cluster inspection methodspoint_count
Number of original points grouped into this clusterpoint_count_abbreviated
An abbreviated point count
clusterMaxZoom
Max zoom on which to cluster points if clustering is enabled. Defaults to one zoom less than maxzoom (so that last zoom features are not clustered). Clusters are re-evaluated at integer zoom levels so setting clusterMaxZoom to 14 means the clusters will be displayed until z15.
clusterMinPoints
Minimum number of points necessary to form a cluster if clustering is enabled. Defaults to 2
.
clusterProperties
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]}
. operator
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; map_expression
produces the value of a single point.
Example: {"sum": ["+", ["get", "scalerank"]]}
.
For more advanced use cases, in place of operator
, you can use a custom reduce expression that references a special ["accumulated"]
value, e.g.:
{"sum": [["+", ["accumulated"], ["get", "sum"]], ["get", "scalerank"]]}
clusterRadius
Radius of each cluster if clustering is enabled. A value of 512 indicates a radius equal to the width of a tile.
data
A URL to a GeoJSON file, or inline GeoJSON.
dynamic
false
. Whether to optimize this source for frequent data updates (e.g. animating features).
SDK Support | Mapbox GL JS | Android SDK | iOS SDK |
---|---|---|---|
basic functionality | >= 3.4.0 | Not yet supported | Not yet supported |
filter
An expression for filtering features prior to processing them for rendering.
generateId
false
. Whether to generate ids for the GeoJSON features. When enabled, the feature.id
property will be auto assigned based on its index in the features
array, over-writing any previous values.
lineMetrics
false
. Whether to calculate line distance metrics. This is required for line layers that specify line-gradient
values.
maxzoom
18
. Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).
minzoom
0
. Minimum zoom level at which to create vector tiles