Skip to main content

Sources

Additional Developer Resources

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.

Sources and layers work together

Adding a source to a map style isn't enough to make data appear on a Mapbox map. You must also specify a layer to visualize the source data. The layer specifies how to render the data from the source on the map.

Data formats​

Each type of source requires a specific data format and has its own set of properties. The following table summarizes the available source types along with their required data formats and usage:

geojson and vector sources are the most commonly used source types, as they allow for the most flexibility in styling and interaction with Mapbox GL JS and the Maps SDKs.

Source TypeData FormatUsage Summary
geojsonGeoJSON object or fileA text-based format for encoding vector-based geometries (points, lines, or polygons) and their properties. Can be loaded from hard-coded strings or objects in source code or via a URL. Best for small to medium vector datasets. Client-side parsed, editable, and highly readable. Example
vectorMapbox Vector TilesetBinary tile format following the Mapbox Vector Tile spec served as a set of files following a tiling scheme. Each tile contains vector-based geometries (points, lines, or polygons) and their properties. Described with a TileJSON or as one or more tile URL templates. Best for large vector datasets. Example
rasterImage-based Raster TilesetImage tile format using rasterized vector data or imagery, typically in PNG or JPEG format, served as a set of image files following a tiling scheme. Described with a TileJSON or as one or more tile URL templates. Ideal for fast, consistent visual display across platforms, especially for basemaps and static layers. Example
raster-arrayMapbox Raster TilesetBinary tile format for multidimensional raster data, structured as layers with one or more bands per tile. Served as a set of files following the xyz tiling scheme. Partial band access is available via HTTP range requests. Ideal for time-series or multiband datasets such as weather, elevation, or satellite-derived metrics. Described with a TileJSON or as one or more tile URL templates. Example
imageImage URLA georeferenced static image (e.g., PNG or JPEG) projected over a specified bounding box. Requires an image URL and its coordinates. Suitable for scanned map overlays, imagery overlays, etc. Example
videoVideo URLA georeferenced video projected over a specified bounding box. Requires URL to video file and geographic coordinates. Useful for animated overlays but limited browser support. Example
Note

Additional source types may be available depending on the Mapbox renderer in use. For example, a canvas source is available in Mapbox GL JS, which provides an HTML5 canvas element for display on the map.

Tiled sources​

Tiled sources (vector, raster, and raster-array) 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 the bbox 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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.10.0>= 2.0.1>= 2.0.0

attribution​

Optional string .

Contains an attribution to be displayed when the map is shown to a user.

bounds​

Optional array of numbers . Defaults to [-180,-85.051129,180,85.051129].

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.

extra_bounds​

Optional array of array of numbers .

An array of additional discrete geographic regions where tiles are available. When used alongside the bounds property, these regions act as an additional filter - Mapbox GL will only request tiles that are both within the bounds and any of the regions defined in extra_bounds. When used independently (without bounds), Mapbox GL will request tiles that fall within any of the regions in extra_bounds. This allows for more fine-grained control over tile requests, particularly when dealing with sparse data coverage.

maxzoom​

Optional number . Defaults to 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​

Optional number . Defaults to 0.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

promoteId​

Optional 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​

Optional enum . One of "xyz", "tms". Defaults to "xyz".

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​

Optional array of strings .

An array of one or more tile source URLs, as in the TileJSON spec. Required if url is not provided.

url​

Optional string .

A URL to a TileJSON resource. Supported protocols are http:, https:, and mapbox://<Tileset ID>. Required if tiles is not provided.

volatile​

Optional boolean . Defaults to false.

A setting to determine whether a source's tiles are cached locally.

SDK SupportMapbox GL JSAndroid SDKiOS 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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.10.0>= 2.0.1>= 2.0.0

attribution​

Optional string .

Contains an attribution to be displayed when the map is shown to a user.

bounds​

Optional array of numbers . Defaults to [-180,-85.051129,180,85.051129].

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.

