Skip to content
mapterm

Map sources

The first argument to mapterm is the tile source. Without one, mapterm uses the OpenFreeMap planet.

Terminal window
mapterm                                                # OpenFreeMap planet
mapterm https://build.protomaps.com/20261031.pmtiles   # Protomaps planet, HTTP range requests
mapterm dc.pmtiles                                     # a local PMTiles file, offline
mapterm 'https://example.com/tiles/{z}/{x}/{y}.pbf'    # an XYZ template
mapterm https://example.com/tiles.json                 # a TileJSON endpoint

Formats

Section titled “Formats”
  • PMTiles v3, from a local file or over HTTP range requests. mapterm has its own reader: it fetches the header and directories it needs, then single tiles, so a planet-sized archive opens without downloading it.
  • XYZ URL templates with {z}, {x} and {y}.
  • TileJSON endpoints, which give the tile URLs, zoom range and center.

Tiles must be Mapbox Vector Tiles (MVT), optionally gzipped.

Schemas

Section titled “Schemas”

The built-in styles understand the two common basemap schemas, and mapterm detects which one a source uses from its layer names:

  • OpenMapTiles: OpenFreeMap, MapTiler, and most self-hosted planet builds.
  • Protomaps basemap layers: the Protomaps daily builds and extracts.

With --style, the style decides which source and layers are drawn and the first argument isn’t used.

Offline maps

Section titled “Offline maps”

A PMTiles file is a whole tileset in one file. Make one for a region with the pmtiles CLI:

Terminal window
pmtiles extract https://build.protomaps.com/20261031.pmtiles dc.pmtiles \
  --bbox=-77.12,38.80,-76.91,38.99
mapterm dc.pmtiles --at 38.8899,-77.0091 -z 13

Credits

Section titled “Credits”

The status bar credits the sources that are being drawn, from their own metadata: a TileJSON or PMTiles attribution, a style source’s attribution, or the imagery provider’s credit. Hide a layer and its credit goes too.

Limits and caching

Section titled “Limits and caching”

Every download has a 30 second timeout and an 8 MB cap, and decompression is capped at 32 MB, so a broken or hostile server can’t hang or exhaust mapterm. Tiles that fail to load are retried with backoff (2, 4, 8, 16 seconds); a 404 means the tile is empty. HTTP tiles are cached on disk for 30 days in ~/.cache/mapterm.

Please respect each tile server’s usage policy. OpenFreeMap is free with no key; Protomaps daily builds are meant to be extracted from rather than used as a heavy-traffic tile server.