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, top : float

Bounding values in meters.

Methods

count($self, value, /) Return number of occurrences of value.
index($self, 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, lat : float

Longitude and latitude in decimal degrees east or north.

Methods

count($self, value, /) Return number of occurrences of value.
index($self, 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, north : float

Bounding values in decimal degrees.

Methods

count($self, value, /) Return number of occurrences of value.
index($self, 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: tuple

An XYZ web mercator tile

Attributes:
x, y, z : int

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

Methods

count($self, value, /) Return number of occurrences of value.
index($self, value[, start, stop]) Return first index of value.
x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

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:
bbox : sequence of float

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

Returns:
Tile
mercantile.bounds(*tile)

Returns the bounding box of a tile

Parameters:
tile : Tile or sequence of int

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

Returns:
LngLatBBox

Notes

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

mercantile.children(*tile, **kwargs)

Get the children of a tile

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

Parameters:
tile : Tile or sequence of int

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

zoom : int, 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

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:
tile : Tile or sequence of int

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

fid : str, optional

A feature id.

props : dict, optional

Optional extra feature properties.

projected : str, optional

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

buffer : float, optional

Optional buffer distance for the GeoJSON polygon.

precision : int, 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, y : float

web mercator coordinates in meters.

truncate : bool, optional

Whether to truncate or clip inputs to web mercator limits.

Returns:
LngLat
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:
tile : Tile or sequence of int

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

zoom : int, 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:
tile : Tile 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:
qk : str

A quadkey string.

Returns:
Tile
mercantile.simplify(tiles)

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

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

Get the tile containing a longitude and latitude

Parameters:
lng, lat : float

A longitude and latitude pair in decimal degrees.

zoom : int

The web mercator zoom level.

truncate : bool, 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, north : sequence of float

Bounding values in decimal degrees.

zooms : int or sequence of int

One or more zoom levels.

truncate : bool, 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:
tile : Tile 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:
tile : Tile 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.