extra_bounds​

Optional array of array of numbers .

An array of additional discrete geographic regions where tiles are available. When used alongside the bounds property, these regions act as an additional filter - Mapbox GL will only request tiles that are both within the bounds and any of the regions defined in extra_bounds. When used independently (without bounds), Mapbox GL will request tiles that fall within any of the regions in extra_bounds. This allows for more fine-grained control over tile requests, particularly when dealing with sparse data coverage.

maxzoom​

Optional number . Defaults to 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​

Optional number . Defaults to 0.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

scheme​

Optional enum . One of "xyz", "tms". Defaults to "xyz".

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​

Optional array of strings .

An array of one or more tile source URLs, as in the TileJSON spec. Required if url is not provided.

tileSize​

Optional number . Units in pixels. Defaults to 512.

The minimum visual size to display tiles for this layer. Only configurable for raster layers.

url​

Optional string .

A URL to a TileJSON resource. Supported protocols are http:, https:, and mapbox://<Tileset ID>. Required if tiles is not provided.

volatile​

Optional boolean . Defaults to false.

A setting to determine whether a source's tiles are cached locally.

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

Not yet supported>= 9.3.0>= 5.10.0

raster-array​

EXPERIMENTAL

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​

Optional string .

Contains an attribution to be displayed when the map is shown to a user.

bounds​

Optional array of numbers . Defaults to [-180,-85.051129,180,85.051129].

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.

extra_bounds​

Optional array of array of numbers .

An array of additional discrete geographic regions where tiles are available. When used alongside the bounds property, these regions act as an additional filter - Mapbox GL will only request tiles that are both within the bounds and any of the regions defined in extra_bounds. When used independently (without bounds), Mapbox GL will request tiles that fall within any of the regions in extra_bounds. This allows for more fine-grained control over tile requests, particularly when dealing with sparse data coverage.

maxzoom​

Optional number . Defaults to 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​

Optional number . Defaults to 0.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

rasterLayers​

Optional .

Contains the description of the raster data layers and the bands contained within the tiles.

tiles​

Optional array of strings .

An array of one or more tile source URLs, as in the TileJSON spec. Required if url is not provided.

tileSize​

Optional number . Units in pixels. Defaults to 512.

The minimum visual size to display tiles for this layer. Only configurable for raster layers.

url​

Optional string .

A URL to a TileJSON resource. Supported protocols are http:, https:, and mapbox://<Tileset ID>. Required if tiles is not provided.

volatile​

Optional boolean . Defaults to false.

A setting to determine whether a source's tiles are cached locally.

SDK SupportMapbox GL JSAndroid SDKiOS 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 SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.43.0Not yet supportedNot yet supported

attribution​

Optional string .

Contains an attribution to be displayed when the map is shown to a user.

bounds​

Optional array of numbers . Defaults to [-180,-85.051129,180,85.051129].

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​

Optional enum . One of "terrarium", "mapbox". Defaults to "mapbox".

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.

extra_bounds​

Optional array of array of numbers .

An array of additional discrete geographic regions where tiles are available. When used alongside the bounds property, these regions act as an additional filter - Mapbox GL will only request tiles that are both within the bounds and any of the regions defined in extra_bounds. When used independently (without bounds), Mapbox GL will request tiles that fall within any of the regions in extra_bounds. This allows for more fine-grained control over tile requests, particularly when dealing with sparse data coverage.

maxzoom​

Optional number . Defaults to 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​

Optional number . Defaults to 0.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

tiles​

Optional array of strings .

An array of one or more tile source URLs, as in the TileJSON spec. Required if url is not provided.

tileSize​

Optional number . Units in pixels. Defaults to 512.

The minimum visual size to display tiles for this layer. Only configurable for raster layers.

url​

Optional string .

A URL to a TileJSON resource. Supported protocols are http:, https:, and mapbox://<Tileset ID>. Required if tiles is not provided.

