arcgis.apps.mapshowcase module

Bases: object

Initializes an object from existing Map showcase items. These items reference existing maps, layers, and other content for a specific purpose, allowing users to override map extents, cartographic vignettes, thumbnails and other properties from authoritative sources without having to duplicate them.

Provides for programmatic management and editing of Map showcase items. Users can add(), remove(), reorder_showcase_items() and more.

All editing is done on the latest draft state of the Map Showcase. If no draft exists, one is created from the current published state before applying edits. This allows you to make multiple changes in memory and save them all at once, instead of directly modifying the published state with each edit.

Objects of this class cannot be directly created or initialized, but rather must be populated from existing Map Showcase items obtained using the search() or get() methods or by directly providing an existing item ID.

Example: Search for Map Showcase items in ArcGIS Online

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

map_showcase_items = gis.content.search(
    query="*",
    item_type="Map showcase",
    max_items=20
)
map_showcase_item = map_showcase_items[0]
showcase_obj = MapShowcase(
                item=map_showcase_item,
                gis=gis
               )

print(showcase_obj)

Output:

MapShowcase(title='MyShowcase', item_id='847f2b12c0ee4504a32ae04f1d20be94')

Example: Initialize a Map showcase object from an item ID.

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_obj = MapShowcase(
                item="847f2b12c0ee4504a32ae04f1d20be94",
                gis=gis
               )

print(showcase_obj)

Output:

MapShowcase(title='MyShowcase', item_id='847f2b12c0ee4504a32ae04f1d20be94')

add(item: Item | str, title: str | None = None, snippet: str | None = None, description: str | None = None, thumbnail_url: str | None = None, visible: bool = True, index: int | None = None) → bool

Adds an item to the showcase by Item or item id.

The new item is written to draft. If no draft exists, one is created from the current published/root state first.

Parameter	Description
item	Required item, or item ID, to add to the Map Showcase.
title	The title to show for this item in the Map Showcase. If None, the source item’s title will be used.
snippet	The snippet to show for this item in the Map Showcase. If None, the source item’s snippet will be used.
description	The description to show for this item in the Map Showcase. If None, the source item’s description will be used.
thumbnail_url	A custom thumbnail URL to use for this item in the Map Showcase. If None, the source item’s thumbnail will be used.
visible	Whether this item should be visible in the Map Showcase. Defaults to True.
index	The position in the showcase items list to insert this item. If None, the item will be appended to the end of the list.

Returns:

True if the item was successfully added and saved to draft, False otherwise.

Example: Adding an item to a Map Showcase by item ID

from arcgis.gis import GIS
gis = GIS(profile="your_online_profile")

my_showcase_item = gis.content.get("your_map_showcase_item_id")
map_showcase = MapShowcase(my_showcase_item, gis)

item_id = "5a622c777ee64a31ad0a81a8d020f26b"

res = map_showcase.add(
    item=item_id,
    title="Custom API Title for Showcase Item",
    visible=True
)
print("Item added successfully:", res)

Output:

Item added successfully: True

Example: Adding an item to a Map Showcase by Item object

from arcgis.gis import GIS
gis = GIS(profile="your_online_profile")

my_showcase_item = gis.content.get("your_map_showcase_item_id")
map_showcase = MapShowcase(my_showcase_item, gis)

new_item = gis.content.get("5a622c777ee64a31ad0a81a8d020f26b")

success = map_showcase.add(
        item=new_item,
        title="Custom API Item Title for Showcase Item",
        visible=True
)

print("Item added successfully:", success)
print(f"Showcase: {map_showcase.showcase_items}")

Output:

Item added successfully: True
[MapShowcaseItem(title='My Cool Map in Showcase - API demo - API demo', item_id='121360f938104db285153479d2cd758c', visible=True),
 MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True),
 MapShowcaseItem(title='World Hillshade (WGS84) in Showcase', item_id='faceb85dd8a9440e9b50692905558513', visible=True),
 MapShowcaseItem(title='Custom API Item Title for Showcase Item', item_id='5a622c777ee64a31ad0a81a8d020f26b', visible=True)]

