Sources

Sources state which data the map should display. Specify the type of source with the "type" property, which must be one of vector, raster, raster-dem, geojson, image, video. Adding a source isn't enough to make data appear on the map because sources don't contain styling details like color or width. Layers refer to a source and give it a visual representation. This makes it possible to style the same source in different ways, like differentiating between types of roads in a highways layer.

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

1
"nb-streets": {
2
"type": "vector",
3
"tiles": [ "http://a.example.com/tiles/{z}/{x}/{y}.pbf",
4
"http://b.example.com/tiles/{z}/{x}/{y}.pbf" ],
5
"maxzoom": 14
6
}

By providing a url to a TileJSON resource

1
"nb-streets": {
2
"type": "vector",
3
"url": "http://api.example.com/tilejson.json"
4
}

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.

1
"wms-imagery": {
2
"type": "raster",
3
"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"
4
],
5
"tileSize": 256
6
}

vector

A vector tile source. 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.

attribution

Optional string.

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

bounds

Optional Array <number>. Default:22

An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: [southwest.lng, southwest.lat, northeast.lng, northeast.lat]. When this property is included in a source, no tiles outside of the given bounds are requested by nb GL.

maxzoom

Optional number. Default: 22

Maximum zoom level for which tiles are available, as in the TileJSON specification. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

minzoom

Optional number. Default: 0

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

scheme

Optional string. Allowed values: xyz, tms Default: xyz

Should belong to one of xyz, tms. Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed. - xyz: Slippy map tilenames scheme. - tms: OSGeo specification scheme.

tiles

Optional Array <number>.

An array of one or more tile source URLs, as in the TileJSON specification.

url

Optional string.

A URL to a TileJSON resource. Supported protocols are http, https.

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 layer

raster

A raster tile source.

1
"nb-satellite": {
2
"type": "raster",
3
"url": "http://api.example.com/satellite.json",
4
"tileSize": 256
5
}

attribution

Optional string.

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

bounds

Optional Array <number>. Default:22

maxzoom

Optional number. Default: 22

Maximum zoom level for which tiles are available, as in the TileJSON specification. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

minzoom

Optional number. Default: 0

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

scheme

Optional string. Allowed values: xyz, tms Default: xyz

Should belong to one of xyz, tms. Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.

xyz: Slippy map tilenames scheme.
tms: OSGeo specification scheme.

tiles

Optional Array <number>.

An array of one or more tile source URLs, as in the TileJSON specification.

url

Optional string.

A URL to a TileJSON resource. Supported protocols are http, https.

tileSize

Optional number. Default: 512

The minimum visual size to display tiles for this layer. Only configurable for raster layers. Please note the units for tileSize is pixel.

raster-dem

A raster DEM source.

1
"terrain-rgb": {
2
"type": "raster-dem",
3
"url": "https://api.example.com/terrain.json"
4
}

attribution

Optional string.

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

bounds

Optional Array <number>. Default:22

maxzoom

Optional number. Default: 22

Maximum zoom level for which tiles are available, as in the TileJSON specification. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

minzoom

Optional number. Default: 0

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

scheme

Optional string. Allowed values: xyz, tms Default: xyz

Should belong to one of xyz, tms. Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.

xyz: Slippy map tilenames scheme.
tms: OSGeo specification scheme.

tiles

Optional Array <number>.

An array of one or more tile source URLs, as in the TileJSON specification.

url

Optional string.

A URL to a TileJSON resource. Supported protocols are http, https.

tileSize

Optional number. Default: 512

The minimum visual size to display tiles for this layer. Only configurable for raster layers. Please note the units for tileSize is pixel.

encoding

Optional enum. Allowed values: mapbox, terrarium. Default: mapbox

Specifies the encoding used by this source.

mapbox: Mapbox Terrain RGB. This is also the default.
terrarium: Terrarium format PNG tiles. See here for more info.

geojson

A GeoJSON source. Data must be provided via a data property, whose value can be a URL or inline GeoJSON.

1
{
2
  "geojson-marker": {
3
    "type": "geojson",
4
    "data": {
5
      "type": "Feature",
6
      "geometry": {
7
        "type": "Point",
8
        "coordinates": [-77.0323, 38.9131]
9
      },
10
      "properties": {
11
        "title": "DC",
12
        "marker-symbol": "monument"
13
      }
14
    }
15
  }
16
}

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.

1
"geojson-lines": {
2
  "type": "geojson",
3
  "data": "./lines.geojson"
4
}

attribution

Optional string.

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

cluster

Optional boolean. Defaults: 'false'

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

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 unique 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. Please note it defaults to one zoom less than maxzoom (so that last zoom features are not clustered).

clusterProperties

Optional object.

An object defining custom properties on the generated clusters if clustering is enabled, aggregating values from clustered points. Has the form

1
{'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.

1
{"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.

1
 {"sum": [["+", ["accumulated"], ["get", "sum"]], ["get", "scalerank"]]}

clusterRadius

Optional number. Default: 128

Radius of each cluster if clustering is enabled. The value must be greater than or equal to 0. A value of 512 indicates a radius equal to the width of a tile.

data

Optional string.

A URL to a GeoJSON file, or inline GeoJSON.

generateId

Optional boolean. Default: false

Determines 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. Default: false

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

maxzoom

Optional number. Default: 18

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

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

1
{
2
  "image": {
3
    "type": "image",
4
    "url": "https://www.example.com/assets/radar.gif",
5
    "coordinates": [
6
      [
7
        -80.425,
8
        46.437
9
      ],
10
      [
11
        -71.516,
12
        46.437
13
      ],
14
      [
15
        -71.516,
16
        37.936
17
      ],
18
      [
19
        -80.425,
20
        37.936
21
      ]
22
    ]
23
  }
24
}

coordinate

Required Array[<<Array <number>>. Default:22

Corners of image specified in longitude, latitude pairs. Please follow the clockwise order - top left, top right, bottom right, bottom left - when specifying the coordinates.

url

Required string.

URL that points to an image.

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.

1
{
2
  "video": {
3
    "type": "video",
4
    "urls": ["https://static-example.com/drone.mp4", "https://static-example.com/drone.webm"],
5
    "coordinates": [
6
      [-122.51596391201019, 37.56238816766053],
7
      [-122.51467645168304, 37.56410183312965],
8
      [-122.51309394836426, 37.563391708549425],
9
      [-122.51423120498657, 37.56161849366671]
10
    ]
11
  }
12
}

coordinate

Required Array <Array <number>>. Default:22

Corners of image specified in longitude, latitude pairs. Please follow the clockwise order - top left, top right, bottom right, bottom left - when specifying the coordinates.

url

Required string.

URLs to video content in order of preferred format.