Vector tiles and PMTiles: publish a map release
When to use a tile archive, how to check HTTP Range and where queries belong.
Editorial review: 2026-09-23
Choose the read contract
PMTiles packages tiles in an archive that clients can access using HTTP ranges. It is useful for distributing a relatively stable map release. It does not replace an editable database, an attribute-query API or feature-level permissions. Keep authoritative data in the editing system and publish a derivative containing approved attributes.
Prepare a small release
Select a dataset you can redistribute. Document its date, license, CRS and included fields. Generate tiles using your chosen compatible tool and its documentation; record the version, simplification parameters and zoom levels. There is no universal command for every PMTiles producer.
Inspect the local archive with pmtiles show map.pmtiles using the installed official CLI. Review tile type, zoom levels and layer names. The internal vector-layer name must match source-layer in the MapLibre style; the archive filename does not replace it.
Verify storage behavior
Upload first to a test environment supporting Range requests. Replace the URL with your test archive and run:
curl --fail --range 0-126 --dump-header headers.txt --output first-bytes.bin 'https://maps.example.org/releases/map.pmtiles'
The domain is illustrative, not a GeoSAT service. Expect an HTTP 206 partial response with a consistent Content-Range. Confirm CORS from the actual viewer origin. If the server returns the whole archive, do not release it: an initial view might download hundreds of megabytes.
Integrate and measure
Use the documented JavaScript PMTiles protocol, register it before creating the map and declare each style layer. Measure initial bytes, time to the first layer and egress cost with cold and warm caches. Test empty regions and zoom boundaries.
Publish using an immutable version name and update the manifest or style when promoting it. Retain the previous release for rollback. Include generation, storage, requests, egress and operations in cost. For frequent changes or per-user restrictions, compare dynamic tiles and an authenticated API; do not hide private information inside a public archive.
Use an archive for a published map version
PMTiles is useful when a map can be built as a versioned tile archive and served through storage that supports the necessary HTTP range behavior. It is not a replacement for an editing database or an arbitrary feature-query API. A changed inspection record will not appear in a previously built archive until the publication process produces and serves an updated version.
Separate authoritative feature data, derived display tiles and style resources. Keep a release identifier that connects them. A style asking for a field removed from the tile schema can produce a visually incomplete map without an obvious server error.
Specify the tile schema before building
| Decision | Example requirement | Validation |
|---|---|---|
| Layer name | assets in the archive | Style source-layer matches exactly |
| Identifier | Stable asset_id for detail lookup | Selected tile feature resolves to correct record |
| Included properties | Type and condition only | No private attributes in decoded tiles |
| Zoom range | Appropriate for the public task | Overview and operational scale both usable |
| Simplification | Display-only geometry policy | Detail queries use authoritative geometry |
| Attribution | Source and license statement | Visible in the map and documented in release |
Do not copy every database attribute into vector tiles. They are downloadable data, even when a user interface hides properties. Decide whether geometry itself is suitable for public release before optimizing transfer size.
Test hosting with real range requests
Use the storage provider's documented configuration and verify a partial-content response from the actual published archive. A successful full-file download is not enough. Check status, content range, cache behavior and cross-origin headers from the application's origin. Avoid placing an archive behind a proxy that silently strips range handling or compresses it incompatibly.
When configuring MapLibre, register the PMTiles protocol before loading a style that refers to it. Inspect the archive's actual layer names rather than guessing. Follow the official MapLibre integration for the installed versions and bundle the dependency consistently with the application.
Validate a release before switching the public pointer
- Build an archive from an immutable source version and preserve the source-to-release identifier.
- Inspect tile metadata and a few representative tiles, including sparse and dense locations.
- Load the new archive in a preview map with the intended style, glyphs and sprites.
- Check feature identity, attribution, low/high zoom behavior and a location near the dataset boundary.
- Publish using a versioned URL, then update the application reference after validation.
- Keep the previous compatible archive and style available for a bounded rollback window.
Versioned filenames help avoid a mixture of old cached data and new styles. If a release is incorrect, restore the prior map reference while preserving the rejected build for diagnosis. Do not overwrite the only working copy before checking the replacement.
Compare the full publication cost
Count build time, storage, requests, transferred bytes, caching and operator effort. A tile archive can simplify serving, but frequent rebuilds or large downloads may dominate a particular workload. Measure your update frequency and audience rather than promising zero hosting cost.
For rapidly changing operational records, combine tiles for orientation with a bounded feature service for current details. Make the display version visible when stale map information could change a decision. The reference lab demonstrates the data/API boundary; it should not be mistaken for a production tile-distribution benchmark.
Sources and documentation
Next step
Continue in the Open GIS collection. For a specific project, use the total-cost calculator and request an assessment.