R104 · Infrastructure for agents at scale › Consistency and storage tradeoffs

PMTiles: a world map as one file on object storage

Read the original

storagefile-formatsopen-sourceserverlessgeospatial

Source: Protomaps, PMTiles format and tools (protomaps/PMTiles, spec v3) and Protomaps Basemaps (protomaps/basemaps). Code BSD-3, map design CC0, OpenStreetMap-derived tiles ODbL. Highlighted on LinkedIn by André Lindenberg, 2026-11-16.

The idea

Web maps usually mean either paying a provider per map load or running a tile server that answers z/x/y tile requests from a database. PMTiles replaces the server with a file. A whole tileset, up to a planet-scale OpenStreetMap basemap, is packed into one archive placed on commodity object storage (S3, R2 or any host that supports HTTP Range). The browser client (MapLibre GL JS, Leaflet or OpenLayers plug-ins) computes which bytes hold the tile it needs and fetches just those bytes with a range request. For a basemap, there is no backend to operate.

How the format makes that work

  1. Fixed 127-byte header at the start of the file with offsets and lengths of every other section.

  2. Root directory within the first 16 KiB, so a client can fetch header and root directory in a single initial request.

  3. JSON metadata (layers, attribution, bounds).

  4. Optional leaf directories for large tilesets, so directory lookups stay at most a couple of extra range reads.

  5. Tile data, with identical tiles (ocean, empty land) deduplicated.

Tiles are addressed along a Hilbert curve so spatially nearby tiles are near each other in the file, which helps both compression of directories and caching. A planet basemap can be built from OpenStreetMap and Natural Earth with a Planetiler profile in a few hours on a modest machine; pmtiles convert and pmtiles upload handle conversion from MBTiles and upload.

The general pattern

PMTiles is one instance of cloud-optimized single-file formats: Cloud Optimized GeoTIFF, Parquet with footers and row-group statistics, and similar designs. The recipe is the same: a small index at a known offset, data laid out for locality, and clients that turn logical lookups into byte-range reads. It trades a running service for a smarter client and a CDN.

Tradeoffs

Failure modes

Review checklist

Connections

See R104 on the knowledge map

Part of the Research notes on nowucca.com. Figures and claims are the source's own unless the summary says otherwise.