Source Types

This page documents the different types of data sources supported by Mapbox GL JS. Data sources are a core component of the Mapbox GL JS style specification and define where the geographic data used to render the map comes from. For information on how these sources are processed and managed within the tile system, see Tile System.

Introduction to Source Types

Sources are defined in the sources property of a Mapbox GL JS style and provide the data that layers use for rendering. Each source has a type property that determines how the data is interpreted and processed.

100%

Source Types Overview

Mapbox GL JS supports several types of sources, each serving a specific purpose and data format:

100%

Vector Source

Vector sources provide vector tile data that contains pre-rendered geometry encoded in a compact, structured format.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "vector"
url	string		URL to a TileJSON resource. Supported protocols are http:, https:, and mapbox://<Tileset ID>. Required if tiles is not provided.
tiles	string[]		Array of tile source URLs. Required if url is not provided.
bounds	number[4]	[-180, -85.051129, 180, 85.051129]	The southwest and northeast corners of the source's bounding box.
scheme	string	"xyz"	Influences the y direction of the tile coordinates. Can be "xyz" or "tms".
minzoom	number	0	Minimum zoom level for which tiles are available.
maxzoom	number	22	Maximum zoom level for which tiles are available.
attribution	string		Attribution to be displayed when the map is shown.
promoteId	string/object		Property to use as feature id for feature state.
volatile	boolean	false	Whether source's tiles are cached locally.

Example

"mapbox-streets": {
  "type": "vector",
  "url": "mapbox://mapbox.mapbox-streets-v8"
}

Raster Source

Raster sources provide raster tiles that contain pixel data like satellite imagery, historical maps, or other image-based visualizations.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "raster"
url	string		URL to a TileJSON resource.
tiles	string[]		Array of tile source URLs.
bounds	number[4]	[-180, -85.051129, 180, 85.051129]	The source's bounding box.
minzoom	number	0	Minimum zoom level for tiles.
maxzoom	number	22	Maximum zoom level for tiles.
tileSize	number	512	The minimum visual size to display tiles for this layer.
scheme	string	"xyz"	The tile coordinate scheme.
attribution	string		Attribution text.
volatile	boolean	false	Whether source's tiles are cached locally.

Example

"satellite": {
  "type": "raster",
  "url": "mapbox://mapbox.satellite",
  "tileSize": 256
}

Raster DEM Source

Raster DEM (Digital Elevation Model) sources provide terrain elevation data used for 3D terrain rendering.

Properties

Same as Raster Source, plus:

Property	Type	Default	Description
encoding	string	"mapbox"	The encoding of the DEM data. Can be "mapbox" or "terrarium".

Example

"terrain-source": {
  "type": "raster-dem",
  "url": "mapbox://mapbox.mapbox-terrain-dem-v1",
  "tileSize": 512,
  "maxzoom": 14
}

GeoJSON Source

GeoJSON sources provide vector data in GeoJSON format, which can be loaded from a URL or included inline in the style.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "geojson"
data	object/string		GeoJSON data or URL to a GeoJSON file.
maxzoom	number	18	Maximum zoom level to preserve detail at.
attribution	string		Attribution text.
buffer	number	128	Size of the tile buffer on each side.
tolerance	number	0.375	Douglas-Peucker simplification tolerance.
cluster	boolean	false	Whether to cluster point features.
clusterRadius	number	50	Radius of each cluster when clustering points.
clusterMaxZoom	number	One zoom less than maxzoom	Maximum zoom level at which to cluster points.
lineMetrics	boolean	false	Whether to calculate line distance metrics.
generateId	boolean	false	Whether to generate ids for the features.

Example

"earthquake-data": {
  "type": "geojson",
  "data": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson"
}

Video Source

Video sources allow you to add a video as a dynamic texture to be displayed on the map.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "video"
urls	string[]	(required)	URLs to video files.
coordinates	number[][]	(required)	Coordinates defining the four corners of the video.

Example

"drone-footage": {
  "type": "video",
  "urls": [
    "https://example.com/video.mp4",
    "https://example.com/video.webm"
  ],
  "coordinates": [
    [-122.51, 37.77],
    [-122.48, 37.77],
    [-122.48, 37.75],
    [-122.51, 37.75]
  ]
}

Image Source

Image sources allow you to add a single image as a texture to be displayed on the map, useful for overlaying historical maps or other georeferenced images.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "image"
url	string	(required)	URL to an image.
coordinates	number[][]	(required)	Coordinates defining the four corners of the image.

Example

"radar": {
  "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]
  ]
}

Model Source

Model sources provide 3D model data for rendering on the map.

Properties

Property	Type	Default	Description
type	string	(required)	Must be "model" or "batched-model"
maxzoom	number		Maximum zoom level for tiles.
minzoom	number		Minimum zoom level for tiles.
tiles	string[]		Array of tile source URLs.

Example

"buildings-3d": {
  "type": "model",
  "tiles": ["https://example.com/model/{z}/{x}/{y}.glb"],
  "minzoom": 14,
  "maxzoom": 16
}

Using Sources in the Style Specification

The diagram below illustrates how sources are used within the Mapbox GL style specification and relate to other components like layers:

100%

Source Usage with Layers

Different source types work with different layer types. This table shows the compatibility between source types and layer types:

Source Type	Compatible Layer Types
Vector	Fill, Line, Symbol, Circle, FillExtrusion, Heatmap
Raster	Raster
Raster DEM	Hillshade
GeoJSON	Fill, Line, Symbol, Circle, FillExtrusion, Heatmap
Image	Raster
Video	Raster
Model	Custom

A layer references a source through its source property, and for vector sources, can additionally specify a source-layer to target specific data within the source.

Example

{
  "sources": {
    "mapbox-streets": {
      "type": "vector",
      "url": "mapbox://mapbox.mapbox-streets-v8"
    }
  },
  "layers": [
    {
      "id": "water",
      "type": "fill",
      "source": "mapbox-streets",
      "source-layer": "water",
      "paint": {
        "fill-color": "#00ffff"
      }
    }
  ]
}