Backup ArcGIS Online WebMap Configurations using the ArcGIS API for Python

The Video

Subscribe on YouTube

Introduction

The ArcGIS API for Python is a powerful Python library that allows users to interact with and automate tasks in ArcGIS Online (or Portal). The API is excellent for programmatically creating, maintaining, updating and extracting components of ArcGIS Online such as WebMaps. In this blog post we will focus on using the ArcGIS API for Python to export a WebMap to configuration files that will act as an archive or backup. We will export two files, one that represents the WebMap JSON Definition, and another that represents the WebMap Item Settings. We will also account for a thumbnail.

arcgis modules

The API provides access to your organisations ArcGIS Online via the GIS class in the gis module. This GIS class is the gateway to ArcGIS Online. We will also utilise two Standard Python Library modules; json for exporting and formatting our JSON files, and os for handling filepaths and creating folders.

## provides access to ArcGIS Online
from arcgis.gis import GIS

## not essential but will make the output file more readable
import json

## for creating our output file path
import os

Accessing ArcGIS Online

Our first port of call is to access your ArcGIS Online via the GIS class. There are a handful of ways to achieve access, if you are logged into your ArcGIS Online in ArcGIS Pro you can simply use "home", otherwise, another common way is to provide the ArcGIS Online URL, followed by your username and password. Check here for more options.

## Access AGOL
agol = GIS("home")

## Access AGOL
agol = GIS(
    url = "https://your_organisation.maps.arcgis.com/",
    username = "Your_Username",
    password = "Your_Password"
)

Required inputs

Two user inputs required; the Item ID for the WebMap to backup, and a folder path for where to store the files.

## the item id for the WebMap you want to backup/archive
wm_item_id = "WM_ITEM_ID"

## the folder where the JSON file is to be saved
output_folder = "path/to/output/folder"

Get the WebMap as an Item Object

Each piece of content in ArcGIS Online is an item defined by its item type. We get the WebMap of interest as an Item object (of type WebMap)

## the ContentManager get() will return the WebMap item as an Item object
wm_item = agol.content.get(wm_item_id)

Get the WebMap JSON Definition

Our Item object represents a WebMap, therefore, when we call the get_data() method on the Item, we are returned the WebMap JSON definition as a Python dictionary. 

We will grab the favourite Item object property and add it to the wm_item because it is not stored in there by default.

## the get_data() method on a WebMap item returns the WebMap definition
## as a dictionary
wm_def = wm_item.get_data()

## struggles to know its a favorite, we'll continue to make it feel special!
wm_item["favorite"] = wm_item.favorite

Some Housekeeping Before Exporting

We create a folder within the Output Folder nominated by the user and name it the same as the WebMap itself. We will want to place two output files in this folder; one that represents the WebMap Definition, and the other that represents the WebMap item settings.

## we will use the title of the WebMap in the output files
wm_title = wm_item.title

## create a folder within the output folder
archive_folder = os.path.join(output_folder, wm_title)

## if the archive_folder doesnt exist then create it
if not os.path.exists(archive_folder):
    os.makedirs(archive_folder)

## the filepath for the WebMap Definition
out_json_definition = os.path.join(archive_folder, f"Definition_{wm_title}.json")

## the fielpath for the Item Setting
out_json_settings = os.path.join(archive_folder, f"Settings_{wm_title}.json")

Export Configurations as JSON Files

We export both the WebMap JSON Definition and WebMap Item Settings to file.

## Export the WebMap Definition to file
with open(out_json_definition, "w", encoding="utf-8") as f:
    json.dump(wm_def, f, ensure_ascii=False, indent=4)

## Export the WebMap Item Settings to file
with open(out_json_settings, "w", encoding="utf-8") as f:
    json.dump(wm_item, f, ensure_ascii=False, indent=4)

Export Configurations as JSON Files

And we’ll make sure to grab the thumbnail too.

## Let's not forget the thumbnail
wm_item.download_thumbnail(save_folder=archive_folder)

All the code in one place

You can find the entire code workflow below with links to important components in the documentation that were used.

## provides access to ArcGIS Online
from arcgis.gis import GIS

## not essential but will make the output file more readable
import json

## for creating our output file path
import os

################################################################################
## API Reference Links:
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#gis
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#contentmanager
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.ContentManager.get
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#item
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.get_data
##  https://developers.arcgis.com/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item.download_thumbnail
##
## API Versions: 2.1.0.2, 2.2.0.1, 2.3.0, 2.4.0
##
################################################################################

################################################################################
## ACCESS ARCGIS ONLINE ########################################################

agol = GIS("home")

################################################################################
## USER INPUTS #################################################################

## teh item id for the WebMap you want to backup/archive
wm_item_id = "WM_ITEM_ID"

## the folder where the JSON file is to be saved
output_folder = "path/to/output/folder"

################################################################################
## GET THE ITEM OBJECT #########################################################

## the ContentManager get() will return the WebMap item as an Item object
wm_item = agol.content.get(wm_item_id)

################################################################################
## GET THE WEBMAP DEFINITION ###################################################

## the get_data() method on a WebMap item returns the WebMap definition
## as a dictionary
wm_def = wm_item.get_data()

## struggles to know its a favorite, we'll continue to make it feel special!
wm_item["favorite"] = wm_item.favorite

################################################################################
## GETTING READY TO EXPORT #####################################################

## we will use the title of the WebMap in the output files
wm_title = wm_item.title

## create a folder within the output folder
archive_folder = os.path.join(output_folder, wm_title)

## if the archive_folder doesnt exist then create it
if not os.path.exists(archive_folder):
    os.makedirs(archive_folder)

## the filepath for the WebMap Definition
out_json_definition = os.path.join(archive_folder, f"Definition_{wm_title}.json")

## the fielpath for the Item Setting
out_json_settings = os.path.join(archive_folder, f"Settings_{wm_title}.json")

################################################################################
## SAVE AS JSON FILES ##########################################################

## Export the WebMap Definition to file
with open(out_json_definition, "w", encoding="utf-8") as f:
    json.dump(wm_def, f, ensure_ascii=False, indent=4)

## Export the WebMap Item Settings to file
with open(out_json_settings, "w", encoding="utf-8") as f:
    json.dump(wm_item, f, ensure_ascii=False, indent=4)

################################################################################
## DOWNLOAD THE THUMBNAIL ######################################################

## Let's not forget the thumbnail
wm_item.download_thumbnail(save_folder=archive_folder)

################################################################################
print("\nSCRIPT COMPLETE")