Get started using the Mapbox Tiling Service and the Tilesets CLI
Mapbox Tiling Service (MTS) allows you to create custom vector tilesets by providing source data with transformation rules called recipes. Tilesets generated using MTS can be used in any of your map styles and can be composited with any other vector tilesets.
At a high level, there are four steps required to create a new tileset using MTS:
These steps can all be accomplished using the Tilesets CLI. In this tutorial, you will use the Tilesets CLI to create a tileset source using sample data, then write a recipe that specifies how to transform that data. Then you will create a new tileset with that recipe and publish it. After it is published, you can use this tileset in a custom map style.
This tutorial uses the Mapbox Tiling Service to process geospatial data into vector tiles and make those tiles available to use. The processing and hosting costs for the data in this tutorial fall within MTS's free tier. For other projects, your MTS usage may not be free. See the Mapbox Tiling Service pricing guide for more details on how we charge for this service.
Getting started
There are a few resources you'll need before getting started:
- Create a Mapbox access token. Create a new access token that has the scopes
tilesets:write,tilesets:read, andtilesets:list. Do not share this token! - Install the Tilesets CLI. The Tilesets CLI is a Python tool that provides source data preparation and validation for interacting with MTS.
- Download sample data. This is a single line-delimited GeoJSON file.
Set your access token as an environment variable
To use Mapbox Tiling Service endpoints via the Tilesets CLI, you need to have a Mapbox access token with the correct scopes: tilesets:write, tilesets:read, and tilesets:list. You can pass your access token to each of the commands used in this tutorial using the --token flag. To save time and keep your secret token secure, we recommend storing your Mapbox access token as an environment variable. Set the environment variable with the export command:
export MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN
Replace the placeholder YOUR_MAPBOX_ACCESS_TOKEN with an access token with the correct scopes.
Create a tileset source
A tileset source is a collection of line-delimited GeoJSON files that is saved on Mapbox.com. A tileset source is referenced by an ID, like mapbox://tileset-source/username/hello-world. You can think of a tileset source as a place to store your raw geographic data before turning it into a vector tileset that can be served from MTS. Tileset sources can contain multiple files. You will use a tileset source to create a new tileset "layer" later on in this tutorial.
MTS requires that all files used to create tileset sources be in line-delimited GeoJSON format. A file formatted as line-delimited GeoJSON contains one or more GeoJSON Feature objects separated by newlines. The Tilesets CLI automatically converts GeoJSON to line-delimited GeoJSON.
To create a tileset source, you will use the Tilesets CLI upload-source command. In this command, you will provide the following information:
- Your Mapbox username
- A name for the new tileset source ("populated-places-source" in the example command below)
- The path to the source file or files
More detail on this command and how it interacts with MTS is available in the Tilesets CLI's documentation.
Run the following Tilesets CLI command, replacing username with your Mapbox account username.
$tilesets upload-source username populated-places-source /path/to/data/populated_places.geojson.ld
This command creates a connection with MTS and uploads your source to a permanent and secure location on Mapbox’s servers.
You will see a message that tells you that the tileset source has been successfully created:
{
"file_size": 18502313,
"files": 1,
"id": "mapbox://tileset-source/username/populated-places-source",
"source_size": 18502313
}
Write a recipe
Now that your tileset source has been created, you must provide a set of rules to tell MTS how this source's data should be transformed when you upload and publish it. These rules are referred to as recipes.
Recipes provide options for generating vector tiles such as degree of simplification, zoom level extent, geometry unioning, attribute manipulation, and much more. You can find more detail about all the available configuration options in the Recipe reference.
Open your text editor and paste in the following recipe:
{
"version": 1,
"layers": {
"hello_world": {
"source": "mapbox://tileset-source/username/populated-places-source",
"minzoom": 0,
"maxzoom": 5
}
}
}
Replace username in the source field with your Mapbox account username. Save the recipe to your computer as a file named hello-world-recipe.json.
With this recipe, you are specifying the vector tile layer name and the zoom range you want to use when the tiles are generated. This range, 0-5, is an acceptable standard default for global or country-level data. If your data requires other zoom levels, take a look at the zoom level table in the Recipe reference. You are also using source to specify that the recipe will use the tileset source that you created in the last step.
This isn’t your only chance to write your recipe. You can change it whenever you want.
Create a new tileset
Now you will create a new tileset using your recipe using the Tilesets CLI create command.
You will give your new tileset a tileset ID. This will be the main resource you reference when adding the tileset to your map styles in the future. The tileset ID is a combination of your Mapbox username plus an identifier that is 32 characters or less. The identifier cannot include spaces, but it can include - and _ special characters. In the example below, the tileset ID is username.hello-world-tiles. When you run the command, replace username with your Mapbox account username.
Use the --recipe flag to reference the recipe you created in the last step. This gives MTS a set of rules to follow as it generates the tileset.
Use the --name flag to create a human-readable name for your tileset. The name is limited to 64 characters. If you do not provide a name, one will be randomly generated.
To create the tileset, run the following Tilesets CLI command:
$tilesets create username.hello-world-tiles --recipe hello-world-recipe.json --name "hello world"
You should see a successful response message:
message: 'Successfully created empty tileset username.hello-world-tiles. Publish your tileset to begin processing your data into vector tiles.'
If you are signed into Mapbox Studio, you will see this new tileset on your Tilesets page. When you click on the new tileset to open the Tileset explorer, it will appear to be empty since it has not been published.
Now that you have successfully created a tileset, you can publish it!
Publish your new tileset
Publishing your tileset is an active step that tells MTS to take the following steps:
- Read your tileset’s recipe.
- Retrieve the tileset source data you created.
- Create vector tiles from the data in the tileset source by applying the transformation rules outlined in the recipe.
To publish your tileset, you will use the Tilesets CLI publish command. Run the following command, replacing username with your Mapbox account username.
$tilesets publish username.hello-world-tiles
You’ll see a success message, which means that your publish request has been queued and MTS has begun generating your tileset!
{
"jobId": "<job_id>",
"message": "Processing username.hello-world-tiles."
}
The time it takes to generate your final tileset is determined by the size of your source data and the complexity of your recipe. For example, if you've specified a larger range of zoom levels, this will generate more vector tiles.
You can check the status of your tileset at any time with the Tilesets CLI status command:
$tilesets status username.hello-world-tiles
This shortcut shows the status of the latest job, which can be queued, processing, failed, or success. Your job should only take a few minutes to show "status": success once processing finishes.
{
"id": "username.hello-world-tiles",
"latest_job": "<job_id>",
"status": "success"
}
To find out more information about the processing jobs, including any processing warnings, use the Tilesets CLI jobs command:
$tilesets jobs username.hello-world-tiles
Once publishing has completed successfully, you will see the new tileset in your Tilesets page. Click on the new tileset to open the Tileset explorer.
This tileset is now ready to be used in your custom map styles!
Need to make changes to your source data or your recipe? You can repeat the process above as many times as you like. For instance, to increase the zoom level to 10 and include an additional line-delimited GeoJSON file, you can repeat steps three and four of this tutorial until you're satisfied with the output tileset.
Additional resources
- Add a tileset to a style. Not sure how to add your new tileset to your style? You can find detailed steps for this in our Make a choropleth map tutorial.
- Recipe examples. Recipes are the primary way to manipulate the look of your tileset. If you aren’t sure what recipe to use, we recommend reading through the Recipe examples page, which has samples of common and complex use cases, plus descriptions for every part of the recipe.
- Recipe reference. The Recipe reference documents all the available options for creating recipes and includes mini examples.
- MTS API documentation. The Mapbox Tilesets CLI is a tool for accessing MTS. The MTS API documentation has information about all MTS's endpoints and options.
- Tilesets CLI documentation. The Tilesets CLI has more commands than those discussed in this tutorial. The documentation in the GitHub repository outlines all the available commands, such as viewing or updating a recipe, validating source data, or converting data into line-delimited GeoJSON.