Mapbox GL JS v3.21.0 added support for vector sources using the PMTiles protocol — another option in your toolkit for bringing spatial data into Mapbox-powered web maps.

What is PMTiles?

PMTiles is a single-file open source format for storing tiled map data — vector or raster — built for random access over HTTP range requests. Host one on any static file server and you have a fully functional tileset, no complicated backend required.

Traditional tile serving follows a familiar pattern: each tile gets its own URL using an x/y/z scheme, and behind that URL is either a directory of pre-cut files or a service dynamically pulling tiles from a database. Either way, there's infrastructure involved.

PMTiles sidesteps all of that. Every tile request hits the same URL — what changes is the byte range. A tile's x/y/z coordinates are converted into a specific byte offset within the file, and the server returns just that chunk. The client receives it and renders it like any other tile, none the wiser.

Using PMTiles in Mapbox GL JS

You're probably already familiar with adding a vector tileset to your map at runtime as a vector source. The existing options are:

• A URL to a TileJSON(https://docs.mapbox.com/help/glossary/tilejson/) metadata file containing the tileset's URL template
• A Mapbox-hosted tileset via its mapbox:// URL (a shorthand for a TileJSON hosted by Mapbox)
• An explicit URL template with {z}/{x}/{y} placeholders

// TileJSON URL
map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'https://somedomain.com/tileset.json'
});

// Mapbox-hosted tileset
map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'mapbox://mapbox.mapbox-terrain-v2'
});

// Explicit x/y/z URL template
map.addSource('some-vector-tileset', {
  type: 'vector',
  tiles: ['https://somedomain.com/tileset/{z}/{x}/{y}']
});

In all three cases, Mapbox GL JS ends up with a {z}/{x}/{y} template URL and uses it to request tiles based on what's in view.

With PMTiles support, you can now pass a .pmtiles file URL directly as the url property:

map.addSource('mapbox-terrain', {
  type: 'vector',
  url: 'https://somedomain.com/tileset.pmtiles'
});

That's it. Mapbox GL JS detects the .pmtiles extension and handles range requests behind the scenes.

A Working Example

The example below shows USGS Earthquake data served from a PMTiles file and visualized with a circlelayer.

See the full example on docs.mapbox.com →

Here's the JavaScript where addSource() is called with a URL to .pmtiles file:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard',
  config: {
    basemap: {
      theme: 'monochrome',
      lightPreset: 'night'
    }
  },
  zoom: 1.78,
  center: [-103.64548, 51.14245]
});

map.on('load', () => {
  map.addSource('pmtiles-earthquakes', {
    type: 'vector',
    url: 'https://docs.mapbox.com/mapbox-gl-js/assets/earthquakes.pmtiles'
  });

  map.addLayer({
    id: 'pmtiles-vector-layer',
    type: 'circle',
    source: 'pmtiles-earthquakes',
    'source-layer': 'earthquakes',
    paint: {
      'circle-color': 'transparent',
      'circle-stroke-color': 'teal',
      'circle-stroke-width': 0.5,
      'circle-radius': 3,
      'circle-emissive-strength': 1
    }
  });
});

How do I make a PMTiles?

The PMTiles file in the example above was generated with tippecanoe from a week's worth of USGS earthquake data (~2,400 point features) and hosted on the same S3 bucket as docs.mapbox.com:

tippecanoe -o public/earthquakes.pmtiles -Z0 -z6 -r1 -pk -l earthquakes data/earthquakes-week.geojson --force

Here's what each flag does:

Try It Yourself

Looking for publicly hosted PMTiles files to experiment with? Check out pmtiles.io — it includes several global vector and raster tilesets and is a handy tool for previewing PMTiles files you generate yourself.

We'd love to hear about what you're building — drop into the #web channel in the Mapbox Discord or share a post on r/mapbox.