Recipe basics - creating an unfiltered tileset | Mapbox Tiling Service

Components of a recipe

The simplest tileset recipe you can write includes two required top-level fields: the version of the recipe specification and the layers object. This example recipe will tile your data without any data modifications.

The layers object can contain multiple individual layers, which are themselves objects.

Within each layer object, an individual layer must contain:

name - a layer name
source - tileset source
minzoom - the minimum zoom level at which you want your data to be tiled
maxzoom - the maximum zoom level at which you want your data to be tiled

A recipe can have up to 20 individual layers within the layers object.

Setting zoom extents

The minzoom and maxzoom you choose directly impact the time it takes MTS to finish processing your data because each additional zoom level increases the amount of data in the resulting tileset exponentially. So, it’s important to first consider the use cases your map is trying to solve for when choosing your minzoom and maxzoom so that you don't incur any performance costs unnecessarily.

You can learn about the appropriate zoom levels for your use case in our zoom level confirmation documentation.

Note

maxzoom does not determine which zoom level your maps zoom to. Your map will still zoom past the max zoom in your recipe because of overzooming.

This recipe example below contains one layer in the layers object, named my_new_layer, and has a minzoom of 0 and a maxzoom of 7. Replace {username} with your username and {id} with the tileset source id. You can view the tileset source id using the `tilesets-cli.


{
  "version": 1,
  "layers": {
    "my_new_layer": {
      "source": "mapbox://tileset-source/{username}/{id}",
      "minzoom": 0,
      "maxzoom": 7
    }
  }
}

Generating a tileset of Washington D.C. bakeries and their health inspection score

The above sample recipe can be applied to any dataset to generate a tileset. While this recipe will produce a tileset for any dataset, MTS will drop features from dense datasets to stay within the 1250 Kilobytes per layer size limit.

Below is an example of how to generate a tileset that includes a small subset of D.C. Bakeries and their associated health inspection scores. This data is sourced from the D.C. Food Safety and Hygiene Inspection Services Division.

Using the Tilesets CLI to generate a tileset

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

Create a tileset source named dc-bakeries with the data you downloaded.


tilesets upload-source username dc-bakeries ~/your/local/path/dc-bakeries.ldgeojson

Create your recipe as a local JSON file (for example, basic-recipe.json) with your dc-bakeries tileset source.


{
  "version": 1,
  "layers": {
    "bakeries": {
      "source": "mapbox://tileset-source/{username}/dc-bakeries",
      "minzoom": 0,
      "maxzoom": 7
    }
  }
}

Create a tileset with the id username.dc-bakeries using your recipe and name it "D.C. bakeries"

This will be an empty tileset to start, until you publish it.


tilesets create username.dc-bakeries --recipe ~/your/local/path/basic-recipe.json --name "D.C. Bakeries"

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


tilesets publish username.dc-bakeries

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.dc-bakeries tileset as a vector tile source to a Mapbox GL JS map style:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Recipe basics - creating an unfiltered 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: 11,
    center: [-77.050636, 38.889248]
  });

  map.on('load', () => {
    map.addSource('dc-bakeries', {
      type: 'vector',
      url: 'mapbox://examples.dc-bakeries'
    });
    map.addLayer({
      'id': 'dc-bakeries-id',
      'type': 'circle',
      'source': 'dc-bakeries',
      'source-layer': 'city_labels',
      'paint': {
        'circle-radius': 4,
        'circle-color': '#ff69b4'
      }
    });
  });
</script>

</body>
</html>

Recipe options used

Field	Description	Data type
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`
minzoom	Specify the minimum zoom at which the data in your tileset will be available.	`Integer`
maxzoom	Specify the maximum zoom at which the data your tileset will be tiled. Your map can be viewed past this zoom level because of overzooming, but the data at zoom levels greater than the maxzoom will be less precise.	`Integer`