In a previous series of posts, Data Clinic detailed the creation of TREC, an open source tool designed to show both essential service access and climate risks at transit stations, and talked about its launch. TREC is made with the help of some third-party services, including the web map that greets you when you open the app. Since TREC is one of Data Clinic’s open source products, we were excited to learn about the open source single-file map format PMTiles. PMTiles enables mapping at a “fraction of the cost” according to protomaps.com, and offers a chance for us to make our products even more open source.
Here at Data Clinic, we have worked with many engineers in mission-driven organizations, and find that they frequently build and maintain web maps. With them in mind, we’re going to get into the technical details about how we integrated PMTiles into TREC, and offer our assessment of this new piece of geospatial tech.
The Setup Process
Using PMTiles requires some more setup than the typical mapping API. For engineers that have not worked with basemap data before, there will be a bit of a learning curve as you adjust to this new ecosystem. The first step is getting basemap data from OpenStreetMap (or OSM), the free and open global geographic database. There are several guides available on how to source and download extracts, such as this one. Another open source tool to get data from OSM is Planetiler. The unprocessed data these tools return, known as extracts, are delivered in a format specific to OpenStreetMap, so the next step is converting it to the PMTiles format. This can be done using the pmtiles command line tool or from GDAL.
You can skip this conversion step, and extract this data directly in the PMTiles format by using some tools in the broader Protomaps ecosystem: either a web interface or an open source command line library. This is much easier than setting up the data yourself, but you do lose some customizability in the process.
Hosting map data is another setup step to manage when using PMTiles. One thing that makes PMTiles distinct is that it is a single-file format, which makes it easy to host on CDNs (Content Delivery Networks). In practice, data can be hosted on any web server that has support for HTTP Range Requests, which is the same browser technology used to stream videos on the web. Broadly, the process is as simple as adding the file to a server or CDN and enabling public access. The Protomaps documentation goes into more detail here, making this step an easy one.
After completing all the above steps, viewing the data is straightforward for any engineer who’s worked with a JavaScript map library. Documentation on the Protomaps project page describes how to display PMTiles data on a variety of map clients, including MapLibre, an open source map client for the browser. You’ll have to install the pmtiles package from NPM, and then add it to MapLibre as a protocol, in order to support the range requests mentioned above. The code will look something like:
import * as pmtiles from "pmtiles";
let protocol = new pmtiles.Protocol();
maplibregl.addProtocol("pmtiles",protocol.tile);
{
"sources": {
"protomaps": {
"type": "vector",
"url": "pmtiles://example.pmtiles",
}
}
}
The Verdict
There are relatively few steps required to give PMTiles a try as the mapping solution in your web app. Though the project is new and rapidly changing, the documentation is solid. The primary benefit we can see is that PMTiles removes at least one third-party service engineers have to manage over the long term. PMTiles allows map data to be stored as a single file, which can really simplify development and deployment. The downside is, of course, that using PMTiles requires an understanding of basemap data, web hosting, and possibly CDNs and their associated costs. If this is something an organization cannot do, then it’s best to try a fully-managed, third-party mapping service. But if an organization or vendor has access to somebody with these skills, PMTiles is a great fit.