Example: Adding an item to a specific position in the Map Showcase

from arcgis.gis import GIS
gis = GIS(profile="your_online_profile")

my_showcase_item = gis.content.get("your_map_showcase_item_id")
map_showcase = MapShowcase(my_showcase_item, gis)

item_id = "5a622c777ee64a31ad0a81a8d020f26b"
index_posn = 0  # insert at the beginning of the list
success = my_showcase.add(
        item=item_id,
        title="Custom Title for Showcase First Item",
        visible=True,
        index=index_posn
)

print(f"Item added successfully at index 0: {success}")
print(f"New order of items in the showcase: {my_showcase.showcase_items}")

Output:

Item added successfully at index 0: True
[MapShowcaseItem(title='Custom Title for Showcase First Item', item_id='5a622c777ee64a31ad0a81a8d020f26b', visible=True),
 MapShowcaseItem(title='My Cool Map in Showcase - API demo - API demo', item_id='121360f938104db285153479d2cd758c', visible=True),
 MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True),
 MapShowcaseItem(title='World Hillshade (WGS84) in Showcase', item_id='faceb85dd8a9440e9b50692905558513', visible=True)]

get_showcase_item(item_id: str | None = None, index: int | None = None) → MapShowcaseItem

Returns a single MapShowcaseItem by item id or list index.

Returns:

A MapShowcaseItem matching the provided key.

remove(item_id: str | None = None, index: int | None = None) → bool

Removes a map by AGOL item id or showcase index.

The removal is written to draft. If no draft exists, one is created from the current published/root state first.

Returns:

True if the item was successfully removed and saved to draft, False otherwise.

reorder_showcase_items(ordered_items: list[MapShowcaseItem]) → None

Reorders showcase entries using the same set of MapShowcaseItems found when calling showcase_items().

Parameter	Description
ordered_items	Required list of MapShowcaseItem objects in the desired order. This must include the same set of MapShowcaseItem objects returned by the latest call to showcase_items(), just in the new order. New or different MapShowcaseItem objects are not allowed.

Returns:

None. The changes are saved to draft.

Example #1: Reversing the order of items in a Map Showcase

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")
my_showcase = MapShowcase(showcase_item, gis)

# get the current items in the showcase
sc_items = my_showcase.showcase_items
sc_items

Output:

[MapShowcaseItem(title='My Cool Map', item_id='121360f938104db285153479d2cd758c', visible=True),
 MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True),
 MapShowcaseItem(title='World Hillshade (WGS84)', item_id='faceb85dd8a9440e9b50692905558513', visible=True)]

Example con’t:

# reverse the order
reversed_sc_items = list(reversed(sc_items))
# save the new order to draft
my_showcase.reorder_showcase_items(reversed_sc_items)
my_showcase.showcase_items

Output:

[MapShowcaseItem(title='World Hillshade (WGS84)', item_id='faceb85dd8a9440e9b50692905558513', visible=True),
 MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True),
 MapShowcaseItem(title='My Cool Map', item_id='121360f938104db285153479d2cd758c', visible=True)]

Example #2: Moving the first item to the end of the list

sc_items = my_showcase.showcase_items
sc_items

Output:

[MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True),
 MapShowcaseItem(title='World Hillshade (WGS84)', item_id='faceb85dd8a9440e9b50692905558513', visible=True),
 MapShowcaseItem(title='My Cool Map', item_id='121360f938104db285153479d2cd758c', visible=True)]

Example con’t:

new_order = sc_items[1:] + sc_items[:1]  # move first item to the end
my_showcase.reorder_showcase_items(new_order)
my_showcase.showcase_items

Output:

[MapShowcaseItem(title='World Hillshade (WGS84)', item_id='faceb85dd8a9440e9b50692905558513', visible=True),
 MapShowcaseItem(title='My Cool Map', item_id='121360f938104db285153479d2cd758c', visible=True),
 MapShowcaseItem(title='Enhanced Contrast Map', item_id='b5aafea65e6b48e0990dc4ad50fc5067', visible=True)]

property showcase_items: list[MapShowcaseItem]

