mercantile package

Module contents

Web mercator XYZ tile utilities

class mercantile.Bbox(left, bottom, right, top)

Bases: tuple

A web mercator bounding box

Attributes
left, bottom, right, topfloat

Bounding values in meters.

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.

bottom

Alias for field number 1

left

Alias for field number 0

right

Alias for field number 2

top

Alias for field number 3

class mercantile.LngLat(lng, lat)

Bases: tuple

A longitude and latitude pair

Attributes
lng, latfloat

Longitude and latitude in decimal degrees east or north.

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.

lat

Alias for field number 1

lng

Alias for field number 0

class mercantile.LngLatBbox(west, south, east, north)

Bases: tuple

A geographic bounding box

Attributes
west, south, east, northfloat

Bounding values in decimal degrees.

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.

east

Alias for field number 2

north

Alias for field number 3

south

Alias for field number 1

west

Alias for field number 0

class mercantile.Tile(x, y, z)

Bases: mercantile.Tile

An XYZ web mercator tile

Attributes
x, y, zint

x and y indexes of the tile and zoom level z.

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.

mercantile.bounding_tile(*bbox, **kwds)

Get the smallest tile containing a geographic bounding box

NB: when the bbox spans lines of lng 0 or lat 0, the bounding tile will be Tile(x=0, y=0, z=0).

Parameters
bboxsequence of float

west, south, east, north bounding values in decimal degrees.

Returns
Tile
mercantile.bounds(*tile)

Returns the bounding box of a tile

Parameters
tileTile or tuple

May be be either an instance of Tile or 3 ints (X, Y, Z).

Returns
LngLatBbox
mercantile.children(*tile, **kwargs)

Get the children of a tile

The children are ordered: top-left, top-right, bottom-right, bottom-left.

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

zoomint, optional

Returns all children at zoom zoom, in depth-first clockwise winding order. If unspecified, returns the immediate (i.e. zoom + 1) children of the tile.

Returns
list
Raises
InvalidZoomError

If the zoom level is not an integer greater than the zoom level of the input tile.

Examples

>>> children(Tile(0, 0, 0))
[Tile(x=0, y=0, z=1), Tile(x=0, y=1, z=1), Tile(x=1, y=0, z=1), Tile(x=1, y=1, z=1)]
>>> children(Tile(0, 0, 0), zoom=2)
[Tile(x=0, y=0, z=2), Tile(x=0, y=1, z=2), Tile(x=0, y=2, z=2), Tile(x=0, y=3, z=2), ...]
mercantile.feature(tile, fid=None, props=None, projected='geographic', buffer=None, precision=None)

Get the GeoJSON feature corresponding to a tile

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

fidstr, optional

A feature id.

propsdict, optional

Optional extra feature properties.

projectedstr, optional

Non-standard web mercator GeoJSON can be created by passing ‘mercator’.

bufferfloat, optional

Optional buffer distance for the GeoJSON polygon.

precisionint, optional

GeoJSON coordinates will be truncated to this number of decimal places.

Returns
dict
mercantile.lnglat(x, y, truncate=False)

Convert web mercator x, y to longitude and latitude

Parameters
x, yfloat

web mercator coordinates in meters.

truncatebool, optional

Whether to truncate or clip inputs to web mercator limits.

Returns
LngLat
mercantile.minmax(zoom)

Minimum and maximum tile coordinates for a zoom level

Parameters
zoomint

The web mercator zoom level.

Returns
minimumint

Minimum tile coordinate (note: always 0).

maximumint

Maximum tile coordinate (2 ** zoom - 1).

Raises
InvalidZoomError

If zoom level is not a positive integer.

Examples

>>> minmax(1)
(0, 1)
>>> minmax(-1)
Traceback (most recent call last):
...
InvalidZoomError: zoom must be a positive integer
mercantile.neighbors(*tile, **kwargs)

The neighbors of a tile

The neighbors function makes no guarantees regarding neighbor tile ordering.

The neighbors function returns up to eight neighboring tiles, where tiles will be omitted when they are not valid e.g. Tile(-1, -1, z).

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

Returns
list

Examples

>>> neighbors(Tile(486, 332, 10))
[Tile(x=485, y=331, z=10), Tile(x=485, y=332, z=10), Tile(x=485, y=333, z=10), Tile(x=486, y=331, z=10), Tile(x=486, y=333, z=10), Tile(x=487, y=331, z=10), Tile(x=487, y=332, z=10), Tile(x=487, y=333, z=10)]
mercantile.parent(*tile, **kwargs)

Get the parent of a tile

The parent is the tile of one zoom level lower that contains the given “child” tile.

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

zoomint, optional

Determines the zoom level of the returned parent tile. This defaults to one lower than the tile (the immediate parent).

Returns
Tile

Examples

>>> parent(Tile(0, 0, 2))
Tile(x=0, y=0, z=1)
>>> parent(Tile(0, 0, 2), zoom=0)
Tile(x=0, y=0, z=0)
mercantile.quadkey(*tile)

Get the quadkey of a tile

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

Returns
str
mercantile.quadkey_to_tile(qk)

Get the tile corresponding to a quadkey

Parameters
qkstr

A quadkey string.

Returns
Tile
mercantile.simplify(tiles)

Reduces the size of the tileset as much as possible by merging leaves into parents.

Parameters
tilesSequence of tiles to merge.
Returns
list
mercantile.tile(lng, lat, zoom, truncate=False)

Get the tile containing a longitude and latitude

Parameters
lng, latfloat

A longitude and latitude pair in decimal degrees.

zoomint

The web mercator zoom level.

truncatebool, optional

Whether or not to truncate inputs to limits of web mercator.

Returns
Tile
mercantile.tiles(west, south, east, north, zooms, truncate=False)

Get the tiles overlapped by a geographic bounding box

Parameters
west, south, east, northsequence of float

Bounding values in decimal degrees.

zoomsint or sequence of int

One or more zoom levels.

truncatebool, optional

Whether or not to truncate inputs to web mercator limits.

Yields
Tile

Notes

A small epsilon is used on the south and east parameters so that this function yields exactly one tile when given the bounds of that same tile.

mercantile.ul(*tile)

Returns the upper left longitude and latitude of a tile

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

Returns
LngLat

Examples

>>> ul(Tile(x=0, y=0, z=1))
LngLat(lng=-180.0, lat=85.0511287798066)
>>> mercantile.ul(1, 1, 1)
LngLat(lng=0.0, lat=0.0)
mercantile.xy_bounds(*tile)

Get the web mercator bounding box of a tile

Parameters
tileTile or sequence of int

May be be either an instance of Tile or 3 ints, X, Y, Z.

Returns
Bbox

Notes

Epsilon is subtracted from the right limit and added to the bottom limit.

Subpackages