Planetary-scale answers, unlocked.
A Hands-On Guide for Working with Large-Scale Spatial Data. Learn more.
The other day, a customer dropped a question in our inbox that made us pause: “Hey, can we use PMTiles with Esri’s JavaScript API?”
Key takeaways
Our first thought? Honestly, probably not. A quick scan of the ArcGIS Maps SDK for JavaScript documentation didn’t show any native support for the PMTiles format. It seemed like a technical dead end.
But “probably not” isn’t really our style. We love a good challenge, so we rolled up our sleeves, fired up our code editors, and started experimenting. And you know what? It is possible. With a clever little workaround, you can get the slick, serverless power of PMTiles lighting up your Esri maps.
This post is the story of how we cracked it—and how you can, too.
To understand the workaround we used with the Esri Javascript API, it helps to first appreciate the core problem PMTiles was built to solve: managing millions of tiny map files in cloud storage. Uploading and synchronizing a massive directory of individual tiles is slow and incredibly difficult to manage.
PMTiles elegantly solves that headache by consolidating everything into a single, cloud-optimized file.
Here’s how it works: a browser first reads the small header of the PMTiles file. This header acts as an internal directory, telling the browser the exact byte-range location for every tile inside the larger file. From then on, the browser uses efficient HTTP Range Requests to ask the cloud storage, “Hey, give me the tile located at position X, Y, and Z.”
The result is a truly serverless format. You get the simplicity of managing a single file with the power to serve it directly from any object storage, drastically simplifying deployment and lowering hosting costs.
So, how do you get your own data into this powerful format? We believe that part should be simple, too. We built our own PMTiles generator to transform massive geographic datasets into a web-ready file with just three lines of code.
Our generator uses a distributed architecture to process your data in parallel for maximum speed, even on small hardware. As a quick test, we converted the entire TIGER railroad dataset—all 112,000 line-strings. The result?
This makes generating large-scale, web-ready PMTiles not just possible, but incredibly cheap and fast.
So, if PMTiles is so great, what’s the catch? The hiccup comes from how Esri’s VectorTileLayer expects to find its data.
VectorTileLayer
Out of the box, it’s looking for a classic tile server URL structure, something like .../Z/X/Y (zoom level, column, row). PMTiles, with its single-file, range-request approach, doesn’t speak that language. It’s a classic case of a mature technology that hasn’t yet caught up with the efficiencies of modern formats.
.../Z/X/Y
To get them to talk to each other, we need to build a small translator. In this case, it’s a lightweight service that sits in the middle, fetches data from the PMTiles file using its native strengths, and then serves it up in the classic Z/X/Y format that the ArcGIS SDK loves.
Z/X/Y
Talk is cheap, right? Here’s a quick video showing what our PMTiles look like, rendered beautifully inside an Esri JavaScript API map.
Ready to stop reading and start coding? We’ve made it incredibly easy for you to get this up and running on your own. No complex setups, we promise.
Here’s a Jupyter notebook hosted in Wherobots that walks through the process, from grabbing geographic data to creating your own optimized .pmtiles file. ➡️ Click here to access the Jupyter notebook
.pmtiles
Next, let’s start the “translator” service we discussed. We’ve open-sourced a lightweight tile server on our GitHub repository. Clone the repo, follow a few simple setup steps, and you’ll be serving your PMTiles to the Esri SDK in minutes. ➡️ Get the code on GitHub
Dive in, play around with the code, and see for yourself how powerful this combination can be. We can’t wait to see what you build! If you have questions or ideas, feel free to open a new discussion thread on GitHub. Better yet, if you’d like to help improve the project, we welcome all contributions to the repo.
No. ArcGIS Maps SDK VectorTileLayer expects a classic /Z/X/Y tile URL. PMTiles does not speak that protocol, so you need a small translator service in the middle.
A lightweight tile server fetches tiles from the PMTiles file using HTTP range requests, then exposes them in the Z/X/Y structure VectorTileLayer expects. Wherobots open-sourced that server on GitHub.
In the post’s test, the full TIGER railroad dataset of 112,000 line-strings became a PMTiles file in under 3.5 minutes for $0.42. It used a distributed generator that runs in three lines of code.
The post links a Wherobots Jupyter notebook for generating PMTiles and a GitHub repository for the open-source tile server that fronts Esri maps. Questions and contributions go to that repo.
RasterFlow is now available in Public Preview
RasterFlow makes planetary-scale earth intelligence workflows easy and costs predictable. We are excited to announce that RasterFlow is now in Public Preview, opening up the power of planetary scale Earth Intelligence to all Wherobots Professional Edition customers! RasterFlow let’s you solve complex monitoring challenges with vision-language models or tailored models for specific use cases, without […]
Most Dangerous Roads for Pedestrians and Cyclists in the US (Part 2)
The Wall Street Journal mapped 1.5 miles of Union Avenue in Memphis. We ran the same test on every U.S. arterial. Westheimer Road in Houston ranks first.
Most Dangerous Highway in the US: 25 Deadliest Stretches
The most dangerous highway in the US is 10 miles of U.S. 19 in Pasco County, Florida. See the 25 deadliest stretches and the worst stretch in each state.
Utility Vegetation Management at Scale with Earth Intelligence
We mapped the trees tall enough to reach power lines in King County, WA and Shasta County, CA, using open NAIP imagery, Meta's canopy height model and Wherobots.
share this article
Awesome that you’d like to share our articles. Where would you like to share it to:
