arcgis.apps.storymap 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

property link¶

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. An Item of type 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

property show_search¶

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

property link¶

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.

Gallery¶

class arcgis.apps.storymap.story_content.Gallery(**kwargs)¶

Bases: object

Class representing an image gallery

To begin with a new gallery, simply call the class. Once added to the story, you can add up to 12 images.

Note

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

# Images to add to the gallery.
>>> image1 = Image(<url or path>)
>>> image2 = Image(<url or path>)
>>> image3 = Image(<url or path>)

# Create a gallery and add to story before adding images to it.
>>> gallery = Gallery()
>>> my_story.add(gallery)
>>> gallery.add_images([image1, image2, image3])

add_images(images)¶

Parameter	Description
images	Required list of images of type Image.

property alt_text¶

Get/Set the alternate text property for the swipe.

Parameter	Description
alt_text	String. The new alt_text for the Gallery.

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

Returns

The caption that is being used.

delete()¶

Delete the node

Returns

True if successful.

delete_image(image)¶

The delete_image method is used to delete one image from the gallery. To see a list of images used in the gallery, use the images() property.

Parameter	Description
image	Required String. The node id for the image to be removed from the gallery or the Image instance.

Returns

The current list of images in the gallery.

property display¶

Get/Set the display type of the Gallery.

Values: jigsaw | square-dynamic

property images¶

Get/Set list of image nodes in the image gallery. Setting the lists allows the images to be reordered.

Parameter	Description
images	List of node ids for the images in the gallery. Nodes must already be in the gallery and this list will adjust the order of the images. To add new images to the gallery use: Gallery.add_images(images) To delete an image from a gallery use: Gallery.delete_image(node_id)

Returns

A list of node ids in order of image appearance in the gallery. If nothing is returned, make sure the gallery is part of the story.

property properties¶

Get properties of the Gallery object

Returns

A dictionary depicting the node in the story. If nothing is returned, make sure the gallery 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¶