Returns each member item of a MapShowcase as a list of MapShowcaseItem objects. The return order can be adjusted with the reorder_showcase_items() method.

Returns:

A list of MapShowcaseItem objects.

Example: Get all items in a Map showcase:

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")

showcase = MapShowcase(showcase_item, gis=gis)

showcase_items = showcase.showcase_items

print(type(showcase_items))
for showcase_item in showcase_items:
    print(f"{showcase_item.showcase_title:20}{showcase_item.item_type:10}{type(showcase_item)}")

Output:

<class 'list'>
Airports            Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>
Parks               Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>
City destinations   Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>

property showcase_items_info: DataFrame

Returns a pandas DataFrame describing each item in the Map Showcase.

Note

Columns are derived from the latest entries in the original Map showcase Item JSON definition. If available, the output will include a resolved organizational Item.

Returns:

A pandas.DataFrame with one row per Map Showcase item.

Includes the following columns:

• MapShowcaseItem: The MapShowcaseItem object representing this item in the Map Showcase.

• title: The title of the item as shown in the Map Showcase. This may differ from the source organizational item title if a custom title was set when adding the item to the showcase.

• original_title: The title of the source organizational Item if it can be resolved. This is the original title of the item in ArcGIS Online, regardless of any custom title set in the Map Showcase.

• type: The type of the item, as defined in the raw Map Showcase JSON. This is typically the same as the source organizational Item type, but may differ if the raw JSON was modified directly.

• visible: A boolean indicating whether the item is currently set to be visible in the Map Showcase.

• thumbnailUrl: The URL of the thumbnail image used for this item in the Map Showcase. This may be a custom thumbnail URL if one was set when adding the item, or it may be the thumbnail URL of the source item if no custom thumbnail was set.

Example: Get a Map showcase item’s informational dataframe

from arcgis.gis import GIS
from arcgis.gis import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")
map_showcase = MapShowcase(showcase_item, gis)

showcase_items_info = map_showcase.showcase_items_info
print(showcase_items_info)

Output:

MapShowcaseItem   title              original_title      type      visible  thumbnailUrl
----------------  -----------------  --------------      --------  -------  ----------------
My Cool Map       My Cool Map        My Cool Map         Web Map   True     https://example.com/thumbnail1.jpg
Enhanced Contrast Enhanced Contrast  Enhanced Contrast   Web Map   True     https://example.com/thumbnail2.jpg
World Hillshade   World Hillshade    World Hillshade     Web Map   True     https://example.com/thumbnail3.jpg

property title: str

Gets the title of the MapShowcase object.

Note

This is the same title property of the underlying organizational Item.

Example: Print the title of the Map Showcase and underlying item

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")
showcase_obj = MapShowcase(showcase_item, gis)

print("Map Showcase title:", showcase_obj.title)

Output:

Map Showcase title: My Custom Showcase Title

Bases: object

Represents an organizational item within a MapShowcase.

The item property returns the underlying organizational Item referenced in the Map showcase. Edits made to these objects are written to the Map showcase draft state.

Objecs of this class are not initialized directly by users. Instead, use the showcase_items() property to get a list of MapShowcaseItem objects.

Example: Get all items in a Map showcase:

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")

showcase = MapShowcase(showcase_item, gis)

showcase_items = showcase.showcase_items

print(type(showcase_items))
for showcase_item in showcase_items:
    print(f"{showcase_item.showcase_title:20}{showcase_item.item_type:10}{type(showcase_item)}")

Output:

<class 'list'>
Airports            Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>
Parks               Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>
City destinations   Web Map   <class 'arcgis.apps.mapshowcase.mapshowcase_item.MapShowcaseItem'>

download_thumbnail(save_folder: str | Path) → str | None

Downloads this map’s showcase thumbnail, falling back to the item thumbnail.

Parameter	Description
save_folder	Required string. The desired folder name to download the thumbnail to. Provide an absolute path.

Returns:

The downloaded thumbnail path, or None if unavailable.

property highlighted_area: HighlightedArea | None

Get/Set the highlighted area configuration for this showcase item.

Note

