> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/ja/llms.txt)

# Get started using the Mapbox Tiling Service and the Tilesets CLI

In this tutorial, you will use the [Mapbox Tiling Service](https://docs.mapbox.com/mapbox-tiling-service/guides/) and [Tilesets CLI](https://github.com/mapbox/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.

At a high level, there are four steps required to create a new tileset using MTS:

1.  [Create a tileset source](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=3)
2.  [Write a recipe](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=4)
3.  [Create a new tileset](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=5)
4.  [Publish your new tileset](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=6)

The Mapbox Tiling Service (MTS) is a tool that allows you to create custom [vector tilesets](https://docs.mapbox.com/help/ja/glossary/tileset/#vector-tilesets) by providing source data with transformation rules called [recipes](https://docs.mapbox.com/help/ja/glossary/tileset-recipe/). Tilesets generated using MTS can be used in any of your map styles and can be composited with any other vector tilesets.

The Tilesets CLI is a Python library that allows you to interact and prepare data for the Mapbox Tiling Service using a command-line interface.

> **Related content (video): [How to create a tileset using Mapbox Tiling Service](null)**
> 
> Learn how to use the Tilesets CLI with Mapbox Tiling Service to create a vector tileset.

> **Note (pricing): Pricing for the Mapbox Tiling Service**
> 
> 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](https://www.mapbox.com/pricing/#data). For other projects, your MTS usage may not be free. See the [Mapbox Tiling Service pricing guide](https://docs.mapbox.com/mapbox-tiling-service/guides/pricing/) for more details on how we charge for this service.

## Prerequisites

There are a few resources you'll need before getting started:

-   **Create a secret Mapbox access token:** Create a [new access token](https://console.mapbox.com/account/access-tokens/create) with the scopes `tilesets:write`, `tilesets:read`, and `tilesets:list`. Do not share this token!
-   **Install the [Tilesets CLI](https://github.com/mapbox/tilesets-cli/):** The Tilesets CLI is a Python tool that provides source data preparation and validation for interacting with MTS.
-   **Python:** Version 3.10 or higher.
-   **Command-line familiarity**: Some familiarity with using the command line.

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

```bash
export MAPBOX_ACCESS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
```

Replace the placeholder `YOUR_SECRET_MAPBOX_ACCESS_TOKEN` with an access token with the correct scopes.

## Create a tileset source

A [tileset source](https://docs.mapbox.com/help/ja/glossary/tileset-source/) is a collection of line-delimited GeoJSON files that is saved to your Mapbox account and can be viewed in the [Data Manager](https://console.mapbox.com/studio/tilesets/). 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.

1.  Download the `populate_places` geojson file.

MTS requires that all files used to create tileset sources be in [line-delimited GeoJSON](https://docs.mapbox.com/mapbox-tiling-service/overview/tileset-sources/#line-delimited-geojson) format. A file formatted as line-delimited GeoJSON contains one or more GeoJSON [Feature objects](https://tools.ietf.org/html/rfc7946#section-3.2) separated by newlines. The Tilesets CLI automatically converts GeoJSON to line-delimited GeoJSON. Download the following file for this tutorial:

[Download line-delimited GeoJSON](https://docs.mapbox.com/help/ja/help/data/populated_places.geojson.ld)

To create a tileset source, you will use the [Tilesets CLI `upload-source` command](https://github.com/mapbox/tilesets-cli/#upload-source):

2.  Run the following command, replacing `username` with your Mapbox account username and `/path/to/data/populated_places.geojson.ld` with the path to the source file.

```bash
$ 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:

```json
{
  "file_size": 18502313,
  "files": 1,
  "id": "mapbox://tileset-source/username/populated-places-source",
  "source_size": 18502313
}
```

More detail on this command and how it interacts with MTS is available in the [Tilesets CLI's documentation](https://github.com/mapbox/tilesets-cli/blob/master/README.md#upload-source).

## 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](https://docs.mapbox.com/help/ja/glossary/tileset-recipe/).

Recipes provide options for generating [vector tiles](https://docs.mapbox.com/help/ja/glossary/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](https://docs.mapbox.com/mapbox-tiling-service/reference/).

To write the recipe, you will need to create a new file:

1.  Open your text editor and paste in the following recipe:

```json
{
  "version": 1,
  "layers": {
    "hello_world": {
      "source": "mapbox://tileset-source/username/populated-places-source",
      "minzoom": 0,
      "maxzoom": 5
    }
  }
}
```

2.  Replace `username` in the `source` field with your Mapbox account username.
    
3.  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](https://docs.mapbox.com/mapbox-tiling-service/reference/#zoom-levels). 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](https://github.com/mapbox/tilesets-cli/#create).

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, replace `username` in following Tilesets CLI command and then run the command:

```bash
$ tilesets create username.hello-world-tiles --recipe hello-world-recipe.json --name "hello world"
```

You should see a successful response message:

```bash
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](https://console.mapbox.com/studio/tilesets/). When you click on the new tileset to open the [Tileset explorer](https://docs.mapbox.com/studio-manual/reference/tilesets/#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](https://github.com/mapbox/tilesets-cli/#publish):

Run the following command, replacing `username` with your Mapbox account username.

```bash
$ 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!

```json
{
  "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](https://github.com/mapbox/tilesets-cli/#status):

```bash
$ 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.

```json
{
  "id": "username.hello-world-tiles",
  "latest_job": "<job_id>",
  "status": "success"
}
```

To find out more information about the processing jobs, including [any processing warnings](https://docs.mapbox.com/mapbox-tiling-service/overview/warnings/), use the [Tilesets CLI `jobs` command](https://github.com/mapbox/tilesets-cli#jobs):

```bash
$ tilesets jobs username.hello-world-tiles
```

Once publishing has completed successfully, you will see the new tileset in your [Tilesets page](https://console.mapbox.com/studio/tilesets/). Click on the new tileset to open the Tileset explorer.

![Screenshot showing Mapbox Studio tilesets page with the newly published tileset](https://docs.mapbox.com/help/ja/assets/ideal-img/tutorials--get-started-mts-and-tilesets-cli--published-tileset.baac901.480.png)

## Next steps

**Congratulations!** Your 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 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 [four](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=3) and [five](https://docs.mapbox.com/help/ja/tutorials/get-started-mts-and-tilesets-cli/?step=4) of this tutorial until you're satisfied with the output tileset.

### What we covered

-   Creating a tileset source
-   Writing a tileset recipe
-   Creating a new tileset
-   Publishing your new 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](https://docs.mapbox.com/help/ja/tutorials/choropleth-studio-gl-pt-1/#add-a-new-layer).
-   **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](https://docs.mapbox.com/mapbox-tiling-service/examples/) page, which has samples of common and complex use cases, plus descriptions for every part of the recipe.
-   **Recipe reference.** The [Recipe reference](https://docs.mapbox.com/mapbox-tiling-service/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](https://docs.mapbox.com/api/maps/#mapbox-tiling-service) has information about all MTS's endpoints and options.
-   **Tilesets CLI documentation.** The [Tilesets CLI](https://github.com/mapbox/tilesets-cli/) has more commands than those discussed in this tutorial. The [documentation](https://github.com/mapbox/tilesets-cli/blob/master/README.md) 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.