mercantile

What it is and what it does

Mercantile is a utility library for working with Web Mercator tiles—the standard XYZ grid system used by web mapping platforms. It provides functions to convert between geographic coordinates (longitude/latitude), spherical Mercator coordinates, and tile indices at various zoom levels. It also handles quadkey encoding (Microsoft's tile naming scheme) and lets you traverse tile hierarchies by finding parent and child tiles.

The library is primarily used by GIS developers, map tile servers, and geospatial analysis tools. It includes both a Python API with named tuples for tiles and bounding boxes, and a command-line interface (via click) for batch operations like generating GeoJSON tile shapes or finding tiles that overlap a given region. The package has been stable since 2014 and sees consistent use in the geospatial ecosystem.

Use it for:

• Convert geographic coordinates to tile indices for web map tile servers or slippy map implementations.
• Generate GeoJSON representations of Web Mercator tiles for visualization or analysis.
• Find which tiles intersect a bounding box or geographic region.
• Navigate tile hierarchies to zoom in/out or find neighboring tiles.
• Encode/decode quadkeys for tile identification in mapping APIs.
• Build command-line tools for tile processing using the mercantile CLI.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Mercantile converts between geographic coordinates, Web Mercator tiles (XYZ), and quadkeys, and provides utilities to navigate tile hierarchies and generate GeoJSON tile shapes.

Yes. Mercantile is a stable, well-maintained library with no known vulnerabilities, minimal dependencies, and a clear purpose. It's the standard choice for Web Mercator tile math in Python. Install it if you're working with tile-based maps or need to convert between geographic and tile coordinate systems.

Install

mercantile on PyPI

pip install mercantile

uv add mercantile

poetry add mercantile

Installing mercantile

Before you install

Low friction: pure Python wheel with a single lightweight runtime dependency (click). Repository is active with a recent commit (2026-06-29) and has been maintained since its 2014 release.

License in practice

BSD license is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart

pip install mercantile

import mercantile

# Get upper-left corner of a tile
ul = mercantile.ul(486, 332, 10)
print(ul)  # LngLat(lng=-9.140625, lat=53.33087298301705)

# Get bounding box of a tile
bounds = mercantile.bounds(486, 332, 10)
print(bounds)

Verify before relying

• Whether the package actively supports Python 3.10+ or only legacy versions (classifiers list Python 2.7 and generic Python 3, but latest release was 2021-04-21)

Package facts

Evidence: mercantile-1.2.1-py3-none-any.whl

Keywords: mapping, web mercator, tiles

Tags

More GIS packages