$ mercantile --help
Usage: mercantile [OPTIONS] COMMAND [ARGS]...
Command line interface for the Mercantile Python package.
Options:
-v, --verbose Increase verbosity.
-q, --quiet Decrease verbosity.
--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.
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.
mercantile shapes
generates GeoJSON from tiles and mercantile tiles
does the reverse operation.
$ mercantile shapes "[2331, 1185, 12]" | mercantile tiles 12
[2331, 1185, 12]
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]
The shapes command writes Mercator tile shapes to several forms of GeoJSON.
$ echo "[106, 193, 9]" | mercantile shapes --indent 2 --precision 6
{
"features": [
{
"geometry": {
"coordinates": [
[
[
-105.46875,
39.909736
],
[
-105.46875,
40.446947
],
[
-104.765625,
40.446947
],
[
-104.765625,
39.909736
],
[
-105.46875,
39.909736
]
]
],
"type": "Polygon"
},
"id": "(106, 193, 9)",
"properties": {
"title": "XYZ tile (106, 193, 9)"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
With the bounding-tile command you can write the input's bounding tile, the smallest mercator tile of any resolution that completely contains the input.
$ echo "[-105, 39.99, -104.99, 40]" | mercantile bounding-tile
[1706, 3101, 13]
Note well that when the input crosses lng 0 or lat 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]
With the tiles command you can write descriptions of tiles intersecting with a geographic point, bounding box, or GeoJSON object.
$ echo "[-105, 39.99, -104.99, 40]" | mercantile tiles 14
[3413, 6202, 14]
[3413, 6203, 14]
The commands can be piped together to do this:
$ echo "[-105, 39.99, -104.99, 40]" \
> | mercantile tiles 14 \
> | mercantile shapes --indent 2 --precision 6
{
"features": [
{
"geometry": {
"coordinates": [
[
[
-105.007324,
39.993956
],
[
-105.007324,
40.010787
],
[
-104.985352,
40.010787
],
[
-104.985352,
39.993956
],
[
-105.007324,
39.993956
]
]
],
"type": "Polygon"
},
"id": "(3413, 6202, 14)",
"properties": {
"title": "XYZ tile (3413, 6202, 14)"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
[
[
-105.007324,
39.97712
],
[
-105.007324,
39.993956
],
[
-104.985352,
39.993956
],
[
-104.985352,
39.97712
],
[
-105.007324,
39.97712
]
]
],
"type": "Polygon"
},
"id": "(3413, 6203, 14)",
"properties": {
"title": "XYZ tile (3413, 6203, 14)"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
or do a round trip like this
$ echo "[106, 193, 9]" | mercantile shapes | mercantile tiles 9
[106, 193, 9]
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
When supplying GeoJSON as input, you may need to first compact with the help of jq
$ cat input.geojson | jq -c . | mercantile tiles 14