Recipe basics - creating an unfiltered tileset
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 namesource
- tileset sourceminzoom
- the minimum zoom level at which you want your data to be tiledmaxzoom
- 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.
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:
- 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 yourdc-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 |
To learn more about zoom levels and how to configure them properly for your data, read our zoom level confirmation documentation.