arcgis.apps.storymap module

StoryMap Implementation

The StoryMap is the main entry point into the Story Map module.

StoryMap

class arcgis.apps.storymap.story.StoryMap(item=None, gis=None)

Bases: object

A Story Map is a web map that has been thoughtfully created, given context, and provided with supporting information so it becomes a stand-alone resource. It integrates maps, legends, text, photos, and video and provides functionality, such as swipe, pop-ups, and time sliders, that helps users explore this content.

ArcGIS StoryMaps is the next-generation storytelling tool in ArcGIS, and story authors are encouraged to use this tool to create stories. The Python API can help you create and edit your stories.

Create a Story Map object to make edits to a story. Can be created from an item of type ‘Story Map’, an item id for that type of item, or if .nothing is passed, a new story is created from a generic draft.

If an Item or item_id is passed in, only published changes or new drafts are taken from the Story Map. If you have a story with unpublished changes, they will not appear when you construct your story with the API. If you start to work on your Story that has unpublished changes and save from the Python API, your unpublished changes on the GUI will be overwritten with your work from the API.

Parameter

Description

item

Optional String or Item. The string for an item id or an item of type ‘Story Map’. If no item is passed, a new story is created and saved to your active portal.

gis

Optional instance of GIS . If none provided the active gis is used.

property actions

Get list of action nodes.

add(content=None, caption=None, alt_text=None, display=None, position=None)

Use this method to add content to your StoryMap. content can be of various class types and when you add this content you can specify a caption, alt_text, display style, and the position at which it will be in your story. Not passing in any content means a separator will be added.

Parameter

Description

content

Optional content of type: Image, Gallery, Video, Audio, Embed, Map, Text, Button, Timeline, Sidecar Swipe, Separator, Code, Table

caption

Optional String. Custom text to caption the webmap.

alt_text

Optional String. Custom text to be used for screen readers.

display

Optional String. How the item will be displayed in the story map.

For Image, Video, Audio, or Map object. Values: “standard” | “wide” | “full” | “float”

For Gallery: Values: “jigsaw” | “square-dynamic”

For Embed: Values: “card” | “inline”

For Swipe: Values: “small” | “medium” | “large”

position

Optional Integer. Indicates the position in which the content will be added. To see all node positions use the node property.

Returns

A String depicting the node id for the content that was added.

new_story = StoryMap()

# Example with Image
>>> image1 = Image("<image-path>.jpg/jpeg/png/gif ")
>>> new_node = new_story.add(image1, position = 2)

# Example with Map
>>> my_map = Map(<item-id of type webmap>)
>>> new_node = new_story.add(my_map, "A map caption", "A new map alt-text")

# Example to add a Separator
>>> new_node = new_story.add()

>>> print(new_story.nodes)
property content_list

Get a list of all the content instances in order of appearance in the story. This returns a list of class instances for the content in the story.

copy_content(target_story, node_list)

Copy the content from one story to another. This will copy the content indicated to the target story in the order they are provided. To change the order once the nodes are copied, use the move() method on the target story.

Note

Do not forget to save the target story once you are done copying and making any further edits.

Note

This method can take time depending on the number of resources. Each resource coming from a file must be copied over and heavy files, such as videos or audio, can be time consuming.

Parameter

Description

target_story

Required StoryMap instance. The target story that the content will be copied to.

node_list

Required list of strings. The list of node ids indicating the content that will be copied to the target story.

Returns

True if all nodes have been successfully copied over.

cover(title=None, type=None, summary=None, by_line=None, image=None)

A story’s cover is at the top of the story and always the first node. This method allows the cover to be edited by updating the title, byline, image, and more. Changing one part of the story cover will not change the rest of the story cover. If just the image is passed in then only the image will change.

Note

To change the date seen on the story cover, use the cover_date property.

Parameter

Description

title

Optional string. The title of the StoryMap cover.

type

Optional string. The type of story cover to be used in the story.

Values: "full" | "sidebyside" | "minimal"

summary

Optional string. The description of the story.

by_line

Optional string. Crediting the author(s).

image

Optional url or file path or Image object. The cover image for the story cover.

Returns

Dictionary representation of the story cover node.

story = StoryMap(<story item>)
story.cover(title="My Story Title", type="minimal", summary="My little summary", by_line="python_dev")
story.save()
property cover_date

Get/Set the date type shown on the story cover.

Parameter

Description

date_type

Optional String. Set the desired date type for the story cover.

Values: "first-published" | "last-published" | "none"

credits(content=None, attribution=None, heading=None, description=None)

Credits are found at the end of the story and thus are always the last node.

To create a credit, add the text that should be shown on each side of the divider. content represents the text seen on the left side and attribution is in line with content on the right side of the divider. (i.e. ‘content’ | ‘attribution’)

Adding content and attribution will add a new line to the credits and will not change previous credits.

Adding heading and description will change what is currently in place.

Parameter

Description

content

Optional String. The content to be added. (Seen on the left side of the credits.)

Make sure text has ‘<strong> </strong>’ tags. Adds to the existing credits.

attribution

Optional String. The attribution to be added. (Seen on right side of the credits.) Adds to the existing credits.

heading

Optional String. Replace current heading for credits.

description

Optional String. Replace current description for credits.

Returns

A list of strings that are the node ids for the text nodes that belong to credits.

#Example
>>> story = StoryMap()
>>> story.credits("Python Dev" , "Python API Team", "Thank You", "A big thank you to those who contributed")
delete_story()

Deletes the story item.

duplicate(title=None)

Duplicate the story. All items will be duplicated as they are. This allows you to create a story template and duplicate it when you want to work with it.

It is highly recommended that once the duplicate is created, open it in Story Maps builder to ensure the issue checker finds any issues before editing.

Note

Can be used with ArcGIS Online or with ArcGIS Enterprise starting 10.8.1

Parameter

Description

title

