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(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, lat : float

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

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

Bases: mercantile.Tile

An XYZ web mercator tile

Attributes:
x, y, z : int

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

mercantile.minmax

Minimum and maximum tile coordinates for a zoom level

Parameters:
zoom : int

The web mercator zoom level.

Returns:
minimum : int

Minimum tile coordinate (note: always 0).

maximum : int

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