Skip to content
CLI for interacting with the Mapbox Tilesets API
Python
Branch: master
Clone or download
samfader Merge pull request #14 from mapbox/sf-update-readme
Update readme to clarify how to update a tileset
Latest commit 932d005 Aug 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests Get tokens from the environment when commands are invoked Jul 31, 2019
tilesets Get tokens from the environment when commands are invoked Jul 31, 2019
.coveragerc hi Jul 24, 2019
.gitignore hi Jul 24, 2019
.python-version hi Jul 24, 2019
.travis.yml hi Jul 24, 2019
CHANGELOG.md 0.1.0 Aug 1, 2019
CODE_OF_CONDUCT.md code of conduct (#4) Jul 25, 2019
CONTRIBUTING.md hi Jul 24, 2019
LICENSE.md add license Jul 25, 2019
README.md Update README.md Aug 14, 2019
codecov.yml hi Jul 24, 2019
requirements.txt Relax requirement specifiers Jul 31, 2019
setup.cfg hi Jul 24, 2019
setup.py 0.1.0 Aug 1, 2019

README.md

tilesets-cli

Build Status codecov

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 git@github.com: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 (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

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.)

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
You can’t perform that action at this time.