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
(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, latfloat
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, northfloat
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:
mercantile.Tile
An XYZ web mercator tile
- Attributes
- x, y, zint
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.
-
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.