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