Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
5 contributors

Users who have contributed to this file

@mapsam @samfader @dianeschulze @HeyStenson @brsbl
230 lines (157 sloc) 5.85 KB

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.