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.

Argument

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.

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.

Note

Not all story content can be added from scratch. Content such as swipe, sidecar, and timeline can only be edited from pre-existing story content of those types. Please refer to the documentation for each.

Argument

Description

content

Optional content of type: Image, Gallery, Video, Audio, Embed, Map, Text, Button

If none is provided, a separator is added.

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: “small” | “wide” | “full” | “float”

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

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

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, "my caption", "my alt-text", "float", 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", "wide")

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

>>> print(new_story.nodes)
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.

Argument

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

Argument

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.

Argument

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

Argument

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)

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.

Argument

Description

node_id

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"

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.

Argument

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.

Argument

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.

property nodes

Get main nodes in order of appearance in the story.

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

Argument

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.

Argument

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)

Each story has a theme node in it’s 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.

Argument

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.

Argument

Description

path

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

property alt_text

Get/Set the alternte text property for the image.

Argument

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.

Argument

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.

Argument

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

Argument

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 alternte text property for the video.

Argument

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.

Argument

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.

Argument

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.

Argument

Description

path

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

property alt_text

Get/Set the alternte text property for the audio.

Argument

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.

Argument

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.

Argument

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.

Argument

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 alternte text property for the embed.

Argument

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.

Argument

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.

Argument

Description

link

String. The new url for the Embed.

Returns

The embed 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

Argument

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 alternte text property for the map.

Argument

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.

Argument

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"

property map

Get/Set the map property.

Argument

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 Map with a new map of same type.

Returns

The item id for the map that is being used.

property properties

Get properties for the Map.

Returns

A dictionary depicting the node dictionary and resource dictionary for the map. 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.

Text

class arcgis.apps.storymap.story_content.Text(text=None, style=TextStyles.PARAGRAPH, color='000', **kwargs)

Bases: object

Class representing a text and a style of text.

Argument

Description

text

Required String. The text that will be shown in the story.

Example: “Paragraph with <strong>bold</strong>, <em>italic</em> and <a href=”https://www.google.com” rel=”noopener noreferrer” target=”_blank”>hyperlink</a> and a <span class=”sm-text-color-080”>custom color</span>”

Example for a numbered list: “<li>List Item1</li> <li>List Item2</li> <li>List Item3</li>”

style

Optional TextStyles type. There are 7 different styles of text that can be added to a story.

Values: PARAGRAPH | LARGEPARAGRAPH | NUMBERLIST | BULLETLIST | HEADING | SUBHEADING | QUOTE

custom_color

Optional String. The hex color value without the #. Only available when type is either ‘paragraph’, ‘bullet-list’, or ‘numbered-list’.

Ex: custom_color = “080”

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

large-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

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.

property text

Get/Set the text itself for the text node.

Argument

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.

Argument

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.

Argument

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.

Argument

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(story, node)

Bases: object

Create an Swipe object from a pre-existing swipe node.

Argument

Description

node

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(my_story, <node_id>)

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

Get/Set the alternte text property for the swipe.

Argument

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.

Argument

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.

Argument

Description

content

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

position

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

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(story, node)

Bases: object

Create an Sidecar immersive object from a pre-existing immersive node.

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

Argument

Description

node_id

Required String. The node id for the sidecar type.

story

Required StoryMap that the sidecar belongs to.

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

# Method 1: Use the Sidecar Class
>>> sidecar = Sidecar(my_story, <node_id>)

# Method 2: Use the get method in story
>>> sidecar = my_story.get(node = <node_id>)
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.

Argument

Description

content

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

slide_number

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

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.

Argument

Description

node_id

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

Returns

An class instance of the node type.

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.

Argument

Description

slide

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

Timeline

class arcgis.apps.storymap.story_content.Timeline(story, node)

Bases: object

Create an 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.

Argument

Description

node_id

Required String. The node id for the timeline type.

story

Required StoryMap that the timeline belongs to.

>>> 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>)
delete()

Delete the node

Returns

True if successful.

edit(content, event)

Edit event text or image content.

Argument

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.

Argument

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"

arcgis.apps.storymap.storymap module