Bathymetry - multilayer tileset | Mapbox Tiling Service

Tilesets can contain multiple layers. This is especially useful when you have multiple, but related, geographical datasets that will be used together in a style. mapbox-public.bathymetry is a multilayer tileset that includes 3 related layers:

water-depth
undersea-features-points
undersea-features-lines

These are all bathymetric data, but each layer is a distinct kind of information.


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Bathymetry - multilayer tileset</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
	// TO MAKE THE MAP APPEAR YOU MUST
	// ADD YOUR ACCESS TOKEN FROM
	// https://account.mapbox.com
	mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/examples/ckoyugkr906bd17o6jv7732xa',
    zoom: 3,
    center: [122.473, 0.4182]
  });
</script>

</body>
</html>

Why generate a multilayer tileset?

Compared to the process of generating and managing a single tileset for each collection of data, a multilayer tileset keeps related data together, making them simpler to create, update, and manage. For information about when a multilayer tileset is appropriate, see the Multilayer tilesets troubleshooting guide.

A multilayer recipe includes multiple keys in the layers element. Each unique key generates a layer and has the same layer configuration options available in a single layer recipe.

Bathymetry data

You will generate a multilayer tileset using data from Natural Earth and GEBCO.

Natural Earth's Bathymetry dataset will become your water-depth layer.
GEBCO's IHO-IOC GEBCO Gazetteer of Undersea Feature Names will become your undersea-names and undersea-lines layers.

This recipe excerpt shows how to include multiple layer elements to produce a multilayer tileset. Each layer has a unique name and typically has its own data source.


{
  "version": 1,
  "layers": {
    "water-depth": {
      "source": "mapbox://tileset-source/{username}/water-detail",
      // layer configuration
    },
    "undersea-features-points": {
      "source": "mapbox://tileset-source/{username}/undersea-names",
      // layer configuration
    },
    "undersea-features-lines": {
      "source": "mapbox://tileset-source/{username}/undersea-lines",
      // layer configuration
    }
  }
}

The map on the left is a single layer tileset generated without any tiles or features options in its recipe. The map on the right is a multilayer tileset with the recipe configurations outlined below.

Create a bathymetry tileset with the Tilesets CLI

This section describes how to use the Tilesets CLI to generate a tileset.

Download the data you'll use to create the tileset:

arrow-downDownload line-delimited GeoJSON

Extract the data to produce three sample data files.
Using the Tilesets CLI, create a tileset source for each of the data files. Give each source a unique name. Replace {username} with your Mapbox username.


tilesets upload-source {username} undersea-lines ~/your/local/path/undersea-lines.geojson
tilesets upload-source {username} undersea-names ~/your/local/path/undersea-names.ldgeojson
tilesets upload-source {username} water-detail ~/your/local/path/water-detail.ldgeojson

Create your recipe as a local JSON file (such as bathymetry-recipe.json) with your undersea-lines, undersea-names, and water-detail tileset sources.


{
  "version": 1,
  "layers": {
    "undersea-features-lines": {
      "source": "mapbox://tileset-source/{username}/undersea-lines",
      "minzoom": 3,
      "maxzoom": 8,
      "features": {
        "attributes": {
          "allowed_output": ["name", "type", "discoverer", "disc_year"]
        }
      }
    },
    "undersea-features-points": {
      "source": "mapbox://tileset-source/{username}/undersea-names",
      "minzoom": 3,
      "maxzoom": 8,
      "features": {
        "attributes": {
          "allowed_output": ["name", "type", "discoverer", "disc_year"]
        }
      },
      "tiles": { "limit": [["lowest_where_in_distance", true, 10, "name"]] }
    },
    "water-depth": {
      "source": "mapbox://tileset-source/{username}/water-detail",
      "minzoom": 0,
      "maxzoom": 8,
      "features": {
        "attributes": { "allowed_output": ["depth"] },
        "simplification": { "outward_only": true, "distance": 1 }
      },
      "tiles": {
        "order": "depth",
        "union": [
          {
            "group_by": ["depth"],
            "simplification": { "distance": 4, "outward_only": false }
          }
        ]
      }
    }
  }
}

Create a tileset with the ID {username}.bathymetry using your recipe and name it "bathymetry multilayer". This tileset will be empty until you publish it.


tilesets create {username}.bathymetry --recipe ~/your/local/path/bathymetry-recipe.json --name "bathymetry multilayer"

Now you're ready to publish your tileset and start processing your data.


tilesets publish {username}.bathymetry

Preview your tileset

You can now add your new tileset to a map style to visualize its data. Below is an example of how to add the {username}.bathymetry tileset as a vector tile source to a Mapbox GL JS map style. Add each of your tileset's layers to the map as separate style layers that can be styled individually.


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Bathymetry - multilayer tileset</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
	// TO MAKE THE MAP APPEAR YOU MUST
	// ADD YOUR ACCESS TOKEN FROM
	// https://account.mapbox.com
	mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/light-v10',
    zoom: 3,
    center: [-13, -25]
  });

  map.on('load', () => {
    map.addSource('bathymetry', {
      type: 'vector',
      url: 'mapbox://examples.bathymetry'
    });
    map.addLayer({
      'id': 'water-depth',
      'type': 'line',
      'source': 'bathymetry',
      'source-layer': 'water-depth',
      'layout': {
        'line-join': 'round',
        'line-cap': 'round'
      },
      'paint': {
        'line-color': '#69b4ff',
        'line-width': 1
      }
    });
    map.addLayer({
      'id': 'undersea-features-lines',
      'type': 'line',
      'source': 'bathymetry',
      'source-layer': 'undersea-features-lines',
      'layout': {
        'line-join': 'round',
        'line-cap': 'round'
      },
      'paint': {
        'line-color': '#ff69b4',
        'line-width': 2
      }
    });
    map.addLayer({
      'id': 'undersea-features-points',
      'type': 'circle',
      'source': 'bathymetry',
      'source-layer': 'undersea-features-points',
      'paint': {
        'circle-radius': 4,
        'circle-color': '#01fe01'
      }
    });
    map.addLayer({
      'id': 'undersea-features-points-label',
      'type': 'symbol',
      'source': 'bathymetry',
      'source-layer': 'undersea-features-points',
      'layout': {
        'text-field': '{name}',
        'text-anchor': 'top-left',
        'text-size': 12
      }
    });
  });
</script>

</body>
</html>

Recipe options used

Field	Description	Data type
layers	The names of the layers and their configuration options. Each layer has its own configuration.	`String`
source	The source data to use for this layer. Tileset sources are created with the Create a tileset source endpoint of Mapbox Tiling Service (MTS).	`String`

Additional Developer Resources

Mapbox Developer Discord

Developer Cheatsheet

Mapbox Support

Ask AI

Was this example helpful?

Why generate a multilayer tileset?​

Bathymetry data​

Create a bathymetry tileset with the Tilesets CLI​

Preview your tileset​

Recipe options used​

Why generate a multilayer tileset?

Bathymetry data

Create a bathymetry tileset with the Tilesets CLI

Preview your tileset

Recipe options used