Optional string. The title of the duplicated story. Only available for ArcGISOnline.

Returns

The Item that was created.

# Example for ArcGIS Online
>>> story = StoryMap(<story item>)
>>> story.duplicate("A Story Copy")

# Example for ArcGIS Enterprise
>>> story = StoryMap(<story item>)
>>> story.duplicate()
get(node=None, type=None)

Deprecated since version 2.2.0: Removed in: 3.0.0. get method has been deprecated, use content_list property instead.

Get node(s) by type or by their id. Using this function will help grab a specific node from the story if a node id is provided. Set this to a variable and this way edits can be made on the node in the story.

Parameter

Description

node

Optional string. The node id for the node that should be returned. This will return the class of the node if of type story content.

type

Optional string. The type of nodes that user wants returned. If none specified, list of all nodes returned.

Values: image | video | audio | embed | webmap | text | button | separator | expressmap | webscene | immersive | code

Returns

If type specified: List of node ids and their types in order of appearance in the story map.

If node_id specified: The node itself.

>>> story = StoryMap(<story item>)

# Example get by type
>>> story.get(type = "text")
Returns a list of all nodes of type text

# Example by id
>>> text = story.get(node= "<id for text node>")
>>> text.properties
Returns a specific node of type text
move(node_id, position=None, delete_current=False)

Move a node to another position. The node currently at that position will be moved down one space. The node at the current position can be deleted instead of moved if delete_current is set to True.

Parameter

Description

node_id

Required String. The node id for the content that will be moved. Find a list of node order by using the nodes property.

position

Optional Integer. Indicates the position in which the content will be added. If no position is provided, the node will be placed at the end.

delete_current

Optional Boolean. If set to True, the node at the current position will be deleted instead of moved down one space. Default is False.

new_story = StoryMap()

# Example with Image
>>> image1 = Image("<image-path>.jpg/jpeg/png/gif")
>>> image2 = Image("<image-path>.jpg/jpeg/png/gif")
>>> new_node = new_story.add(image1, "my caption", "my alt-text", "float", 2)
>>> new_story.add(image2)
>>> new_story.move(new_node, 3, False)
navigation(nodes=None, hidden=None)

Story navigation is a way for authors to add headings as links to allow readers to navigate between different sections of a story. The story navigation node takes TextStyle.HEADING text styles as its only allowed children. You can only have 30 Text child nodes as visible and act as links within a story.

The text nodes must already exist in the story. Pass the list of node ids for the heading text nodes to assign them to the navigation.

Parameter

Description

nodes

Optional list of nodes to include in the navigation. These nodes can only be of style heading (“h2”). Include in order. This will override current list and order.

To see current list use navigation_list property.

hidden

Optional boolean. If True, the navigation is hidden.

Returns

List of nodes in the navigation.

#Example
>>> story = StoryMap("<existing story id>")
>>> story.navigation_list

>>> story.navigation(["<header node id>", "<header node id>"], False)
property navigation_list

Get a list of the nodes that are linked in the navigation.

nodes

Deprecated since version 2.2.0: Removed in: 3.0.0. nodes property has been deprecated, use content_list property instead.

Get main nodes in order of appearance in the story. This will return a list of dictionaries specifying the node ids and the class content they correspond to. If there is no class for the content, a string is returned with the content type.

property properties

This property returns the storymap’s JSON.

save(title=None, tags=None, access=None, publish=False)

This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.

The title only needs to be specified if a change is wanted, otherwise existing title is used.

Warning

Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.

Warning

Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.

Parameter

Description

title

Optional string. The title of the StoryMap.

tags

Optional string. The tags of the StoryMap.

access

Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.

Values: private | org | public

publish

Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.

Returns

The Item that was saved to your active GIS.

show(width=None, height=None)

Show a preview of the story. The default is a width of 700 and height of 300.

Parameter

Description

width

Optional integer. The desired width to show the preview.

height

Optional integer. The desired height to show the preview.

Returns

An Iframe display of the story map if possible, else the item url is returned to be clicked on.

property story_locale

Get/Set the locale and language of the story.

If your story was created with the Python API then the default is “en-US”

theme(theme=<Themes.SUMMIT: 'summit'>)

Each story has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.

Parameter

Description

theme

Required Themes Style or custom theme item id. The theme to set the story to.

Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>

>>> from arcgis.apps.storymap import Themes

>>> story = StoryMap()
>>> story.theme(Themes.TIDAL)

Image

class arcgis.apps.storymap.story_content.Image(path=None, **kwargs)

Bases: object

Class representing an image from a url or file.

Warning

Image must be smaller than 10 MB to avoid having issues when saving or publishing.

Note

Once you create an Image instance you must add it to the story to be able to edit it further.

Parameter

Description

path

Required String. The file path or url to the image that will be added.

property alt_text

Get/Set the alternate text property for the image.

Parameter

Description

alt_text

String. The new alt_text for the Image.

Returns

The alternate text that is being used.

property caption

Get/Set the caption property for the image.

Parameter

Description

caption

String. The new caption for the Image.

Returns

The caption that is being used.

delete()

Delete the node

Returns

True if successful.

property display

Get/Set display for image.

Values: small | wide | full | float

property image

Get/Set the image property.

Parameter

Description

image

String. The new image path or url for the Image.

Returns

The image that is being used.

property properties

Get properties for the Image.

Returns

A dictionary depicting the node dictionary and resource dictionary for the image. If nothing is returned, make sure your content has been added to the story.

Video

class arcgis.apps.storymap.story_content.Video(path=None, **kwargs)

Bases: object

Class representing a video from a url or file

Note

Once you create a Video instance you must add it to the story to be able to edit it further.

Parameter

Description

path

Required String. The file path or embed url to the video that will be added.

Note

URL must be an embed url. Example: “https://www.youtube.com/embed/G6b7Kgvd0iA

property alt_text

Get/Set the alternate text property for the video.

Parameter

Description

alt_text

String. The new alt_text for the Video.

Returns

The alternate text that is being used.

property caption

Get/Set the caption property for the video.

Parameter

Description

caption

String. The new caption for the Video.

Returns

The caption that is being used.

delete()

Delete the node

Returns

True if successful

property display

Get/Set display for the video.

Values: small | wide | full | float

Note

Cannot change display when video is created from a url

property properties

Get properties for the Video.

Returns

A dictionary depicting the node dictionary and resource dictionary for the video. If nothing is returned, make sure the content is part of the story.

Note

To change various properties of the Video use the other property setters.

property video

Get/Set the video property.

Parameter

Description

video

String. The new video path for the Video.

Returns

The video that is being used.

Audio

class arcgis.apps.storymap.story_content.Audio(path=None, **kwargs)

Bases: object

This class represents content that is of type audio. It can be created from a file path and added to the story.

Note

Once you create an Audio instance you must add it to the story to be able to edit it further.

Parameter

Description

path

Required String. The file path to the audio that will be added.

property alt_text

Get/Set the alternate text property for the audio.

Parameter

Description

alt_text

String. The new alt_text for the Audio.

Returns

The alternate text that is being used.

property audio

Get/Set the audio path.

Parameter

Description

audio

String. The new audio path for the Audio.

Returns

The audio that is being used.

property caption

Get/Set the caption property for the audio.

Parameter

Description

caption

String. The new caption for the Audio.

Returns

The caption that is being used.

delete()

Delete the node

Returns

True if successful

property display

Get/Set display for audio.

Values: small | wide | float`

property properties

Get properties for the Audio.

Returns

A dictionary depicting the node dictionary and resource dictionary for the audio.

If nothing is returned, make sure the content is part of the story.

Embed

class arcgis.apps.storymap.story_content.Embed(path=None, **kwargs)

Bases: object

Class representing a webpage or embedded audio. Embed will show as a card in the story.

Note

Once you create an Embed instance you must add it to the story to be able to edit it further.

Parameter

Description

path

Required String. The url that will be added as a webpage, video, or audio embed into the story.

property alt_text

Get/Set the alternate text property for the embed.

Parameter

Description

alt_text

String. The new alt_text for the Embed.

Returns

The alternate text that is being used.

property caption

Get/Set the caption property for the webpage.

Parameter

Description

caption

String. The new caption for the Embed.

Returns

The caption that is being used.

delete()

Delete the node

Returns

True if successful.

property display

Get/Set display for embed.

Values: card | inline

Get/Set the link property.

Parameter

Description

link

String. The new url for the Embed.

Returns

The embed that is being used.

property offline_media

Get/Set the offline media property for the embed.

Parameter

Description

offline_media

Image or Video. The new offline_media for the Embed.

Returns

The offline media that is being used.

property properties

Get properties for the Embed.

Note

To change various properties of the Embed use the other property setters.

Returns

A dictionary depicting the node dictionary for the embed. If nothing is returned, make sure the content is part of the story.

Map

class arcgis.apps.storymap.story_content.Map(item=None, **kwargs)

Bases: object

Class representing a webmap or webscene for the story

Note

Once you create a Map instance you must add it to the story to be able to edit it further.

Parameter

Description

item

An Item of type WebMap or WebScene or a String representing the item id to add to the story map.

property alt_text

Get/Set the alternate text property for the map.

Parameter

Description

alt_text

String. The new alt_text for the Map.

Returns

The alternate text that is being used.

property caption

Get/Set the caption property for the map.

Parameter

Description

caption

String. The new caption for the Map.

Returns

The caption that is being used.

delete()

Delete the node

property display

Get/Set the display type of the map.

Values: standard | wide | full | float right | float left

property legend_pinned

Get/Set the legend pinned toggle. True if enabled and False if disabled.

Note

If set to True, make sure show_legend is also True. Otherwise, you will not see the legend pinned.

property map

Get/Set the map property.

Parameter

Description

map

One of three choices:

  • String being an item id for an Item of type

WebMap or WebScene.

WebMap or WebScene.

Note

Only replace a Map with a new map of same type. Cannot replace a 2D map with 3D.

Returns

The item id for the map that is being used.

property offline_media

Get/Set the offline media. This is an alternative version of this media for offline viewing using the ArcGIS StoryMaps Briefings app.

Note

This property is only available for ArcGIS StoryMaps Briefings and the map must be part of the Briefing before setting this property.

Parameter

Description

offline_media

The new offline media for the Map or Scene. This can either be the item of a Mobile Map Package or Mobile Scene Package or it can be an item of type Image or Video from Story Contents.

property properties

Get properties for the Map.

Returns

A dictionary depicting the node dictionary and resource dictionary for the map. The resource dictionary depicts the original map settings. The node dictionary depicts the current map settings. If nothing it returned, make sure the content is part of the story.

Note

To change various properties of the Map use the other property setters.

set_viewpoint(extent=None, scale=None)

Set the extent and/or scale for the map in the story.

If you have an extent to use from a bookmark, find this extent by using the bookmarks property in the WebMap Class. The map property on this class will return the Web Map Item being used. By passing this item into the WebMap Class you can retrieve a list of all bookmarks and their extents with the bookmarks property.

To see the current viewpoint call the properties property on the Map node.

Parameter

Description

extent

Optional dictionary representing the extent of the map. This will update the extent, center and viewpoint accordingly.

Example:
{‘spatialReference’: {‘latestWkid’: 3857, ‘wkid’: 102100},
‘xmin’: -609354.6306080809,
‘ymin’: 2885721.2797636474,
‘xmax’: 6068184.160383142,
‘ymax’: 6642754.094035632}

scale

Optional Scales enum class value or dict with ‘scale’ and ‘zoom’ keys.

Scale is a unit-less way of describing how any distance on the map translates to a real-world distance. For example, a map at a 1:24,000 scale communicates that 1 unit on the screen represents 24,000 of the same unit in the real world. So one inch on the screen represents 24,000 inches in the real world.

Returns

The current viewpoint dictionary

property show_legend

Get/Set the showing legend toggle. True if enabled and False if disabled

Get/Set the search toggle. True if enabled and False if disabled

property time_slider

Get/Set the time slider toggle. True if enabled and False if disabled

Text

class arcgis.apps.storymap.story_content.Text(text=None, style=<TextStyles.PARAGRAPH: 'paragraph'>, color=None, size=None, **kwargs)

Bases: object

Class representing a text and a style of text.

Note

Once you create a Text instance you must add it to the story to be able to edit it further.

Properties of the different text types:

Type

Text

paragraph

String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags

Values: themeColor1 | themeColor2 | themeColor3 | customTextColors

heading

String can only contain <em> tag

subheading

String can only contain <em> tag

bullet-list

String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags

Values: themeColor1 | themeColor2 | themeColor3 | customTextColors

numbered-list

String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags

Values: themeColor1 | themeColor2 | themeColor3 | customTextColors

quote

String can only contain <strong> and <em> tags

add_attachment(content, text=None)

Add a text action to your text. You can specify the data of the action. This can only be used within a Briefing

Parameter

Description

content

Required content that can be added as an attachment. Content can be: * An Item object of type: Web Map, Image, StoryMap, Collection, Dashboard, Web Experience, or other arcgis Apps. * A story content of type Image or Video

text

Optional String. The part of the text that the attachment will be linked to. The text must already exist in the text node.

For example, if the entire text is “Look at this dog.” and you want to link the word “dog” to the attachment, then the text parameter would be “dog”.

Returns

True if successful.

delete()

Delete the node

Returns

True if successful.

property properties

Get the properties for the text.

Returns

The Text dictionary for the node. If nothing is returned, make sure the content is part of the story.

remove_attachment(text=None)

Remove an attachment from the text. If text_to_remove is None, remove all attachments. This can only be used within a Briefing.

Parameter

Description

text

Optional String. The part of the text that the attachment will be removed from. The text must already exist in the text class. If text is None, then all attachments will be removed.

Returns

True if successful.

property size

Get/Set the size for the text node.

Parameter

Description

size

Optional String. The new size to be displayed. Applicable for Paragraph, Bullet List, and Numbered List.

Values: small | medium | large

Note

“small” can only be used in a Briefing.

Returns

The size for the node. If nothing is returned, make sure the content is part of the story.

property text

Get/Set the text itself for the text node.

Parameter

Description

text

Optional String. The new text to be displayed.

Returns

The text for the node. If nothing is returned, make sure the content is part of the story.

Button

class arcgis.apps.storymap.story_content.Button(link=None, text=None, **kwargs)

Bases: object

Class representing a button.

Note

Once you create a Button instance you must add it to the story to be able to edit it further.

Parameter

Description

link

Required String. When user clicks on button, they will be brought to the link.

text

Required String. The text that shows on the button.

delete()

Delete the node

Get/Set the link for the button.

Parameter

Description

link

Optional String. The new path for the button.

Returns

The link being used. If nothing is returned, make sure the content is part of the story.

property properties

Get the properties for the button.

Returns

The Button dictionary for the node. If nothing is returned, make sure the content is part of the story.

property text

Get/Set the text for the button.

Parameter

Description

text

Optional String. The new text to be displayed.

Returns

The text for the node. If nothing is returned, make sure the content is part of the story.

Swipe

class arcgis.apps.storymap.story_content.Swipe(**kwargs)

Bases: object

Create a Swipe node.

Note

Once you create a Swipe instance you must add it to the story to be able to edit it further.

Parameter

Description

node_id

Required String. The node id for the swipe type.

story

Required StoryMap that the swipe belongs to.

>>> my_story.nodes #use to find swipe node id

# Method 1: Use the Swipe Class
>>> swipe = Swipe()

# Method 2: Use the get method in story
>>> swipe = my_story.get(node = <node_id>)
property alt_text

Get/Set the alternate text property for the swipe.

Parameter

Description

alt_text

String. The new alt_text for the Swipe.

Returns

The alternate text that is being used.

property caption

Get/Set the caption property for the swipe.

Parameter

Description

caption

String. The new caption for the Swipe.

Returns

The caption that is being used.

delete()

Delete the node

Returns

True if successful.

edit(content=None, position='right')

Edit the media content of a Swipe item. To save your edits and see them in the StoryMap’s builder, make sure to save the story.

Use this method to add new content if your swipe is empty. You can specify the content to add and which side of the swipe it should be on.

Parameter

Description

content

Required story content of type: Image or Map. Must be the same media type on both panels.

position

Optional String. Either “right” or “left”. Default is “right” so content will be added to right panel.

Returns

True if successful

property properties

Get properties of the Swipe object

Returns

A dictionary depicting the node in the story.

Sidecar

class arcgis.apps.storymap.story_content.Sidecar(style=None, **kwargs)

Bases: object

Create an Sidecar immersive object.

A sidecar is composed of slides. Slides are composed of two sub structures: a narrative panel and a media panel. The media node can be a(n): Image, Video, Embed, Map, or Swipe. The narrative panel can contain multiple types of content including Image, Video, Embed, Button, Text, Map, and more.

Note

Once you create a Sidecar instance you must add it to the story to be able to edit it further.

Parameter

Description

style

Optional string that depicts the sidecar style. Values: ‘floating-panel’ | ‘docked-panel’ | ‘slideshow’

>>> my_story.nodes #use to find sidecar node id

# Method 1: Use the Sidecar Class
>>> sidecar = Sidecar("floating-panel") # create from scratch

# Method 2: Use the get method in story
>>> sidecar = my_story.content_list()[3] # sidecar is fourth item in story
add_action(slide_number, text, viewpoint, extent=None, map_layers=None)

Add a map action button to a slide. You can specify the data of the action.

Parameter

Description

slide_number

Required Integer. The slide that the map action will be added to. First slide is 1.

text

Required String. The map action button text

viewpoint

Required Dictionary. The viewpoint to be set. The minimum keys to include are an x and y center point in the target geometry.

Example:
viewpoint = {

“rotation”: 0, “scale”: 18055.954822, “targetGeometry”: {

“spatialReference”: {

“latestWkid”: 3857, “wkid”: 102100

}, “x”: -8723429.856341356, “y”: 4019095.847955684

}

}

extent

Optional Dictionary. The extent of the map that will be shown when the action button is used.

Example:
extent = {
“spatialReference”: {

“latestWkid”: 3857, “wkid”: 102100

}, “xmin”: -8839182.968379805, “ymin”: 3907027.5240857545, “xmax”: -8824335.075635428, “ymax”: 3915378.269425899

}

map_layers

Optional list of dictionaries. Each dictionary represents a map layer and the parameters set on the map layer.

Example:
map_layers = [
{

“id”: “18511776c33-layer-2”, “title”: “USA Forest Type”, “visible”: true

}

]

Returns

The node id for the action that was added to the slide

add_slide(contents=None, media=None, slide_number=None)

Add a slide to the sidecar. You are able to specify the position of the slide, the content of the narrative panel and the media of the slide.

Parameter

Description

contents

Optional list of story content item(s). The instances of story content that will be added to the narrative panel such as Text, Image, Embed, etc.

media

Optional item that is a story content item. Item type for the media node can be: Image, Video, Map, Embed, or Swipe.

slide_number

Optional Integer. The position at which the new slide will be. If none is provided then it will be added as the last slide.

First slide is 1.

# Get sidecar from story and see the properties
sc = story.get(<sidecar_node_id>)
sc.properties
>> returns a dictionary structure of the sidecar

# create the content we will add to narrative_panel_nodes parameter
im = Image(<img_url_or_path>)
txt = Text("Hello World")
embed = Embed(<url>)
narrative_nodes = [im, txt, embed]

mmap = Map(<item_id webmap>)

# Add new slide with the content:
sc.add_slide(narrative_nodes, mmap, 4)
>> New slide added with the content at position 4
property content_list

Get a list of all the content within the sidecar in order of appearance. The content will be displayed in the following order: A list of the content in slide 1, a list of the content in slide 2, etc. Each sub-list will contain content found in the narrative panel, if any, and the media content, if any.

delete()

Delete the node

Returns

True if successful.

edit(content, slide_number)

Edit method can be used to edit the type of media in a slide of the Sidecar. This is done by specifying the slide number and the media content to be added. The media can only be of type: Image, Video, Map, or Embed.

Note

This method should not be used to edit the narrative panel of the Sidecar. To better edit both the media and the narrative panel, it is recommended to use the get() method in the Sidecar class. The get method can be used to change media if the content is of the same type as what is currently present and preserve the node_id.

Parameter

Description

content

Required item that is a story content item. Item type for the media node can be: Image, Video, Map Embed, Swipe

slide_number

Required Integer. The slide that will be edited. First slide is 1.

# Get sidecar from story and see the properties
sc = story.get(<sidecar_node_id>)
sc.properties
>> returns a dictionary structure of the sidecar

# If a slide 2 contains a map and you want to change it to an image
im = Image(<img_url_or_path>)
sc.edit(im, 2)
sc.properties
>> notice slide 2 now has an image

# If I want to update the image then 2 methods:
# OPTION 1
im2 = Image(<img_url_or_path>)
sc.edit(im2, 2)

# OPTION 2 (only applicable if content is of same type as existing)
im2 = sc.get(im.node_id)
im2.image = <img_url_or_path>
get(node_id)

The get method is used to get the node that will be edited. Use sidecar.properties to find all nodes associated with the sidecar.

Parameter

Description

node_id

Required String. The node id for the content that will be returned.

Returns

An class instance of the node type.

# Find the nodes associated with the sidecar
sc = story.get(<sidecar_node_id>)
sc.properties
>> returns a dictionary structure of the sidecar

# Get a node associated with the sidecar, in this example an image, and change the image
im = sc.get(<node_id>)
im.image = <new_image_path>

# Save the story to see changes applied in Story Map builder
story.save()
property properties

List all slides and their children for a Sidecar node.

Returns

A list where the first item is the node id for the sidecar. Next items are slides with the dictionary their children.

remove_slide(slide)

Remove a slide from the sidecar.

Parameter

Description

slide

Required String. The node id for the slide that will be removed.

Timeline

class arcgis.apps.storymap.story_content.Timeline(style=None, **kwargs)

Bases: object

Create a Timeline object from a pre-existing timeline node.

A timeline is composed of events. Events are composed of maximum three nodes: an image, a sub-heading text, and a paragraph text.

Note

Once you create a Timeline instance you must add it to the story to be able to edit it further.

Parameter

Description

style

Required string, the style type of the timeline. If the timeline will be added to a Sidecar, then only waterfall and single-sided are allowed.

Values: ‘waterfall’ | ‘single-side’ | ‘condensed’

>>> my_story.nodes #use to find timeline node id

# Method 1: Use the Timeline Class
>>> timeline = Timeline(my_story, <node_id>)

# Method 2: Use the get method in story
>>> timeline = my_story.get(node = <node_id>)
add_event(contents=None, position=None)

Add event or spacer to the timeline.

Parameter

Description

contents

Optional item list that will be in the event. Need to be passed in by order of appearance. Item type can be Image or Text .

Text can only be of style TextStyles.SUBHEADING or TextStyles.PARAGRAPH

Note

To create timeline spacer, do not pass in any value for this parameter.

position

Optional Integer. The position at which the even will be added. First event is 1. If None, then the event will be added to the end.

delete()

Delete the node

Returns

True if successful.

edit(content, event)

Edit event text or image content. To add a new event use the add_event method.

Parameter

Description

content

Required content to replace current content. Item type can be Image or Text .

Text can only be of style TextStyles.SUBHEADING or TextStyles.PARAGRAPH

event

Required Integer. The event that will be edited. First event is 1.

property properties

List all events and their children

Returns

A list where the first item is the node id for the timeline. Next items are dictionary of events and their children.

remove_event(event)

Remove an event from the timeline.

Parameter

Description

event

Required String. The node id for the timeline event that will be removed.

property style

Get/Set the style of the timeline

Values: waterfall | single-slide | condensed

MapTour

class arcgis.apps.storymap.story_content.MapTour(**kwargs)

Bases: object

Create a MapTour object from a pre-existing maptour node.

Note

Once you create a MapTour instance you must add it to the story to be able to edit it further.

>>> my_story.nodes #use to find map tour node id

# Method 1: Use the MapTour Class
>>> maptour = MapTour(my_story, <node_id>)

# Method 2: Use the get method in story
>>> maptour = my_story.get(node = <node_id>)
get(node_id)

The get method is used to get the node that will be edited. Use maptour.properties to find all nodes associated with the sidecar.

Parameter

Description

node_id

Required String. The node id for the content that will be returned.

Returns

An class instance of the node type.

# Find the nodes associated with the map tour
mt = story.get(<maptour_node_id>)
mt.places
>> returns places of the map tour

# Get a node associated with the map tour, in this example an image, and change the image
im = mt.get(<node_id>)
im.image = <new_image_path>

# Save the story to see changes applied in Story Map builder
story.save()
property places

List all places on the map

property style

Get the type and subtype of the map tour

Code

class arcgis.apps.storymap.story_content.Code(content=None, language=None, **kwargs)

Bases: object

Class representing a code content card. Code will show as a block of code in your Storymap.

Note

Once you create a Code instance you must add it to the story to be able to edit it further.

Parameter

Description

content

Required String. The code content to have in the block.

language

Required Language or String. The coding language of the content provided. For values see Language Enum Class.

property content

Get/Set the content property.

Parameter

Description

content

String. The new content for the code block.

Returns

The content that is being used.

delete()

Delete the node

Returns

True if successful.

property language

Get/Set the language property.

Parameter

Description

language

Language value. The new language for the code block.

Returns

The language that is being used.

property line_number

Get/Set whether line number property is set.

Parameter

Description

enabled

Bool. Set to True if you want line numbers, False otherwise.

Returns

True if line numbers are enabled and False if not.

Briefing

class arcgis.apps.storymap.briefing.Briefing(item=None, gis=None)

Bases: object

Synthesize critical information and maintain mission readiness with briefings, a new slide-based presentation style now available as a type of ArcGIS StoryMap. Make data-driven decisions and provide meaningful context to your audience by infusing your presentations with real-time data and dynamic maps. Briefings also allow you to unify images, videos, and other multimedia in your presentation to create a cohesive experience for both you and your viewers.

Example use cases include on-the-ground disaster briefings, budget numbers presented in real-time, and daily leadership briefings. After the briefings mobile app launches in September, you’ll be able to securely connect with your stakeholders wherever they are with a tablet app that works on- and offline.

Create a StoryMap Briefing object to make edits to a story. Can be created from an item of type ‘StoryMap Briefing’, an item id for that type of item, or if nothing is passed, a new story is created from a generic draft.

If an Item or item_id is passed in, only published changes or new drafts are taken from the StoryMap Briefing. If you have a story with unpublished changes, they will not appear when you construct your story with the API. If you start to work on your Briefing that has unpublished changes and save from the Python API, your unpublished changes on the GUI will be overwritten with your work from the API.

Parameter

Description

item

Optional String or Item. The string for an item id or an item of type ‘StoryMap Briefing’. If no item is passed, a new story is created and saved to your active portal.

gis

Optional instance of GIS . If none provided the active gis is used.

property actions

Get list of action nodes. These are nodes that trigger an action to occur, for example when text is linked to an image, map, etc.

add(layout, *, sublayout=None, title=None, subtitle=None, section_position=None, position=None)

Use this method to add content to your StoryMap. content can be of various class types and when you add this content you can specify a caption, alt_text, display style, and the position at which it will be in your story. Not passing in any content means a separator will be added.

Parameter

Description

layout

Required LayoutType or string, the layout type of the slide.

sublayout

Optional SubLayoutType or string, the sublayout type of the slide. Only applicable when the layout is “double” or “titleless-double”.

title

Optional string or Text object, the title of the slide. Text can only be of type heading (h2).

subtitle

Optional string or Text object, the subtitle of the slide. Text can only be of type paragraph.

section_position

Optional string, the title panel position of the section slide. Only applicable for “section-double”. Values: ‘start’ | ‘end’

position

Optional Integer. Indicates the position in which the slide will be added. If no position is provided, the slide will be placed at the end.

Returns

The new slide that was added to the story

copy_content(target_briefing, content)

Copy the content from one briefing to another. This will copy the content indicated to the target briefing in the order they are provided.

Note

Do not forget to save the target briefing once you are done copying and making any further edits.

Note

This method can take time depending on the number of resources. Each resource coming from a file must be copied over and heavy files, such as videos or audio, can be time consuming.

Parameter

Description

target_briefing

Required Briefing instance. The target briefing that the content will be copied to.

content

Required list of content. The list of content that will be copied to the target briefing.

Returns

True if all content has been successfully copied over.

cover(title=None, type=None, summary=None, by_line=None, media=None)

A briefing’s cover is the first slide. This method allows the cover to be edited by updating the title, byline, media, and more. Changing one part of the briefing cover will not change the rest of the cover. If just the media is passed in then only the media will change.

Parameter

Description

title

Optional string. The title of the Briefing cover.

type

Optional string. The type of briefing cover to be used in the story.

Values: "full" | "sidebyside" | "minimal"

summary

Optional string. The description of the story.

by_line

Optional string. Crediting the author(s).

media

Optional url or file path or Image or Video object.

Returns

True if the cover was updated successfully.

briefing = Briefing(<briefing item>)
briefing.cover(title="My Briefing Title", type="sidebyside", summary="My little summary", by_line="python_dev")
briefing.save()
delete_briefing()

Deletes the briefing item.

duplicate(title=None)

Duplicate the story. All items will be duplicated as they are. This allows you to create a briefing template and duplicate it when you want to work with it.

It is highly recommended that once the duplicate is created, open it in StoryMap Briefing builder to ensure the issue checker finds any issues before editing.

Note

Can be used with ArcGIS Online or with ArcGIS Enterprise starting 10.8.1.

Note

To duplicate into another organization, use the clone_items() method.

Parameter

Description

title

Optional string. The title of the duplicated story. Only available for ArcGIS Online.

Returns

The Item that was created.

# Example for ArcGIS Online
>>> briefing = Briefing(<briefing item>)
>>> briefing.duplicate("A Briefing Copy")
move(slide, position=None, delete_current=False)

Move a slide to another position. The slide currently at that position will be moved down one space. The slide at the current position can be deleted instead of moved if delete_current is set to True.

Parameter

Description

slide

Required integer. The slide number to move. The cover is slide 0 and this cannot be moved.

position

Optional Integer. Indicates the position in which the slide will be added. If no position is provided, the slide will be placed at the end.

delete_current

Optional Boolean. If set to True, the slide at the current position will be deleted instead of moved down one space. Default is False.

Returns

True if the slide was moved successfully.

save(title=None, tags=None, access=None, publish=False)

This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.

The title only needs to be specified if a change is wanted, otherwise existing title is used.

Warning

Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.

Warning

Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.

Parameter

Description

title

Optional string. The title of the StoryMap.

tags

Optional string. The tags of the StoryMap.

access

Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.

Values: private | org | public

publish

Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.

Returns

The Item that was saved to your active GIS.

show(width=None, height=None)

Show a preview of the briefing. The default is a width of 700 and height of 300.

Parameter

Description

width

Optional integer. The desired width to show the preview.

height

Optional integer. The desired height to show the preview.

Returns

An Iframe display of the briefing if possible, else the item url is returned to be clicked on.

property slides

Get a list of all the content instances in order of appearance in the story. This returns a list of class instances for the content in the story.

theme(theme=<Themes.SUMMIT: 'summit'>)

Each briefing has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.

Parameter

Description

theme

Required Themes Style or custom theme item id. The theme to set on the briefing.

Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>

>>> from arcgis.apps.storymap import Themes, Briefing

>>> briefing = Briefing()
>>> briefing.theme(Themes.TIDAL)

Block

class arcgis.apps.storymap.story_content.Block(block_index, slide, story)

Bases: object

Represents a block in a briefing slide.

Note

Blocks are automatically created when you create a new slide. You can access the blocks through the blocks property of the slide. Do not create this class directly.

add_content(content)

Add content to the block.

Parameter

Description

content

Required content object to be added to the block. The content object can be of type Text, Image, Video, Embed, Map, or Swipe. There can be more than one Text contents in the same block but only one of the other types of content. Setting an Image, Video, Embed, Map, or Swipe content will overwrite the current content. Setting a Text content will add the text to the block.

Returns

The Content object that was added to the block.

property content

Get the contents of the block. This will return a list of the content objects in the block. The content objects can be of type Text, Image, Map, etc.

Returns

A list of content objects in the block.

delete_content(index=None)

Delete content from the block.

Parameter

Description

index

Optional integer, the index of the content to be deleted. If not specified, all content will be deleted.

Returns

True if successful.

Table

class arcgis.apps.storymap.story_content.Table(rows=None, columns=None, **kwargs)

Bases: object

Class representing a table block. Table will show as a gridded table in your Storymap.

Note

Once you create a Table instance you must add it to the story to be able to edit it further.

Parameter

Description

rows

Optional int. The number of rows in the table. Table supports a maximum of 10 rows. Minimum of 2 rows supported.

columns

Optional int. The number of columns in the table. Table supports a maximum of 8 columns. Minimum of 1 column supported.

property content

Get the content of the table as a panda’s DataFrame. Each cell content is held within a dictionary where the ‘value’ key is the text of the cell. The other key that can be included in the dictionary is the ‘textAlignment’ key.

Parameter

Description

content

Required pandas DataFrame. The content of the table as a pandas DataFrame. The index of the DataFrame will be the row headers and the columns of the DataFrame will be the column headers.

delete()

Delete the node

Returns

True if successful.

ExpressMap

class arcgis.apps.storymap.story_content.ExpressMap(**kwargs)

Bases: object

Class representing an ExpressMap.

Note

You can only create an ExpressMap from a pre-existing expressmap in a story or briefing. You cannot create an ExpressMap from scratch.

delete()

Delete the map action.

property offline_media

Get/Set the offline media property for the embed.

Parameter

Description

offline_media

Image or Video. The new offline_media for the Embed.

Returns

The offline media that is being used.

Collection

class arcgis.apps.storymap.collection.Collection(item=None, gis=None)

Bases: object

Parameter

Description

item

Optional String or Item. The string for an item id or an item of type ‘StoryMap Collection’. If no item is passed, a new story is created and saved to your active portal.

gis

Optional instance of GIS . If none provided the active gis is used.

add(item, title=None, thumbnail=None, position=None)

Add an item to the collection. Specify this item with the item object. The item can be a portal item, file resource, or a story content of type Image, Video, or Embed.

Parameter

Description

item

Required object. Either an Image, Video, or Embed content type object.

title

Optional string. The title of the item to add under the thumbnail in the collection.

thumbnail

Optional string. The image file path to use as the thumbnail for the item.

position

Optional integer. The position in the collection to add the item. If none is specified, the item is added to the end of the collection.

property content

Returns the content of the collection.

cover(title=None, type=None, summary=None, by_line=None)

A collection’s cover is the first slide. This method allows the cover to be edited by updating the title, byline, media, and more. Changing one part of the collection cover will not change the rest of the cover. If just the media is passed in then only the media will change.

Parameter

Description

title

Optional string. The title of the Collection cover.

type

Optional string. The type of collection cover to be used in the story.

Values: "full" | "sidebyside" | "minimal"

summary

Optional string. The description of the story.

by_line

Optional string. Crediting the author(s).

Returns

True if the cover was updated successfully.

collection = Collection(<collection item>)
collection.cover(title="My Collection Title", type="sidebyside", summary="My little summary", by_line="python_dev")
collection.save()
delete_collection()

Deletes the collection item.

remove(index)

Remove an item from the collection. Specify this item with the index position of the item in the collection. The list of items in the collection can be found by using the content property. The index position is the position of the item in the list.

Parameter

Description

index

Required integer. The index position of the item to remove.

Returns

True if the item was removed successfully.

save(title=None, tags=None, access=None, publish=False)

This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.

The title only needs to be specified if a change is wanted, otherwise exisiting title is used.

Warning

Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.

Warning

Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.

Parameter

Description

title

Optional string. The title of the StoryMap.

tags

Optional string. The tags of the StoryMap.

access

Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.

Values: private | org | public

publish

Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.

Returns

The Item that was saved to your active GIS.

show(width=None, height=None)

Show a preview of the collection. The default is a width of 700 and height of 300.

Parameter

Description

width

Optional integer. The desired width to show the preview.

height

Optional integer. The desired height to show the preview.

Returns

An Iframe display of the collection if possible, else the item url is returned to be clicked on.

theme(theme=<Themes.SUMMIT: 'summit'>)

Each collection has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.

Parameter

Description

theme

Required Themes Style or custom theme item id. The theme to set on the collection.

Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>

>>> from arcgis.apps.storymap import Themes, Collection

>>> collection = Collection()
>>> collection.theme(Themes.TIDAL)

Enumerations

Language

class arcgis.apps.storymap.story_content.Language(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Represents the supported Languages for the Code Content.

ARCADE = 'arcade'
CSHARP = 'cs'
CSS = 'css'
DIFF = 'diff'
HTML = 'html'
JAVA = 'java'
JAVASCRIPT = 'js'
JSON = 'json'
JSX = 'jsx'
KOTLIN = 'kt'
PYTHON = 'py'
R = 'r'
SQL = 'sql'
SVG = 'svg'
SWIFT = 'swift'
TEXT = 'txt'
TSX = 'tsx'
TYPESCRIPT = 'ts'

Scales

class arcgis.apps.storymap.story_content.Scales(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Scale is a unit-less way of describing how any distance on the map translates to a real-world distance. For example, a map at a 1:24,000 scale communicates that 1 unit on the screen represents 24,000 of the same unit in the real world. So one inch on the screen represents 24,000 inches in the real world.

This can be used for methods involving viewpoint in the Map Content.

BUILDING = {'scale': 1250, 'zoom': 18}
BUILDINGS = {'scale': 2500, 'zoom': 17}
CITIES = {'scale': 160000, 'zoom': 11}
CITY = {'scale': 80000, 'zoom': 12}
CONTINENT = {'scale': 50000000, 'zoom': 3}
COUNTIES = {'scale': 1500000, 'zoom': 8}
COUNTRIESLARGE = {'scale': 25000000, 'zoom': 4}
COUNTRIESSMALL = {'scale': 12000000, 'zoom': 5}
COUNTY = {'scale': 750000, 'zoom': 9}
METROPOLITAN = {'scale': 320000, 'zoom': 10}
NEIGHBORHOOD = {'scale': 2000, 'zoom': 14}
PROVINCE = {'scale': 3000000, 'zoom': 7}
PROVINCES = {'scale': 6000000, 'zoom': 6}
ROOM = {'scale': 100, 'zoom': 22}
ROOMS = {'scale': 400, 'zoom': 20}
SMALLBUILDING = {'scale': 800, 'zoom': 19}
STATE = {'scale': 3000000, 'zoom': 7}
STATES = {'scale': 6000000, 'zoom': 6}
STREET = {'scale': 5000, 'zoom': 16}
STREETS = {'scale': 10000, 'zoom': 15}
TOWN = {'scale': 40000, 'zoom': 13}
WORLD = {'scale': 147914382, 'zoom': 2}

TextStyles

class arcgis.apps.storymap.story_content.TextStyles(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Represents the Supported Text Styles for the Text Content. Example: Text(text=”foo”, style=TextStyles.HEADING)

BULLETLIST = 'bullet-list'
HEADING = 'h2'
LARGEPARAGRAPH = 'large-paragraph'
NUMBERLIST = 'numbered-list'
PARAGRAPH = 'paragraph'
QUOTE = 'quote'
SUBHEADING = 'h3'

SlideLayout

class arcgis.apps.storymap.story_content.SlideLayout(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

This depicts the various layout types that can be used for a BriefingSlide.

DOUBLE = 'double'
FULL = 'full'
SECTIONDOUBLE = 'section-double'
SECTIONSINGLE = 'section-single'
SINGLE = 'single'
TITLELESSDOUBLE = 'titleless-double'
TITLELESSSINGLE = 'titleless-single'

SlideSubLayout

class arcgis.apps.storymap.story_content.SlideSubLayout(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Depicts the various subtypes for a BriefingSlide. For example, if the layout type is DOUBLE then the sublayout type can be THREE_SEVEN or SEVEN_THREE or ONE_ONE.

ONE_ONE = '1-1'
SEVEN_THREE = '7-3'
THREE_SEVEN = '3-7'

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.