Frequently asked questions
Google Maps API
The Google Maps API has a generous free tier, but high fees past 30,000 map loads. Protomaps is designed from the ground up to be a system you run yourself - as a 100% static backend on cloud storage - so you only incur the usage costs of storing and serving that data, which can be pennies for moderate usage.
The Google Terms of Service prohibit caching of data or using map tiles in conjunction with other services like search. Protomaps is a system for serving tiles with zero vendor lock-in.
If your use case is simple and you can afford the Google Maps API, it may be a better choice for your project.
OpenStreetMap is distributed weekly as a single file on planet.osm.org that contains all up-to-date data. It is a raw dataset of tagged features often used for making interactive maps, search, or direction services, but the OSM project does not officially provide those data products itself.
OpenStreetMap does have a standard tile layer called openstreetmap-carto that's displayed on the homepage. This tileset:
Is based on dynamic rendering of raster images, instead of vector tiles that can be customized on the client.
Cannot be redeployed or customized without running many programs such as PostgreSQL, Apache and Mapnik.
Exists for the purpose of assisting contributors to OSM, and thus is updated at high frequency.
Forbids external heavy use or bulk downloads: see the Tile Usage Policy.
Protomaps is a system for serving tilesets, and also provides "basemap" tilesets derived from OSM as free and paid products. Basemaps include the most common features needed in a map's background, like water features, oceans, buildings and roads. These are a processed result of OSM for efficient interactive display via:
Slicing of geometric features into tiles
Simplifying or eliminating features at zoomed-out views (generalization)
Organization of features into layers
Computation of label prominence and positions
Mapbox is a commercial provider of map services, many of which include OpenStreetMap as a data source.
Mapbox, like the Google Maps API, is accessed via a metered-usage API. Protomaps is a system designed for self-hosting with no dependence on a third party or API keys, with unmetered usage - you pay your own storage and bandwidth costs.
Mapbox data is built from a blend of data sources; the basemaps Protomaps distributes are built from OpenStreetMap only, and the design is not yet as advanced. Mapbox data may reflect the state of OSM many months ago; Protomaps on-demand downloads reflect the current state of OSM.
Mapbox has initiated open standards which Protomaps strives to be compatible with:
The Mapbox Vector Tile format. These are also called "PBF" vector tiles, referring to its use of Google's Protocol Buffers serialization format. or "MVT", which is how it is referred to in the rest of this documentation. It's supported by many GIS systems such as PostGIS.
The Mapbox GL frontend rendering library. Version 2 of this library has a restricted source-available license. Version 1 of this library has been forked as MapLibre GL and remains BSD-licensed. Protomaps is designed to officially support only MapLibre GL alongside Leaflet and OpenLayers.
If you need the more detailed data and cartography from the Mapbox API, the features of Mapbox GL version 2, or other Mapbox APIs, it may be a better choice for your project.
Is Protomaps open source?
Yes! All core software libraries and formats are open source under permissive licenses, including:
- The PMTiles specification for tile archives.
- The PMTiles implementations for reading and writing PMTiles across languages and libraries.
- The basemaps tileset generation and display styles.
- The protomaps-leaflet vector tile renderer for Leaflet.
- The OSM Express storage engine.
The technical documentation is in the process of being open sourced.
Do you offer a hosted API?
Yes! If you have light to medium traffic needs, you can sign up for an API key and use a demo API with a soft limit of 1,000,000 tile requests per month. Commercial use of this API requires becoming a GitHub Sponsor, which is meant to offset the cost of running this infrastructure.
Of course, if you're a heavy user of this API, it may become more economical to host it youself!
Why don't you just sell plans for the hosted API?
Selling a hosted service would create a conflict of interest between the open source project and the incentives of a business. Hosted APIs rely on large customers with monthly subscriptions. It's important that those customers don't leave the platform, so the service is either non-FOSS or is difficult to run yourself. The explicit goal of the Protomaps project is to make leaving the platform as simple and easy as possible once you outgrow it. This means it must take the hard route: building a sustainable living for a full-time developer without SaaS lock-in.
If the hosted API is free, why do I need an API key?
Because the edge-cached hosted API costs money to run, and I need the ability to communicate with developers and block abuse of the hosted service (scam websites, doxxing, etc). If you want a hosted, keyless API, you can use raster tiles hosted by OpenStreetMap, which has 100x the budget of a one-person company.
Do you offer geocoding and routing?
No, Protomaps's focus right now is on tileset-powered cartography and interactive visualization. Tiled formats like PMTiles are usually not sufficient for geocoding and routing.
Routing projects and companies:
Geocoding projects and companies:
Why not store individual tiles on S3?
PMTiles is designed for planet-scale datasets with millions of tiles. Uploading 300,000,000 individual tiles, or a full 15-level pyramid, to cloud storage like S3 will cost 1,500 USD in request fees and takes hours to days. PMTiles is a single file that can upload in minutes, incurs few requests, and deduplicates tiles internally, reducing size by as much as 80% for vector basemaps.
If your dataset is less than a few thousand tiles, uploading them each to S3 is a simpler option.
MBTiles by Mapbox is a container format for tiled data, just like PMTiles.
A MBTiles file needs to be accessed as a SQLite database on disk, so requires a running server and disk storage for cloud hosting. PMTiles is designed to be cloud-native and readable in fine-grained parts from remote storage like Amazon S3.
SQLite databases can be accessed over HTTP with approaches like sql.js-httpvfs, but these introduce overhead and client-side complexity with WebAssembly. PMTiles is designed to retrieve any tile with at most two extra requests, and cache those intermediate requests using a spatially ordered design.
If your use case can just read a database from disk, then MBTiles is a more established choice.
Cloud Optimized GeoTIFFs
A Cloud Optimized GeoTIFF (COG) is a raster TIFF file with a specific internal organization that enables remote reads from cloud storage.
PMTiles is inspired directly by COG, with a few key differences:
- PMTiles stores arbitrary tiled data, not just TIFF images.
- COG is backwards-compatible with software that can read GeoTIFF.
- The tiling and overview organization of PMTiles is always a powers-of-two pyramid, used by Web Mercator Z/X/Y map tiles.
- PMTiles has very concise CDN integration because of its internal design. The equivalent for COG is TiTiler.
If your workflows already use GeoTIFF, COG is the best choice. It also makes sense to use PMTiles for vector data in conjunction with COG in the same map application. You can think about PMTiles as "COG for vector tiles".
How do I control costs for public buckets?
Making a storage bucket public means that anonymous users can bulk download your tile archive at once, incurring bandwidth costs. Amazon S3, for example, charges 0.09 per gigabyte.
Protomaps recommends Cloudflare R2 as the first choice of storage platform, because it does not have outgoing bandwidth fees.
Use a limited set of CORS origins, instead of the wildcard
For high traffic public deployments, you should always use the CDN integration, since data remains in private buckets. It's easy to set up!
What about map updates?
PMTiles is designed as a compact write-once format. It's not possible to update a single tile in place without re-writing the entire file.
Updating your map requires re-uploading the new file to cloud storage.
Limited-area OSM PBFS from the OSM downloads service reflect the minute-level state of OpenStreetMap.
Which mapping frontend should I use?
Protomaps recommends Leaflet for most basic use cases, because of its small code footprint, simple API, and large ecosystem of plugins for map UIs and visualization. The display of vector basemaps is powered by the in-house-developed Leaflet plugin, protomaps-leaflet.
More sophisticated web map use cases that want the "smooth-zoom" WebGL-powered user experience should use MapLibre GL JS. This is a larger library with a more powerful API for map styling.
OpenLayers is another mature frontend that has the most GIS-related features. If you're a GIS company or agency, you're probably already using this. Support for PMTiles in OpenLayers is still experimental and not officially supported yet.