tilesets-cli

CLI for interacting with and preparing data for Mapbox Tilesets API.

Contributing

CONTRIBUTING.md includes information about release processes & running tests. 🙌

Installation

# clone
git clone [email protected]:mapbox/tilesets-cli.git
cd tilesets-cli

# virtual env (optional)
mkvirtualenv tilesets-cli

# install deps
pip install .

# confirm installation was successful
tilesets --help
tilesets --version

Requirements

• Python >= 3.6 (can be installed via virtualenv)
• virtualenv / virtualenvwrapper (optional)

Mapbox Access Tokens

In order to use the tilesets endpoints, you need a Mapbox Access Token with tilesets:write and tilesets:read scopes. This is a secret token, so do not share it publicly!

You can either pass the Mapbox access token to each command with the --token flag or export it as an environment variable. Acceptable values are:

• MAPBOX_ACCESS_TOKEN
• MapboxAccessToken

Set the environment variable with export

export MAPBOX_ACCESS_TOKEN=my.token

Commands

• Tileset Sources
  • add-source
  • validate-source
  • view-source
  • list-sources
  • delete-source
• Recipes
  • view-recipe
  • validate-recipe
  • update-recipe
• Tilesets
  • create
  • publish
  • status
  • job
  • jobs
  • list

add-source

tilesets add-source <username> <id> <file>

Flags:

• --no-validation [optional]: do not validate source data locally before uploading

Usage

# single file
tilesets add-source <username> <id> ./file.geojson

# multiple files
tilesets add-source <username> <id> file-1.geojson file-4.geojson

# directory of files
tilesets add-source <username> <id> ./path/to/multiple/files/

Reading from a directory will not distinguish between GeoJSON files and non GeoJSON files. All source files will be run through our validator unless you pass the --no-validation flag.

validate-source

tilesets validate-source <path>

Validates a line delimited GeoJSON source file locally. Example error output:

Invalid line delimited geojson.

view-source

tilesets view-source <username> <id>

Get information for a tileset source, such as number of files, the size in bytes, and the ID in mapbox:// protocol format.

list-sources

tilesets list-sources <username>

List all tileset sources from a particular account. Response is an array of sources.

delete-source

tilesets delete-source

Permanently delete a tileset source and all of its files. This is not a recoverable action!

view-recipe

Prints the Recipe JSON to stdout.

tilesets view-recipe <tileset_id>

validate-recipe

Validates a Recipe JSON document.

tilesets validate-recipe /path/to/recipe.json

Example recipe.json:

{
  "version": 1,
  "layers": {
    "trees": {
      "source": "mapbox://tileset-source/{username}/trees-data",
      "minzoom": 4,
      "maxzoom": 8
    }
  }
}

See more details about the recipe spec here. See recipe examples here.

Example error output:

{
  "errors": [
    "Unknown top-level key \"potato\"."
  ],
  "valid": false
}

update-recipe

Update the Recipe JSON for a tileset. Performs a server-side validation of the new document.

tilesets update-recipe <tileset_id> /path/to/recipe.json

create

Creates a brand new, empty tileset with a recipe passed in from your local filesystem.

tilesets create <tileset_id> --recipe /path/to/recipe.json --name "My neat tileset"

Flags:

• --recipe or -r [required]: path to your Recipe JSON document
• --name or -n [required]: human-readable name of your tileset. (If your tileset_id is user.my_amazing_tileset, you might want your name field to be "My Amazing Tileset".)
• --description or -d: description of your tileset
• --privacy or -p: Set the privacy of the tileset. Allowed values are private and public. If not provided, will default to your plan level on Mapbox.com. Pay-As-You-Go plans only support public maps.

publish

Queues a tiling job using the recipe provided. Use to publish a new tileset or update an existing one. Returns a job ID for progress tracking.

tilesets publish <tileset_id>

status

View the status of a tileset. This includes how many jobs are queued, processing, and complete.

tilesets status <tileset_id>

job

Retrieve a single job for a tileset.

tilesets job <tileset_id> <job_id>

What is a job? Each time you generate or regenerate your output tileset via the publish command (whether that's a new recipe or new source data), a single job is created that processes your data. A tileset can have many jobs, each with a unique identifier. When you publish a tileset, the HTTP response includes the unique job identifier that corresponds to the most recent job. To read more about HTTP design, see this documentation.

jobs

Check all jobs associated with a tileset. You can filter jobs by a particular stage - processing, queued, success, or failed.

tilesets jobs <tileset_id> --stage=processing

• --stage: Filter by the stage of jobs. (Optional.)

list

List all tilesets for an account. Just lists tileset IDs by default. Use the --verbose option for more information.

tilesets list <username>

• --verbose: will list out the entire response object from the API