Mapbox Tilesets API CLI

Operate the tilesets API to upload and generate tilesets for your Mapbox maps.

The tilesets API works with two basic entities: the tileset-source and the tileset. To generate a tile layer for a map, you need to upload one or more files to a tileset-source and then create a "recipe" that specifies which sources at which zoom levels should appear in a generated tileset.

Setup

Mapbox requires an access token with permissions to create, list, delete, etc. the entities that comprise a tileset. Create an account and create an access token with the needed permissions. Pass the username and token to this tool by creating a .env file with these two values:

MAPBOX_USERNAME=abc
MAPBOX_TOKEN=xyz

Alternatively, send the username as a CLI param -u <username> and the token as -t <access_token>.

Check your geometry file

mapbox-tileset source validate <geometry-file>

This checks that

• each line of the file is valid JSON
• each point is an array of two numbers
• the first coordinate of each polygon is the same as the last
• points are not repeated within a polygon

Create a tileset-source

mapbox-tileset source create <source-id> <geometry-file>

Add data to a tileset-source

mapbox-tileset source create <source-id> <geometry-file-2>

To generate a tileset from a tileset-source, use a recipe to specify which sources will be available at which zoom levels. The recipe for the tileset takes this form:

{
  "name": "My Tileset's Name",
  "recipe": {
    "version": 1,
    "layers": {
      "layer_id": {
        "source": "mapbox://tileset-source/my-username/my-tileset-source",
        "minzoom": 5,
        "maxzoom": 8
      }
    }
  }
}

With an available tileset-source and a recipe.json file like the above example,

Create a tileset

mapbox-tileset tileset create <tileset-id> <recipe.json file>

Finally, to generate the tileset that will be usable in a Mapbox map,

Publish a tileset

mapbox-tileset tileset publish <tileset-id>

This step generates a job that can take quite a while to complete, depending on the number of zoom levels required and how much geographical area is included in the geometry sources.

Check tileset status

mapbox-tileset tileset status <tileset-id>

Other commands:

List available tileset-sources

mapbox-tileset source list

Delete a tileset-source

mapbox-tileset source delete <source-id>

List available tilesets

mapbox-tileset tileset list

Get recipe of a tileset

mapbox-tileset tileset recipe <tileset-id>

Delete a tileset

mapbox-tileset tileset delete <tileset-id>