volatile​

Optional boolean . Defaults to false.

A setting to determine whether a source's tiles are cached locally.

SDK SupportMapbox GL JSAndroid SDKiOS 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 SupportMapbox GL JSAndroid SDKiOS 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​

Optional string .

Contains an attribution to be displayed when the map is shown to a user.

buffer​

Optional number between 0 and 512 inclusive. Defaults to 128.

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​

Optional boolean . Defaults to 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 Is true if the point is a cluster
  • cluster_id A unqiue id for the cluster to be used in conjunction with the cluster inspection methods
  • point_count Number of original points grouped into this cluster
  • point_count_abbreviated An abbreviated point count

clusterMaxZoom​

Optional number .

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​

Optional number .

Minimum number of points necessary to form a cluster if clustering is enabled. Defaults to 2.

clusterProperties​

Optional .

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​

Optional number greater than or equal to 0. Defaults to 50.

Radius of each cluster if clustering is enabled. A value of 512 indicates a radius equal to the width of a tile.

data​

Optional .

A URL to a GeoJSON file, or inline GeoJSON.

dynamic​

Optional boolean . Defaults to false.

Whether to optimize this source for frequent data updates (e.g. animating features).

SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 3.4.0Not yet supportedNot yet supported

filter​

Optional .

An expression for filtering features prior to processing them for rendering.

generateId​

Optional boolean . Defaults to 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​

Optional boolean . Defaults to false.

Whether to calculate line distance metrics. This is required for line layers that specify line-gradient values.

maxzoom​

Optional number . Defaults to 18.

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

minzoom​

Optional number . Defaults to 0.

Minimum zoom level at which to create vector tiles

promoteId​

Optional promoteId .

A property to use as a feature id (for feature state). Either a property name, or an object of the form {<sourceLayer>: <propertyName>}.

tolerance​

Optional number . Defaults to 0.375.

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

image​

An image source. The "url" value contains the image location.

The "coordinates" array contains [longitude, latitude] pairs for the image corners listed in clockwise order: top left, top right, bottom right, bottom left.

"image": {
    "type": "image",
    "url": "https://docs.mapbox.com/mapbox-gl-js/assets/radar.gif",
    "coordinates": [
        [-80.425, 46.437],
        [-71.516, 46.437],
        [-71.516, 37.936],
        [-80.425, 37.936]
    ]
}
SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.10.0>= 5.2.0>= 3.7.0

coordinates​

Required array of array of numbers .

Corners of image specified in longitude, latitude pairs. Note: When using globe projection, the image will be centered at the North or South Pole in the respective hemisphere if the average latitude value exceeds 85 degrees or falls below -85 degrees.

url​

Optional string .

URL that points to an image. If the URL is not specified, the image is expected to be loaded directly during runtime.

video​

A video source. The "urls" value is an array. For each URL in the array, a video element source will be created. To support the video across browsers, supply URLs in multiple formats.

The "coordinates" array contains [longitude, latitude] pairs for the video corners listed in clockwise order: top left, top right, bottom right, bottom left.

"video": {
    "type": "video",
    "urls": [
        "https://static-assets.mapbox.com/mapbox-gl-js/drone.mp4",
        "https://static-assets.mapbox.com/mapbox-gl-js/drone.webm"
    ],
    "coordinates": [
        [-122.51596391201019, 37.56238816766053],
        [-122.51467645168304, 37.56410183312965],
        [-122.51309394836426, 37.563391708549425],
        [-122.51423120498657, 37.56161849366671]
    ]
}
SDK SupportMapbox GL JSAndroid SDKiOS SDK

basic functionality

>= 0.10.0Not yet supportedNot yet supported

coordinates​

Required array of array of numbers .

Corners of video specified in longitude, latitude pairs.

urls​

Required array of strings .

URLs to video content in order of preferred format.

Additional Developer Resources
Was this page helpful?