Skip to main content

Web mercator XYZ tile utilities

## Project description

Spherical mercator coordinate and tile utilities

Documentation: http://mercantile.readthedocs.io/en/latest/

The mercantile module provides ul(xtile, ytile, zoom) and bounds(xtile, ytile, zoom) functions that respectively return the upper left corner and bounding longitudes and latitudes for XYZ tiles, a xy(lng, lat) function that returns spherical mercator x and y coordinates, a tile(lng, lat, zoom) function that returns the tile containing a given point, and quadkey conversion functions quadkey(xtile, ytile, zoom) and quadkey_to_tile(quadkey) for translating between quadkey and tile coordinates.

>>> import mercantile
>>> mercantile.ul(486, 332, 10)
LngLat(lng=-9.140625, lat=53.33087298301705)
>>> mercantile.bounds(486, 332, 10)
LngLatBbox(west=-9.140625, south=53.12040528310657, east=-8.7890625, north=53.33087298301705)
>>> mercantile.xy(*mercantile.ul(486, 332, 10))
(-1017529.7205322663, 7044436.526761846)
>> mercantile.xy_bounds(486, 332, 10)
Bbox(left=-1017529.7205322663, bottom=7005300.768279833, right=-978393.962050256, top=7044436.526761846)
>>> mercantile.tile(*mercantile.ul(486, 332, 10) + (10,))
Tile(x=486, y=332, z=10)
>>> mercantile.quadkey(486, 332, 10)
'0313102310'
>>> mercantile.quadkey_to_tile('0313102310')
Tile(x=486, y=332, z=10)

Also in mercantile are functions to traverse the tile stack.

>>> mercantile.parent(486, 332, 10)
Tile(x=243, y=166, z=9)
>>> mercantile.children(mercantile.parent(486, 332, 10))
[Tile(x=486, y=332, z=10), Tile(x=487, y=332, z=10), Tile(x=487, y=333, z=10), Tile(x=486, y=333, z=10)]

Named tuples are used to represent tiles, coordinates, and bounding boxes.

## Mercantile CLI

Mercantile’s command line interface, named “mercantile”, has commands for getting the shapes of Web Mercator tiles as GeoJSON and getting the tiles that intersect with a GeoJSON bounding box.

\$ 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.

## See Also

supermercado is another python lib with added tile logic functionality (union tile shapes, find edge tiles, and find tile intersections for complex geometries).

node-sphericalmercator provides many of the same features for Node.

tilebelt has some of the GeoJSON features as mercantile and a few more (tile parents, quadkey).

morecantile is like mercantile, but with support for other TileMatrixSet grids.

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

### Source Distribution

mercantile-1.2.1.tar.gz (26.4 kB view hashes)

Uploaded Source

### Built Distribution

mercantile-1.2.1-py3-none-any.whl (14.8 kB view hashes)

Uploaded Python 3