Skip to content

Migration Guide for Stamen Map Tile Users

Stadia Maps has partnered with Stamen Design to host their iconic map styles. If you are currently accessing Stamen map tiles via the Fastly CDN or a Stamen domain, you'll need to make a few (small!) changes to keep on using these maps after August 31, 2023. After this point, we will start progressive brownouts before the old URLs stop working entirely on October 31, 2023.

The typical migration for a web-based map should take about ten minutes. In most cases you'll only need to touch 2 or 3 lines of code. Let's dive in!

Create a Stadia Maps account

We've set up an onboarding flow specifically for Stamen users to make the migration as easy as possible. Click here to get started!

No credit card is required to create an account, and we offer a free tier for non-commercial users. Commercial and higher-volume plans start at just $20/month. If you have any questions about pricing or aren't sure which plan you need, contact us via email.

After verifying your email address, we'll walk you through setting up your domain authentication or API key. Then you're ready to migrate! If you are using the Stamen URLs directly, proceed to our URL-based migration steps. Otherwise, find your framework under the framework/library migration steps.

Toner Hybrid Deprecation Notice

Note that the Toner Hybrid style is deprecated. You can recreate this by combining the lines and labels layer groups. Additionally, you may find that you can achieve the same (or better) by migrating your application to vector styles (currently in beta).

URL-based migration steps

Switch your tile URLs

If you are using the URLs directly (for example, in Leaflet via an L.tileLayer), find your style in the table below and copy the new URL format string. Leaflet users can copy this directly into the L.TileLayer URL configuration. Other map renderers typically use a similar URL format.

Style URLs

What do {x}, {y}, {z}, and {r} mean?

The {x}, {y}, and {z} placeholders represent x, y, and zoom following the standard slippy map tilename convention. This format is used by most popular libraries. Note that our tile numbering uses the XYZ scheme, not TMS.

The {r} placeholder is used for HiDPI ("retina") display suppoort. Popular web map renderers like Leaflet understand this placeholder. If your renderer does not understand this (e.g., MapLibre GL JS or QGIS), you can either remove the placeholder to get raw 256x256 PNGs, or replace it with @2x for 2x scaled images.

Here is a translation table of the primary map styles with all cartographic layers present. Simply change your URLs in Leaflet, OpenLayers, or your other raster map renderer of choice.


If you'd like to use an API key instead of domain auth, simply append ?api_key=YOUR-API-KEY to the URLs above.

Stamen identifier Stadia URL format Notes
watercolor{z}/{x}/{y}.jpg JPEG only; not available in @2x resolution

Layer Group URLs

We also have a migration path for Stamen's "flavors" containing a subset of the cartographic layers in the full style.

Stamen identifier Stadia URL format Notes
toner-background{z}/{x}/{y}{r}.png Includes only background layers (water, landcover, etc.) and lines (roads, borders, etc.)
toner-lines{z}/{x}/{y}{r}.png Includes only line layers (road, borders, etc.)
toner-labels{z}/{x}/{y}{r}.png Includes only label layers (places, road names, etc.)
toner-hybrid Deprecated. You can recreate toner-hybrid by combining the labels and lines layer groups or using vector styles (currently in beta)
terrain-background{z}/{x}/{y}{r}.png Includes only background layers (water, landcover, hillshading, etc.)
terrain-lines{z}/{x}/{y}{r}.png Includes only line layers (road, borders, etc.)
terrain-labels{z}/{x}/{y}{r}.png Includes only label layers (places, road names, etc.)

Updating attribution

Finally, you'll need to update your attribution to include Stadia Maps and (for all styles except Watercolor) OpenMapTiles. In HTML, the full attribution looks like this.

&copy; <a href="" target="_blank">Stadia Maps</a>
&copy; <a href="" target="_blank">Stamen Design</a>
&copy; <a href="" target="_blank">OpenMapTiles</a>
&copy; <a href="" target="_blank">OpenStreetMap contributors</a>

Leaflet example: Bringing it all together

Here's an example of how to update a Toner Lite map to the new URL in Leaflet.

- L.tileLayer('https://stamen-tiles-{s}{z}/{x}/{y}{r}.png', {
+ L.tileLayer('{z}/{x}/{y}{r}.png', {
    maxZoom: 19,
-    attribution: 'Map tiles by <a href="">Stamen Design</a>, Data by &copy; <a href="">OpenStreetMap</a> under <a href="">ODbL<a/>',
+    attribution: '&copy; <a href="" target="_blank">Stadia Maps</a> <a href="" target="_blank">&copy; Stamen Design</a> &copy; <a href="" target="_blank">OpenMapTiles</a> &copy; <a href="" target="_blank">OpenStreetMap</a> contributors',

Framework/library migration steps

We are working with major plugins and library authors to transition to the new URLs, and will update this guide as updates are available. Send us an email if you have any questions.

Leaflet providers

Leaflet Providers has support for the Stamen Styles from Stadia Maps since version 2.0.0. If you are using Leaflet Providers directly, you will need to change your style name slightly. The styles have all moved under the Stadia provider, and the style name has been prefixed with Stamen. For example:

- L.tileLayer.provider('Stamen.Watercolor').addTo(map);
+ L.tileLayer.provider('Stadia.StamenWatercolor').addTo(map);

You con see the full list of available style identifiers on the Leaflet Providers preview site.


If you were previously using the Stamen source in your application, update to the StadiaMaps source instead after upgrading OpenLayers v8.0.0 or higher.

Here is an example of switching a map that had the Stamen Watercolor style and the terrain labels layer.

 import Map from 'ol/Map.js';
-import Stamen from 'ol/source/Stamen.js';
+import StadiaMaps from 'ol/source/StadiaMaps.js';
 import TileLayer from 'ol/layer/Tile.js';
 import View from 'ol/View.js';

 const map = new Map({
   layers: [
     new TileLayer({
-      source: new Stamen({
-        layer: 'watercolor',
+      source: new StadiaMaps({
+        layer: 'stamen_watercolor',
+        // apiKey: 'OPTIONAL' (we suggest domain-based auth)
     new TileLayer({
-      source: new Stamen({
-        layer: 'terrain-labels',
+      source: new StadiaMaps({
+        layer: 'stamen_terrain_labels',
+        // apiKey: 'OPTIONAL' (we suggest domain-based auth)

Still using an older version? No worries. You can reference the tiles directly by URL in an XYZ source. Our OpenLayers tutorial shows you how.


We have opened a pull request with ggmap, and expect version 4.0.0 to fully support the migrated styles. Existing ggmap versions should continue working October 31st (though we will begin showing some warning tiles in September).

Having problems with ggmap?

Certain older ggmap and R configurations may have trouble with loading maps before the cutoff. If you are experiencing, issues, ensure that ggmap and R are reasonably up to date. We have confirmed that RStudio 2022.12.0 running R version 4.3.1 and ggplot 3.0.2 are working.

We're here to help

At Stadia Maps, real human support is part of our DNA. If you have any questions or need further assistance with your migration, send us an email.