{"id":4107,"library":"mercantile","title":"Mercantile","description":"Mercantile is a Python library (current version 1.2.1) providing utilities for working with Web Mercator XYZ tiles. It offers functions to convert between geographic coordinates (longitude, latitude) and tile coordinates (x, y, z), calculate tile bounds, and traverse the tile hierarchy (parent, children, neighbors). Releases occur periodically, with significant updates every 1-2 years.","status":"active","version":"1.2.1","language":"en","source_language":"en","source_url":"https://github.com/mapbox/mercantile","tags":["GIS","mapping","tiles","web mercator","geospatial"],"install":[{"cmd":"pip install mercantile","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"mercantile","correct":"import mercantile"},{"note":"Used to get the XYZ tile for a given longitude, latitude, and zoom.","symbol":"tile","correct":"mercantile.tile(lng, lat, zoom)"},{"note":"Used to get the geographic bounding box (west, south, east, north) for a tile.","symbol":"bounds","correct":"mercantile.bounds(x, y, z)"},{"note":"Returns the upper-left (longitude, latitude) coordinate of a tile.","symbol":"ul","correct":"mercantile.ul(x, y, z)"},{"note":"Returns the child tiles of a given tile, optionally at a specific zoom level.","symbol":"children","correct":"mercantile.children(tile, zoom=None)"},{"note":"A namedtuple representing an XYZ tile.","symbol":"Tile","correct":"mercantile.Tile(x, y, z)"},{"note":"A namedtuple representing a longitude and latitude pair.","symbol":"LngLat","correct":"mercantile.LngLat(lng, lat)"}],"quickstart":{"code":"import mercantile\n\n# Get the tile containing a specific longitude, latitude, and zoom level\ntile = mercantile.tile(-105.0, 40.0, 10)\nprint(f\"Tile: {tile}\")\n\n# Get the geographic (longitude and latitude) bounds of a tile\nbbox = mercantile.bounds(tile.x, tile.y, tile.z)\nprint(f\"Bounding Box: {bbox}\")\n\n# Get the upper-left corner (longitude, latitude) of a tile\nul_corner = mercantile.ul(tile.x, tile.y, tile.z)\nprint(f\"Upper-Left Corner: {ul_corner}\")\n\n# Find children tiles at a deeper zoom level\nchildren_tiles = mercantile.children(tile, zoom=11)\nprint(f\"Children tiles (first 2): {children_tiles[:2]}\")","lang":"python","description":"This quickstart demonstrates fundamental operations: getting a tile for a given point, retrieving its geographic bounds, finding its upper-left corner, and identifying its children tiles."},"warnings":[{"fix":"Upgrade to Python 3.x before migrating to Mercantile 2.0.","message":"Mercantile 2.0 (future release) will drop support for Python versions older than 3.0. Running on Python 2.x will issue a `UserWarning` in current versions.","severity":"breaking","affected_versions":"< 3.0 (Mercantile 2.0 and later)"},{"fix":"Ensure `x` and `y` inputs to `mercantile.Tile` are integers and within the valid tile range for the given zoom level.","message":"In Mercantile 2.0 (future release), the `Tile` constructor will enforce stricter validation: `x` and `y` tile indexes must be integers and within the valid range (0 to 2 ** zoom). Current versions issue a `FutureWarning` if these conditions are not met.","severity":"breaking","affected_versions":"1.2.x (as `FutureWarning`), 2.0 (as error)"},{"fix":"For CLI users, use the dedicated `mercantile bounding-tile` command instead of the removed options.","message":"The command line interface (CLI) underwent changes in version 1.2.0 (specifically 1.2a1). The `--bounding-tile` and `--with-bounds` options of the `mercantile tiles` command were removed. A new `mercantile bounding-tile` command was introduced to replace this functionality.","severity":"breaking","affected_versions":"1.2.0+"},{"fix":"Upgrade to Mercantile 1.2.1 or later to ensure proper introspection and documentation for all module functions.","message":"In Mercantile versions prior to 1.2.1, a missing comma in the `__all__` list could prevent `neighbors` and `parent` functions from appearing in module documentation (e.g., `help(mercantile)`). The functions were callable but discoverability was hampered. This was fixed in 1.2.1.","severity":"gotcha","affected_versions":"< 1.2.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}