mercantile package¶
Subpackages¶
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:
tuple
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.
-
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
- 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 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
- 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
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.
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.