Skip to main content

URL parameters

Parameters can be added to the URL of an ArcGIS StoryMaps item to modify its behavior or activate specific features. They must be added to an ArcGIS StoryMaps URL using the following convention:

[baseURL] + ? + [parameter1] + & + [parameter2] + & + [parameter3] + ...

Base URLs

Base URLs are the server endpoints ArcGIS StoryMaps uses to access resources and functionality. The three base URLs that support parameters are listed below.

Action Base URL
Create a new item https://storymaps.arcgis.com/[storymap-type]/new
Edit an item (builder) https://storymaps.arcgis.com/[storymap-type]/[storymap-itemID]/edit
View an item (viewer) https://storymaps.arcgis.com/[storymap-type]/[storymap-itemID]

Notes:

  • The [storymap-type] can be stories, briefings, frames, collections, templates, or themes.

  • The [storymap-itemID] can be the ID of an ArcGIS item of type StoryMap or StoryMap theme.

  • There is currently no way to view a theme.

Important:

On ArcGIS Enterprise, replace storymaps.arcgis.com with [your-portal-domain]/[web-adaptor-name]/apps/storymaps/.

For example:

https://www.myorg.gov/my-portal/apps/storymaps/[storymap-type]/new

Display parameters

Display parameters are used with the viewer base URL:

https://storymaps.arcgis.com/[storymap-type]
Parameter
Behavior Values
Story Briefing Frame Collection
play Activate autoplay true (default)
false		 ✅ ✅ ❌ ✅
speed Control autoplay speed (requires play=true) slow
medium (default)
fast		 ✅ ✅ ❌ ✅
header Show/hide the header when viewing an item true (default)
false		 ✅ ✅ ❌ ✅
cover Show/hide the cover true (default)
false		 ✅ ✅ ✅ ✅
navigation Show/hide navigation controls true (default)
false		 ❌ ❌ ❌ ✅
item Display a collection item by numerical position 1, 2, 3, ... ❌ ❌ ❌ ✅

Notes:

  • The default is used when no value is specified for a parameter. For example, play is the same as play=true.

  • The header and cover URL parameters will override the currently configured behavior of the item. For example, if a story has the Hide cover activated, cover=true can be used to show the cover. For more information, see Configure story settings.

  • The header is hidden when a story is embedded in an <iframe>, but the header parameter can be used to force it to show. The header is not hidden by default for embedded briefings or collections since it contains navigation elements. For more information, see Standard embedding.

  • Hiding the header for a briefing will make its navigation toolbar unavailable. Readers can still navigate using the keyboard or a slide remote. The header cannot be hidden for a collection.

Display parameter examples

The examples below combine the base URL and display parameters to illustrate how to construct a valid URL for some typical use cases.

Action URL
Enable autoplay at slow speed for a briefing .../briefings/[itemID]?play&speed=slow
Hide the header for a briefing .../briefings/[storymap-itemID]?header=false
Hide the header and cover for a story .../stories/[storymap-itemID]?header=false&cover=false
Hide the header but show the cover for a story .../stories/[storymap-itemID]?header=false&cover=true
Display the fifth item in a collection .../collections/[storymap-itemID]?item=5

Item creation parameters

These parameters are used with the base URL for creating new ArcGIS StoryMaps items:

https://storymaps.arcgis.com/[storymap-type]/new
Parameter
Behavior Values
Story Briefing Frame Collection
theme Create a new ArcGIS StoryMaps item and apply a theme [theme-itemID] ✅ ✅ ❌ ✅
webmap Create a new ArcGIS StoryMaps story and add a web map as the first block [webmap-itemID] ✅ ✅ ❌ ❌
webscene Create a new ArcGIS StoryMaps story and add a web scene as the first block [webscene-itemID] ✅ ✅ ❌ ❌
template Create a new ArcGIS StoryMaps story from a template [template-itemID] ✅ ❌ ❌ ❌

Item creation examples

The examples below combine the base URL and item creation parameters to illustrate how to construct a valid URL for some typical use cases.

Action URL
Create a new briefing and apply a theme .../briefings/new?theme=[theme-itemID]
Create a new story with a web map as the first block .../stories/new?webmap=[webmap-itemID]

Sign in parameters

The parameter below works with all item types.

Parameter
Behavior Values
urlKey Direct the user to the sign in page for a particular organization–for example, if an organization uses enterprise logins. Your ArcGIS organization short name, which is the first part of your organization URL. See example below.

Sign in parameter example

Action URL
Direct readers to sign in at https://myorg.maps.arcgis.com .../briefings/[storymap-itemID]?urlKey=myorg
Tip:

For more information on using the urlKey parameter, see Sharing a StoryMap with an organization-specific link.

Variable parameters (beta)

Beta:

Variable parameters are in beta. If you encounter issues with a beta feature, share your feedback on the Esri Community.

Variable parameters work only when using ArcGIS Online and only with stories. Variable parameters may receive breaking changes, so they are not recommended for use in high-profile production deployments.

Variable parameters allow you to pass information to an ArcGIS StoryMaps item URL that is then available to reference in the URL of embedded content.

Parameter
Behavior Values
var_[variable_name] Defines a variable named variable_name that can be referenced in embed URLs User-provided values
Important:

Variable parameter names must contain only letters and numbers, must be named using the prefix var_, and are case sensitive. Variable values containing spaces or other special characters must be encoded.

Variable parameters can be used with embedded ArcGIS apps that support URL parameters, such as ArcGIS Dashboards, ArcGIS Survey123, ArcGIS Experience Builder, and ArcGIS Instant Apps. You may also be able to use variable parameters when embedding other non-ArcGIS apps or websites.

Dive in:

To learn how URL parameters work in various ArcGIS apps and what you can do with them, see the links below.

Variable parameter examples

The example below illustrates how to construct valid URLs for a typical use case. The first URL shows how to reference the variable parameter in an embed URL, and the second shows how to pass in a value for the variable in the ArcGIS StoryMaps item URL.

This example uses a variable named mercury to pass a value of 0.25 to a dashboard's preconfigured numeric parameter named mercuryMin. The parameter filters the information in the dashboard to only show locations that are above a minimum water quality testing result.

Dashboard URL (added to a story with an embed block):

https://www.arcgis.com/apps/dashboards/[dashboard-itemID]#mercuryMin={{url.mercury}}

ArcGIS StoryMaps item URL:

https://storymaps.arcgis.com/stories/[storymap-itemID]?var_mercury=0.25

Additional resources

Back to top