Command line interface¶
$ mercantile --help
Usage: mercantile [OPTIONS] COMMAND [ARGS]...
Command line interface for the Mercantile Python package.
Options:
-v, --verbose Increase verbosity.
-q, --quiet Decrease verbosity.
--version Show the version and exit.
--help Show this message and exit.
Commands:
bounding-tile Print the bounding tile of a lng/lat point, bounding box, or
GeoJSON objects.
children Print the children of the tile.
neighbors Print the neighbors of the tile.
parent Print the parent tile.
quadkey Convert to/from quadkeys.
shapes Print the shapes of tiles as GeoJSON.
tiles Print tiles that overlap or contain a lng/lat point, bounding
box, or GeoJSON objects.
Examples¶
mercantile shapes generates GeoJSON from tiles and mercantile tiles
performs the reverse operation.
$ mercantile shapes "[2331, 1185, 12]" | mercantile tiles 12
[2331, 1185, 12]
If you have geojsonio-cli installed, you can shoot this GeoJSON straight to geojson.io for lightning-fast visualization and editing.
$ echo "[-105, 39.99, -104.99, 40]" \
| mercantile tiles 14 \
| mercantile shapes --collect \
| geojsonio
mercantile parent and mercantile children traverse the hierarchy
of Web Mercator tiles.
$ mercantile parent "[2331,1185,12]" | mercantile children
[2330, 1184, 12]
[2331, 1184, 12]
[2331, 1185, 12]
[2330, 1185, 12]
mercantile quadkey will convert to/from quadkey representations of tiles.
$ mercantile quadkey "[486, 332, 10]"
0313102310
$ mercantile quadkey 0313102310
[486, 332, 10]
bounding-tile¶
The bounding-tile command writes the input’s bounding tile, the smallest mercator tile of any resolution that completely contains the input.
$ mercantile bounding-box --help
Usage: mercantile bounding-tile [OPTIONS] [INPUT]
Print the Web Mercator tile at ZOOM level bounding GeoJSON [west, south,
east, north] bounding boxes, features, or collections read from stdin.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Example:
echo "[-105.05, 39.95, -105, 40]" | mercantile bounding-tile
[426, 775, 11]
Options:
--seq / --lf Write a RS-delimited JSON sequence (default is LF).
--help Show this message and exit.
Note that when the input crosses longitude 0 or latitude 0, or any such tile boundary, the bounding tile will be at a shallow zoom level.
$ echo "[-1, 1, 1, 2]" | mercantile bounding-tile
[0, 0, 0]
$ echo "[-91, 1, -89, 2]" | mercantile bounding-tile
[0, 0, 1]
Compare these bounding tiles to the one for a similarly size input box shifted away from the zoom=1 tile intersection.
$ echo "[-92, 1, -91, 2]" | mercantile tiles bounding-tile
[31, 63, 7]
children¶
$ mercantile children --help
Usage: mercantile children [OPTIONS] [INPUT]
Takes [x, y, z] tiles as input and writes children to stdout in the same
form.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Example:
echo "[486, 332, 10]" | mercantile children
[972, 664, 11]
[973, 664, 11]
[973, 665, 11]
[972, 665, 11]
Options:
--depth INTEGER Number of zoom levels to traverse (default is 1).
--help Show this message and exit.
neighbors¶
The neighbors command writes out the tiles adjacent to the input tile.
$ mercantile neighbors --help
Usage: mercantile neighbors [OPTIONS] [INPUT]
Takes [x, y, z] tiles as input and writes adjacent tiles on the same zoom
level to stdout in the same form.
There are no ordering guarantees for the output tiles.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Example:
echo "[486, 332, 10]" | mercantile neighbors
[485, 331, 10]
[485, 332, 10]
[485, 333, 10]
[486, 331, 10]
[486, 333, 10]
[487, 331, 10]
[487, 332, 10]
[487, 333, 10]
Options:
--help Show this message and exit.
parent¶
The parent command writes out the tiles that contain the input tiles.
$ mercantile parent --help
Usage: mercantile parent [OPTIONS] [INPUT]
Takes [x, y, z] tiles as input and writes parents to stdout in the same
form.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Example:
echo "[486, 332, 10]" | mercantile parent
[243, 166, 9]
Options:
--depth INTEGER Number of zoom levels to traverse (default is 1).
--help Show this message and exit.
quadkey¶
The quadkey command converts between [x, y, z] arrays and quadkey strings.
$ mercantile parent --help
Usage: mercantile quadkey [OPTIONS] [INPUT]
Takes [x, y, z] tiles or quadkeys as input and writes quadkeys or a [x, y,
z] tiles to stdout, respectively.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Examples:
echo "[486, 332, 10]" | mercantile quadkey
0313102310
echo "0313102310" | mercantile quadkey
[486, 332, 10]
Options:
--help Show this message and exit.
shapes¶
The shapes command writes tile shapes to several forms of GeoJSON.
$ mercantile shapes --help
Usage: mercantile shapes [OPTIONS] [INPUT]
Print tiles as GeoJSON feature collections or sequences.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Tile descriptions may be either an [x, y, z] array or a JSON object of the
form
{"tile": [x, y, z], "properties": {"name": "foo", ...}}
In the latter case, the properties object will be used to update the
properties object of the output feature.
Example:
echo "[486, 332, 10]" | mercantile shapes --precision 4 --bbox
[-9.1406, 53.1204, -8.7891, 53.3309]
Options:
--precision INTEGER Decimal precision of coordinates.
--indent INTEGER Indentation level for JSON output
--compact / --no-compact Use compact separators (',', ':').
--geographic Output in geographic coordinates (the default).
--mercator Output in Web Mercator coordinates.
--seq Write a RS-delimited JSON sequence (default is
LF).
--feature Output as sequence of GeoJSON features (the
default).
--bbox Output as sequence of GeoJSON bbox arrays.
--collect Output as a GeoJSON feature collections.
--extents / --no-extents Write shape extents as ws-separated strings
(default is False).
--buffer FLOAT Shift shape x and y values by a constant number
--help Show this message and exit.
tiles¶
With the tiles command you can write descriptions of tiles intersecting with a geographic point, bounding box, or GeoJSON object.
$ mercantile tiles --help
Usage: mercantile tiles [OPTIONS] [ZOOM] [INPUT]
Lists Web Mercator tiles at ZOOM level intersecting GeoJSON [west, south,
east, north] bounding boxen, features, or collections read from stdin.
Output is a JSON [x, y, z] array.
Input may be a compact newline-delimited sequences of JSON or a pretty-
printed ASCII RS-delimited sequence of JSON (like
https://tools.ietf.org/html/rfc8142 and
https://tools.ietf.org/html/rfc7159).
Example:
$ echo "[-105.05, 39.95, -105, 40]" | mercantile tiles 12
[852, 1550, 12]
[852, 1551, 12]
[853, 1550, 12]
[853, 1551, 12]
Options:
--seq / --lf Write a RS-delimited JSON sequence (default is LF).
--help Show this message and exit.
$ echo "[-105, 39.99, -104.99, 40]" | mercantile tiles 14
[3413, 6202, 14]
[3413, 6203, 14]
When supplying GeoJSON as input, you may need to first compact with the help of jq
$ cat input.geojson | jq -c . | mercantile tiles 14