Vector maps (PMTiles)

A sharp, modern map from one file on your own server: no API key, no costs per view and no third party. The map is a PMTiles file with the Protomaps basemap (made from OpenStreetMap), drawn by MapLibre in the browser. (from v5.0.0)

{exp:reinos_maps:map tiles="pmtiles"}
    {maps:add_marker address="Domplein, Utrecht"}
{/exp:reinos_maps:map}

• No third party: the map, the fonts and the icons come from your own server, the IP address of the visitor goes nowhere else. You don't need the consent gate or the tile proxy for the map.
• No API key and no costs, however many visitors you have.
• Sharp on every screen, with smooth zooming, a dark style for theme="dark" and the labels in the language of the page (<html lang="nl">).
• Everything of Maps works on it: markers, popups, routes, entries, clustering, lazy and consent.

The vector map needs a bit more Javascript (about 300 KB gzipped). Maps only loads it on a page with a vector map, the other maps don't get it.

Setup

You host three things yourself: the map file, the fonts and the icons. The steps are also on the tile in the CP (Maps → Tiles → Self-hosted vector map).

1. The map file

Cut your area out of the Protomaps basemap (the whole world is about 140 GB) with the pmtiles tool. Use a recent build from maps.protomaps.com/builds and the bounding box of your area (west,south,east,north, e.g. from bboxfinder.com):

pmtiles extract https://build.protomaps.com/20261104.pmtiles netherlands.pmtiles --bbox=3.3,50.7,7.3,53.6

Or with Docker, without installing the tool:

docker run --rm -v "$PWD":/data protomaps/go-pmtiles extract https://build.protomaps.com/20261104.pmtiles /data/netherlands.pmtiles --bbox=3.3,50.7,7.3,53.6

The tool only downloads your area. A city is a few MB to some tens of MB, a country hundreds of MB. Add --maxzoom=14 for a smaller file with less detail when zoomed in. Make a new file now and then (e.g. every few months) for the changes in OpenStreetMap.

2. The fonts and icons

Download basemaps-assets and unzip it. It has the folders fonts (the labels, in every script) and sprites (the icons). The fonts are licensed under the SIL Open Font License, the file is in the folder.

3. Upload

Put both on your web server as static files, e.g.:

/maps/netherlands.pmtiles
/maps/basemaps-assets/fonts/...
/maps/basemaps-assets/sprites/...

The web server must support HTTP range requests for the .pmtiles file (the browser asks only the parts it needs). Apache and nginx do that for static files. On another domain (e.g. a CDN or S3) it needs CORS for your site.

4. The tile in the CP

Enable the tile Self-hosted vector map (PMTiles) under Maps → Tiles, and fill in:

• PMTiles file URL: /maps/netherlands.pmtiles
• Fonts and icons URL: /maps/basemaps-assets/

The Diagnostics page checks whether the file answers range requests and whether the fonts and icons are there.

The styles

Tile	Style
pmtiles or pmtiles_light	Light
pmtiles_dark	Dark
pmtiles_white	White, for a calm background
pmtiles_grayscale	Grayscale
pmtiles_black	Black

With theme="dark" (or theme="auto" in dark mode) the light style becomes the dark one and the white style the black one. More styles in the layer control: tiles="pmtiles|pmtiles_grayscale|openstreetmap".

Good to know

• The labels are in the language of the page (<html lang="">), with the local name when there is no translation.
• The map needs WebGL, every current browser has it.
• Outside the area of your file the map is empty. Use a bigger area, or the world up to a low zoom level.