A. Using Published Tiled Maps

In this module, we will learn to use a map from a published (third-party) tiled map server as the background for your StoryMap.

Estimated time: 30-45 mins.

About Custom Maps

Several map servers are offered in StoryMapJS as built-in options, but you may find that none of these maps meet your requirements. To display your storymap using a tile server which is not included in the built-in list, you will need to point StoryMapJS to the server you need.

This module focuses on published tiled map servers.

To create your own tile server from a georeferenced map, see the module on Using Your Own Map.

To use a scan of a map without georeferencing, or to use any other image as the background for your StoryMap (a story panorama), see the module on Using a Picture to make a Story Panorama.

About Tiled Maps and Tile Map Servers

StoryMapJS uses tiled maps to generate the map in your storymap. A tiled map makes a map out of many separate map sections, tiled together like a patchwork quilt. StoryMapJS does not store any tiled maps. It pulls the map tiles from a tile map server.

StoryMapJS will access your tile map server every time the storymap is viewed or edited. Map servers are sometimes taken down with little warning. If the tile map server you are using goes offline, the map area in your StoryMap will appear blank.

If you are using a tiled map provided by a third party, check the map’s terms of use to find out whether you are allowed to use it. Some hosts also impose limits on how frequently their map can be accessed. If the host blocks StoryMapJS from accessing the map tiles it needs for your StoryMap, visitors to your StoryMap will see a blank map, or error messages where the map should be.

Using a Published Map Server

Begin by logging back into the StoryMapJS web authoring tool, and select your StoryMap.

Now select Options from the upper left. Map Type is at the bottom of the options list.

The Custom map option (at the bottom of the list at Options/Map Type) allows you to specify any open-access tile map server in TMS or Slippy format.

To use a tile map server, you will need to enter its URL template into the Custom box. The URL template for your map server will look something like:

If your chosen tile map server provides a URL template which looks a little like this, copy and paste that into the Custom box exactly as it is given.

Click Close, and your map should appear. If so, congratulations! If not, read on.

URL Formats of Map Servers

Websites like Openstreetmap.org publish useful lists of URL templates for open maps, but these URL templates may need editing before StoryMapJS can understand them.

Let’s take the OpenCycleMap showing cycle routes. The URL template for this is given as as:
But if we copy and paste this URL into the StoryMapJS Custom box, StoryMap will not find a map. What has gone wrong?


Let’s start at the beginning of the URL template. Right after the http://, we can see [abc]. This text in square brackets is a set of subdomains, which help to make the map show up quickly on your visitors’ screens. We must remove any text in square brackets from the URL template so that StoryMapsJS can understand the template. If we delete [abc]., that gives us a URL of http://tile.opencyclemap.org/cycle/zoom/x/y.png. Let’s put that into the Custom box. StoryMapJS can use subdomains, but they must be entered separately, so we put the subdomains – abc, without square brackets – in the Subdomains box (underneath the Custom box).

Still no map…


Next, let’s look near the end of the URL template. Here we see the section /zoom/x/y. These are parameters, and they indicate where the zoom level and the XY coordinates should be included in each request, so the server knows which map tile to send. But StoryMapJS can only understand the parameters in a particular format. Each parameter must be in curly brackets {} (also known as “braces”) – so we need {x} not x. And StoryMapJS understands {z}, but not zoom.

So let’s delete /zoom/x/y from our URL template and put in /{z}/{x}/{y} instead. Now the URL template has become:

Enter that into the Custom box. Success! The map appears.

Rewriting the URL template
Published URLhttp://[abc].SERVER/zoom/x/y.png
StoryMapsJS-style URLhttp://SERVER/{z}/{x}/{y}.pngabc

Alternative formats

Some map servers use rather different URL template formats.

For example, maps in the MapSurfer.NET format are often accessed as:

So to use the OpenMapSurfer world road map hosted at http://korona.geog.uni-heidelberg.de/tiles/roads, put in:
The map should appear as expected.