This method is currently in beta and the API may change without a major version bump. Please reach out to Esri if you want to use or provide feedback on this functionality. The values for HighlightedArea are subject to change as we learn more about how users want to use this and what the app supports. We recommend using this in a development environment and providing feedback to Esri on your experience.

Parameter	Description
highlighted_area	A arcgis.apps.mapshowcase.HighlightedArea pydantic model defining the highlighted area to show on the map.

property item: Item | None

Get the underlying organizational Item that is represented by the MapShowcaseItem object.

Returns:

The Item if it exists in the organization, else None.

Example: Get the underlying portal item for a showcase item:

from arcgis.gis import GIS
from arcgis.apps.mapshowcase import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")
showcase_object = MapShowcase(showcase_item, gis)

first_showcase_item = showcase_object.showcase_items[0]
portal_item = first_showcase_item.item

print(f"Portal item title: {portal_item.title if portal_item else None}")
print(f"Item type: {portal_item.type if portal_item else None}")

Output:

Portal item title: Imagery (WGS84)
Item type: Web Map

property item_id: str | None

Get the portal item ID referenced by this showcase item.

property item_type: str | None

Get the item type stored for this showcase item.

property showcase_description: str | None

Get/Set the description override as shown in the showcase.

Parameter	Description
new_description	The new description to set for this showcase item. If None, the source item’s description will be used.

property showcase_snippet: str | None

Get/Set the snippet/summary override as shown in the showcase.

Parameter	Description
new_snippet	The new snippet/summary to set for this showcase item. If None, the source item’s snippet will be used.

property showcase_title: str | None

Get or set a title within the Map showcase that can override the source organizational item title..

Parameter	Description
new_title	String to use for new title. If None, the source item title will be used.

Example: Set a new title for a MapShowcaseItem object within a Map showcase:

from arcgis.gis import GIS
from arcgis.gis import MapShowcase

gis = GIS(profile="your_online_profile")

showcase_item = gis.content.get("your_map_showcase_item_id")
showcase = MapShowcase(showcase_item, gis)

first_showcase_item = showcase.showcase_items[0]
print(f"{first_showcase_item.showcase_title}")

Output:

Water District Web Map

Example con’t: Update the title for a MapShowcaseItem object within a Map showcase:

first_showcase_item.showcase_title = "API-Updated " + first_showcase_item.showcase_title
print(f"{first_showcase_item.showcase_title}")

Output:

API-Updated Water District Web Map

property thumbnail_type: str | None

Get the thumbnail type used by this showcase item.

property thumbnail_url: str | None

Get the thumbnail URL for this item as shown in the showcase.

This may be different than the portal item thumbnail if a custom thumbnail is set for the showcase item. To see if the showcase item is using the portal item thumbnail, check if thumbnail_type() is “item”.

property uid: str | None

Get the unique showcase item ID.

uploaded_thumbnail(thumbnail_path: str) → None

Sets this showcase item to use an uploaded/custom thumbnail.

Parameter	Description
thumbnail_path	Required file path or URL of the uploaded thumbnail.

property url: str | None

Get the URL stored for this showcase item.

use_original_item_thumbnail() → None

Sets this showcase item to use the original portal item thumbnail.

This updates the showcase draft state.

property viewpoint: Viewpoint | None

Get the configured viewpoint for this showcase item.

property visible: bool

Get/Set whether this item is set to be visible in the showcase.

Parameter	Description
value	The new visibility state for this showcase item. Must be a boolean.

Bases: str, Enum

Known highlighted area source types.

ADMIN_LAYER = 'adminLayer'

DRAW = 'draw'

Bases: str, Enum

Known highlighted area mask themes.

DARK = 'dark'

LIGHT = 'light'

Bases: str, Enum

Known highlighted area style types for Map Showcase.

DARK_MASK = 'darkMask'

DARK_OPAQUE_MASK = 'darkOpaqueMask'

DROP_SHADOW_OUTLINE = 'dropShadowOutline'

LIGHT_MASK_BLUR = 'lightMaskBlur'

LIGHT_OPAQUE_MASK = 'lightOpaqueMask'