Protomaps Blog

A new way to make maps with OpenStreetMap

If you develop for the web, you’ve probably heard of OpenStreetMap, an open data alternative to Google Maps. Despite the wide name recognition of OSM, you may have questions like how do I make a web map with OSM data? and how can I host maps myself?

There are popular guides on how to work with planet files, PostGIS databases, and run tileservers for the OSM “slippy map” style. Even if you figure those out, you may be curious about vector maps for high-DPI sharpness and client-side customization of appearance and labels.

Protomaps is a new basemap system which is an end-to-end rethinking of this entire stack, oriented around the idea that custom mapmaking should be simple.

In about five minutes, you can select any area in the world and get a self-contained map that runs locally, offline or serverlessly on S3 - check out the Getting Started guide.

Building Blocks

Web maps are a “full-stack” challenge: Aesthetic goals, such as a sensible arrangement of map labels, need to be supported not only by JavaScript rendering but also the underlying data backend. Protomaps is designed as an end-to-end system for this reason — see What is Protomaps? — although each part is interoperable with other tools.

As of now (April 2021), each component is viable and being used in production; I’ll describe how each fills a specific gap in the map ecosystem, as well as the direction I am developing it towards.

protomaps.js: a vector map renderer and labeler for the web

protomaps.js on GitHub

Where it fits

  • There’s powerful WebGL-based map renderers like MapboxGL JS, Tangram and for vector map tiles. Despite this, the Leaflet library remains extremely popular because of its simple, DOM-driven design. Protomaps.js brings high-DPI vector rendering and map customization to the Leaflet map experience, with some deliberate compromises: see what protomaps.js is not.

  • Protomaps.js is also a system for code-driven map symbology. While the above WebGL libraries and image-based renderers like Mapnik expose a limited API for map labels and markers, protomaps.js is extensible at runtime by implementing custom Symbolizers; it’s an immediate-mode system for direct access to Canvas.

What’s next

  • protomaps.js is alpha stage and needs a lot of work — it’s being used to power all the maps on this site, but the internal API is still unstable. I am open sourcing it now to gauge interest in a pure 2D webmap renderer: protomaps.js on GitHub

  • Labels are currently, well, bad. Linear feature labels are mostly broken; multiple candidate positions should be considered for point labels like cities and POIs. Some features, such as country-specific highway shields, will need to be supported by the vector data from the Downloads service and web map API.

  • Support SVG icons via the protosprites library and port popular open source map styles such as Stamen Design’s Toner.

  • All features need to be designed with performance as a primary goal: while a pure Canvas-based experience will never be as slick as a WebGL one, protomaps.js aims to be just as good as “slippy” image maps.

PMTiles: a serverless format for map tiles

Spec and Reference Python/JS implementations on GitHub

Where it fits

  • Vector map data in the form of Z/X/Y tiles is typically made available as a commercial API. If you don’t need the entire planet, it should be possible to host a piece of the world yourself.

  • Existing formats like MBTiles are based on SQLite. This limits the ability to self-host maps to those confident running a server in production.

  • PMTiles is a format based on HTTP Byte Serving that can be hosted on S3 or any other cloud provider. It can be read directly by the protomaps.js renderer for a totally serverless map application. It’s a perfect match for projects where a long-term subscription to a hosted service is undesirable.

What’s next

Map Downloads & Web API

Downloads | Web API Documentation

Where it fits

  • Eliminates all complexity from getting map data: The current status quo is to use PostgreSQL as an intermediate store for OSM data, and to render tiles from PostgreSQL on-demand. Instead, download pre-rendered PMTiles from the Downloads site, or use the global Web API.

  • Map Downloads (but not web API) snapshot OSM every 60 seconds: this turns OpenStreetMap into a truly live, editable project. This resolves the mismatch between the idea that the map can be improved by anyone, and the reality that map services are weeks or months behind the live data.

  • For those needing a global hosted service, you can sign up for an API key.

What’s next

  • Scaling up: Map downloads are currently limited to 500,000 nodes to help isolate bugs - for example, sometimes the ocean “leaks” into land. If you find problems or have questions, please email me.

  • Map downloads and the Web API should support high-quality label generalizations, highway shields, and beautiful graph-based simplification of road networks.

  • The Infinite Map: PMTiles downloads should be customizable to include any object or tag in OpenStreetMap, via the OSM Express database.

  • OSM as a live project also comes with risks related to vandalism or just broken data. Monthly releases of Facebook’s Daylight Map Distribution should be an option for Map Downloads and the Web API.

OSM Express: a database for OpenStreetMap

Documentation | Minutely Extracts

Where it fits

  • Relational databases are the most popular way to work with OSM, but demand a lossy transformation of the data model. OSMX is a embedded database for nodes, ways and relations to make building applications on fresh OSM data simple. Check it out on GitHub.

  • All Protomaps services are built on top of OSMX; it’s orders of magnitude faster than alternatives. It’s being used by other companies for tasks like generating diffs. Minutely Extracts provides fresh PBF format data for use in other applications like routing and geocoding.

What’s next

  • More OSMX reader libraries in other languages.

  • Applications for visualizing OSM activity in near-realtime built on OSMX.

What’s next for Protomaps

Aside from the existing parts above, there’s other features on the roadmap:

  • Terrain: protomaps.js should render client-side hillshades and contour lines, and Terrarium-format tiles should be downloadable as PMTiles archives, based on SRTM, ASTER or a mosaic dataset.
  • Satellite: A cloudless Landsat or Sentinel-2 imagery layer is a great match for canvas-rendered, custom map labels.

I want to end by clarifying that Protomaps is a self-funded, single-person product, executing on a distinct vision of what web cartography can be. If your company or project has a mapping challenge I might help you solve, schedule a short 30-minute call with me, email me at or find me on Twitter (DMs open), and I’ll of course be publishing on GitHub. If you also happen to be in Taipei, I’ll buy you a coffee.

You’ll see more on this blog soon!