morecantile

library7.0.3pypypi✓ verified 86d ago

Morecantile is a Python library for constructing and using map tile grids, also known as TileMatrixSet (TMS). It extends the functionality of libraries like mercantile by supporting a wider range of TileMatrixSet grids beyond just Web Mercator. The library is currently at version 7.0.3 and maintains an active release cadence, providing tools to work with OGC TMS specifications (currently TMS 2.0).

database http-networking data

pip install morecantile

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MORECANTILE

morecantile

databasepythonv7.0.3

Install

3.8s avg

Import

701ms

Disk

59MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 4.25s

py 3.11

✓ —

✓ 3.58s

py 3.12

✓ —

✓ 3.03s

py 3.13

✓ —

✓ 3.1s

py 3.9

✕ build_error

✓ 4.8s

59MB installed

● package 59MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tms

✓ import morecantile tms = morecantile.tms.get('WebMercatorQuad')

The 'tms' object is the primary entry point for accessing default and custom TileMatrixSets.

Tile

✓ from morecantile import Tile

Represents a single map tile with x, y, z coordinates.

TileMatrixSet

✓ from morecantile.models import TileMatrixSet

The Pydantic model for defining custom TileMatrixSets.

This quickstart demonstrates how to load a predefined TileMatrixSet, create a Tile object, and retrieve its bounding box in both the TMS's native CRS and in a geographic CRS.

import morecantile # Get a default TileMatrixSet (TMS) like WebMercatorQuad tms = morecantile.tms.get("WebMercatorQuad") # Define a tile (Z, X, Y) tile = morecantile.Tile(x=10, y=10, z=4) # Get the bounding box of the tile in the TMS's CRS (e.g., EPSG:3857 for WebMercatorQuad) xy_bounds = tms.xy_bounds(tile) print(f"Tile {tile} XY Bounds: {xy_bounds}") # Get the bounding box of the tile in Geographic CRS (e.g., EPSG:4326) geographic_bounds = tms.bounds(tile) print(f"Tile {tile} Geographic Bounds: {geographic_bounds}") # List available default TileMatrixSets print(f"Available TMS grids: {morecantile.tms.list()[:3]}...")

Debug

Known issues

breakingMorecantile 7.0.0 dropped support for Python versions 3.8, 3.9, and 3.10. It now requires Python 3.11 or newer.

fix

Upgrade your Python environment to version 3.11 or later to use morecantile 7.x.

affects: >=7.0.0

breakingStarting with version 7.0.0, the default CRS for GeoJSON outputs from methods like `TileMatrixSet.feature` is now WGS84 (EPSG:4326) as per specification. Additionally, property names like `grid_name` and `grid_crs` were renamed to `tms` and `tms_crs` respectively within GeoJSON responses.

fix

Update your code to expect WGS84 for GeoJSON outputs, and adjust property access for `tms` and `tms_crs` if you were consuming `grid_name` or `grid_crs`. If you need a different CRS, explicitly set the `geographic_crs` option in the relevant methods.

affects: >=7.0.0

gotchaThe `TileMatrixSet.is_valid` method became strict by default in 7.0.0. This means it will raise an error if a requested tile's zoom level is beyond the TMS's `maxzoom` and a corresponding `TileMatrix` is not explicitly defined, whereas previous versions might have issued a `UserWarning`.

fix

If your application relies on the previous, more lenient behavior, you can pass `strict=False` to the `is_valid` method: `tms.is_valid(x, y, z, strict=False)`.

affects: >=7.0.0

breakingMorecantile versions 4.0.0 and above adopted the OGC TMS 2.0 specification, which introduced several breaking changes to the TMS JSON document structure. Key field renames include `identifier` to `id`, `supportedCRS` to `crs`, `tileMatrix` to `tileMatrices`, and `topLeftCorner` to `pointOfOrigin`.

fix

If you are defining custom TileMatrixSets using JSON files, update your JSON documents to conform to the TMS 2.0 specification. Alternatively, for older TMS v1 JSONs, use the `TileMatrixSet.from_v1` class method to parse them.

affects: >=4.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'morecantile'

The 'morecantile' library is not installed in the Python environment being used.

fix

Install the library using pip: `pip install morecantile`

Exception: Invalid identifier: <TMS_NAME>

The TileMatrixSet identifier provided to `morecantile.tms.get()` does not correspond to a registered or default TMS.

fix

Use a valid TMS identifier from `morecantile.tms.list()` or register a custom TMS. For example: `tms = morecantile.tms.get("WebMercatorQuad")`

AssertionError: Tile(x, y, z) is not valid

The `is_valid` method of a TileMatrixSet has been called with a tile (x, y, z) that falls outside the defined bounds or zoom levels for that TMS, and the `strict` parameter is implicitly or explicitly `True` (default in more recent versions).

fix

Ensure the tile coordinates (x, y, z) are within the valid range for the given TileMatrixSet's definition, or use `strict=False` if you want to allow out-of-bounds tiles with a warning instead of an error: `tms.is_valid(x, y, z, strict=False)`.

morecantile.errors.PointOutsideTMSBounds

An operation, such as finding a tile for a given longitude/latitude, was attempted with coordinates that lie outside the geographic bounding box defined by the TileMatrixSet.

fix

Adjust the input coordinates to be within the TMS's defined geographic boundaries, or ensure the correct TMS is being used for the given location.

Upgrade

Version history

7.0.3latest on PyPI · released Feb 4, 2026

Audit

Dependencies

pyprojrequiredCore dependency for Coordinate Reference System (CRS) transformations.

pydanticrequiredUsed for defining and validating TileMatrixSet documents.

rasteriooptionalOptional dependency for integration with raster data operations, often installed as an extra.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/developmentseed/morecantile ↗

packagehttps://pypi.org/project/morecantile/ ↗

docshttps://developmentseed.org/morecantile/ ↗