tilesets-cli

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

Contributing

CONTRIBUTING.md includes information about release processes & running tests. :raised_hands:

Installation

pip install mapbox-tilesets

Requirements

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

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
  • update
  • delete
  • status
  • job
  • jobs
  • list
  • tilejson

add-source

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

Adds GeoJSON files to a source for tiling. Accepts line-delimited GeoJSON or GeoJSON feature collections as files or via stdin. The CLI automatically converts data to line-delimited GeoJSON prior to uploading.

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
# 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.
tilesets add-source <username> <id> ./path/to/multiple/files/

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.
• --attribution or -a [optional]: set tileset attribution. Must be a JSON string, specifically an array of attribution objects, each with text and link keys. Limited to three attribution objects, 80 characters maximum combined across all text values, and 1000 characters maximum combined across all link values.

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>

update

Update a tileset's information.

tilesets update <tileset_id>
  --name "Hello World"
  --description "Say hi to the world"
  --privacy=private
  --attribution='[{"text":"© Hola Mundo","link":"http://example.com"}]'

Flags:

• --name or -n [optional]: update tileset name
• --description or -d [optional]: update tileset description
• --privacy or -p [optional]: set your tileset to public or private
• --attribution or -a [optional]: set tileset attribution. Must be a JSON string, specifically an array of attribution objects, each with text and link keys. Limited to three attribution objects, 80 characters maximum combined across all text values, and 1000 characters maximum combined across all link values.

delete

Delete a tileset. By default will prompt you for confirmation before deleting.

tilesets delete <tileset_id>

Flags:

• --force or -f to bypass confirmation prompt.

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

tilejson

View the TileJSON for a tileset. tileset_id can be a comma-separated list of up to 15 tilesets for composited requests.

A TileJSON document, according to the specification, attempts to create a standard for representing metadata about multiple types of web-based layers, to aid clients in configuration and browsing.

tilesets tilejson <tileset_id>

Flags

• --secure: By default, resource URLs in the retrieved TileJSON (such as in the "tiles" array) will use the HTTP scheme. Include this query parameter in your request to receive HTTPS resource URLs instead.