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` 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: “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)¶

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.

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.

property nodes¶: 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 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 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.

>>> 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 alternte 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 alternte 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 alternte 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 alternte 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 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 alternte 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 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 unitless 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, **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.

Parameter	Description
text	Required String. The text that will be shown in the story. # Usage Example for paragraph: >>> text = Text('''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>''') # Usage Example for numbered list: >>> text = Text("<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.

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 alternte 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 an 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 alternte 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 mulitple 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

Scales¶

class arcgis.apps.storymap.story_content.Scales(value)¶

Bases: enum.Enum

Scale is a unitless 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.

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}¶

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.

Parameter	Description
node_id	Required String. The node id for the map tour type.
story	Required `StoryMap` that the map tour belongs to.

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