Using classic Esri Story Maps URL parameters

This article covers a topic related to the classic Esri Story Maps templates. Story authors are encouraged to use the current-generation ArcGIS StoryMaps to create stories. However, Esri will continue to maintain the classic templates for your use. For more information, see the product road map.

Classic Esri Story Maps template support many helpful URL parameters. This article serves as a reference for these URL parameters and describes how and when to use them.

The parameters listed later in this article are divided into two groups: one group that is useful for advanced authors and one group that is typically only useful for developers.

Before getting to the list of parameters, here’s a quick primer on how to use them…

How to use URL parameters

To use a parameter, add it to the end of an app’s base URL after an ampersand. If it’s the first parameter on the URL, then use an question mark instead of an ampersand.

For example, there are two parameters in the link below, appid and autoplay. The first is preceded by a ? and the second by an &.

https://story.maps.arcgis.com/apps/MapTour/index.html?appid=79fe8b5237f5437ea427fdf9b897aab5&autoplay

The base URLs for the story map apps hosted on ArcGIS Online are:

https://www.arcgis.com/apps/Cascade/index.html
https://www.arcgis.com/apps/MapJournal/index.html
https://www.arcgis.com/apps/MapSeries/index.html
https://www.arcgis.com/apps/MapTour/index.html
https://www.arcgis.com/apps/Shortlist/index.html
https://www.arcgis.com/apps/StoryMapCrowdsource/index.html
https://www.arcgis.com/apps/StorytellingSwipe/index.html

You can also use your organization’s URL (my-org.maps.arcgis.com) instead of the generic www.arcgis.com.

Note: URLs and URL parameters are cAsE sEnSiTiVe, so be sure to capitalize them as shown.

Parameters For Advanced Authors

These parameters may be useful for advanced authors who want to do more with story maps than is possible in the builders.

Embed mode (no header)

When embedding a story map in a web page or within another story map it is often useful to remove its header using the embed parameter. This parameter is supported by Tour, Series, Shortlist, and Swipe. See this blog post for more detail:

Embedding a Story Map within a Story Map

&embed
http://www.arcgis.com/apps/StorytellingSwipe/index.html?appid=fc64e3596bbd4d3caf865da6d77c386e&embed

Show a story in a particular device layout

Story Map apps are responsive and will show their mobile layout when viewed or embedded at certain dimensions. To show the mobile layout under conditions that otherwise wouldn’t trigger it you can force the mobile layout using forceMobile.

&forceMobile
http://www.arcgis.com/apps/Shortlist/index.html?appid=0584dbad6ebf433a96f1111f4cc7e3bd&forceMobile

Likewise you can force a story to show in Desktop layout using forceDesktop.

&forceDesktop
http://www.arcgis.com/apps/Shortlist/index.html?appid=0584dbad6ebf433a96f1111f4cc7e3bd&forceDesktop

Those last two parameters are supported by Journal, Series, and Shortlist.

Open a story map at a specific part

Story Map Tour, Series, and Journal support parameters to open a story at a specific tour point, tab, bullet, or section. See this blog for details.

Launch a Story Map at a specific place

To summarize:

&index=[tour-point-number]       // Story Map Tour
&entry=[tab-number]              // Story Map Series
&section=[section-number]        // Story Map Journal

Autoplay

You can use autoplay mode to automatically advance through a story map so it will play on an unattended kiosk or public display monitor.

Autoplay can most easily be accessed from the Share panel (by clicking the link icon or share icon in the header), but it can also be triggered using the autoplay parameter. This can be useful since the Share panel is not available when the story is private or if the share controls have been disabled by the author.

Autoplay mode option, as shown in Cascade’s Share panel

Cascade, Journal, Series, and Tour support autoplay. Story Map Swipe also supports autoplay if a swipe series is defined.

&autoplay
https://www.arcgis.com/apps/Cascade/index.html?appid=2f085872b4ce4938bad51ad0b26ec22b&autoplay

Force a story map app to display in another language

Normally the language used for the story map app’s text elements is determined by the language set in the user’s web browser, but the locale parameter can be used to override the browser language setting to simulate how text elements in the story map app look in another supported language.

This parameter can be invoked when viewing or building stories and uses the two-letter ISO country code to specify a language as shown below:

&locale=[language-code]
https://www.arcgis.com/apps/Cascade/index.html?appid=2f085872b4ce4938bad51ad0b26ec22b&locale=es    //Spanish

Note: This parameter does not translate the story (titles, narrative, map labels, etc.); it only affects the text that is part of the app’s user interface elements, such as the Share panel in view mode and all the builder tools.

Cascade’s Share panel in Spanish

Some Cascade builder controls in Spanish

Story Map Basic

Story Map Basic is built on the same framework as the other ArcGIS configurable apps, so it supports app framework of

Parameters for Developers

This group of parameters is most useful for developers who host their own versions of story map apps or are building solutions that create story maps programmatically.

Open a specific story map using its item ID

Use the appid parameter to open a specific story map that’s hosted on ArcGIS Online using its item ID.

?appid=[itemID]

https://www.arcgis.com/apps/Cascade/index.html?appid=2f085872b4ce4938bad51ad0b26ec22b

The story map type of the referenced item must match the app you are using. For example, the Map Tour app can only load Map Tour story items.

This parameter can also be used to open a story map from an ArcGIS Enterprise deployment if you are hosting your own copy of the story map app and have configured it to point to your Enterprise portal in the index.html file.

Using appid can be very useful when hosting your own customized version of a story map app. See this post for details:

Getting the most out of your customized storytelling app — part 1

Open a story in Builder Mode

You can open a story you own — or otherwise have permissions to edit — in builder mode using the edit parameter (and appid to specify the story).

&edit
https://www.arcgis.com/apps/MapTour/index.html?appid=79fe8b5237f5437ea427fdf9b897aab5&edit

Create a new story

Launching a story map builder to create a new story can be accomplished using fromScratch. To author a story you must have permissions to create items.

?fromScratch
https://www.arcgis.com/apps/Cascade/index.html?fromScratch

Create a new Map Series in a specific layout

You can launch the Map Series builder to create a new story from scratch in a particular layout using the layout parameter. Expected values for layout-name include tab, accordion, and bullet.

&layout=[layout-name]                 //Story Map Series ONLY
http://www.arcgis.com/apps/MapSeries/index.html?fromScratch&layout=accordion

Create a new Map Series from a set of existing web maps

Story Map Series also supports the ability to create a new story using existing web maps. Just include itemIDs for web maps separated by commas. You can create a new story with up to 30 web maps this way.

?fromScratch&webmap=ID1,ID2,ID3,...   //Story Map Series ONLY
https://www.arcgis.com/apps/MapSeries/index.html?fromScratch&webmap=80f9b95a4ce0491091f1477710f6a91d,e2e83bc7147542269d8f8186c40bbc9e

More information

For more examples of using URL parameters, check out these articles:

Getting the most out of your customized storytelling app — part 1

Embedding a Story Map within a Story Map

An introduction to hosting your own Story Map

Intro photo by JJ Ying via Unsplash