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.

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¶

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.

Layer Group URLs¶

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

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="https://www.stadiamaps.com/" target="_blank">Stadia Maps</a>
&copy; <a href="https://stamen.com/" target="_blank">Stamen Design</a>
&copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a>
&copy; <a href="https://www.openstreetmap.org/about/" 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}.a.ssl.fastly.net/toner-lite/{z}/{x}/{y}{r}.png', {
+ L.tileLayer('https://tiles.stadiamaps.com/tiles/stamen_toner_lite/{z}/{x}/{y}{r}.png', {
    maxZoom: 19,
-    attribution: 'Map tiles by <a href="https://stamen.com/">Stamen Design</a>, Data by &copy; <a href="https://openstreetmap.org/about">OpenStreetMap</a> under <a href="http://www.openstreetmap.org/copyright">ODbL<a/>',
+    attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a> <a href="https://stamen.com/" target="_blank">&copy; Stamen Design</a> &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/about" target="_blank">OpenStreetMap</a> contributors',
}).addTo(map);

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.

OpenLayers¶

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.

ggmap¶

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).

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.