ArcGIS API for Python – WebMap Object versus Item Object
Glen Bambrick
- August 23, 2024
- 4:30 pm
- No Comments
Table of Contents
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, and updating webmaps and feature layers in ArcGIS Online. In this post we focus on the difference between an
Item object that represents a WebMap and a WebMap object instantiated from the WebMap class. The differentiation is important as they represent two different aspects of the WebMap type in ArcGIS Online. The Item object is basically the shell, the information that you see on the homepage of the item and in the Settings tab. But it is not limited to this for all Item types, especially with WebMaps. The WebMap object is the visual you see when you open the WebMap item in a Map Viewer. So lets take look… 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 need to import the WebMap class to create a WebMap object. The WebMap class is a part of the mapping module. This mapping module provides components for working with 2D and 3D maps and scenes, and also includes classes for map layers such as the MapFeatureLayer, MapImageLayer, and VectorTileLayer. We will also use the json module from the standard Python library to print some information to screen in a more readable fashion.
## import GIS which provides the gateway entry to your AGOL
from arcgis.gis import GIS
## import WebMap from the mapping module
from arcgis.mapping import WebMap
## to prettify some output
import json
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.
## Access AGOL
agol = GIS("home")
## Access AGOL
agol = GIS(
url = "https://your_organisation.maps.arcgis.com/",
username = "Your_Username",
password = "Your_Password"
)
The (WebMap) Item Object
An
Item object can represent any content item in your ArcGIS Online. Each Item object has an associated type such as Feature Layer Collection (which represents a Feature Service), Dashboard, Form, Shapefile, CSV, and Web Map for example. Here, we are interested in an Item object that represents a Web Map item in our ArcGIS Online.
Every content item in ArcGIS Online has its own unique item id. You can get the item id from the URL of the homepage for the item, or over on the righthand side of the item page where it has ID. 
We can directly access and instantiate an
Item object with the ArcGIS API for Python by using the ContentManager get() method and supplying in the item id. In the snippet below we do just that and then print the Item object to screen. When we print the wm_item to screen, the Item inside the first chevron shows it is an Item object. We can see the title of the WebMap, the type of the Item, which is Web Map, and the owner. If we call the type() function and supply in our wm_item, we can see it is from the Item class.
## access the WebMap Item
wm_item = agol.content.get("e5af618cbffe4d5b8de004d86bd78c19")
## print the object
print(wm_item)
# >>> <Item title:"WebMap_Item_v_Object" type:Web Map owner:FinalDraftMapping>
## print the object type
print(type(wm_item))
# >>> <class 'arcgis.gis.Item'>
The Item Class Properties and Methods
The
Item object has some class properties and methods that are available too all Item types, and some that are available for specific Item types only. You can check out the documentation here. Some Item class properties include can_delete (which is get only), comments (get-only, a list of all comments), content_status (get and set), and favorite (get and set). Some Item class methods include add_comment(), delete(), move(), and protect(). An important method for the WebMap Item object is the get_data() method. The get_data() method returns information about the Operational Layer and Tables for the WebMap, and initial WebMap extent, amongst other information. In comparison, the get_data() for a Feature Service returns and empty list.
The
Item object has some class properties and methods that are available too all Item types, and some that are available for specific Item types only. You can check out the documentation here. Some Item class properties include can_delete (which is get only), comments (get-only, a list of all comments), content_status (get and set), and favorite (get and set). Some Item class methods include add_comment(), delete(), move(), and protect(). An important method for the WebMap Item object is the get_data() method. The get_data() method returns information about the Operational Layers and Tables for the WebMap, and initial WebMap extent, amongst other information. In comparison, the get_data() for a Feature Service returns and empty list.
## get the WebMap Item "data"
wm_item_data = wm_item.get_data()
## print to screen
print(json.dumps(wm_item_data, indent=4))
##{
## "operationalLayers": [
## {
## "id": "1917ff49190-layer-2",
## "title": "County Boundaries",
## "url": "https://services-eu1.arcgis.com/xImpnbbhc3YDkwTJ/arcgis/rest/services/County Boundaries/FeatureServer/0",
## "itemId": "f1935e7c63744117b83b2de6edb5988f",
## "layerType": "ArcGISFeatureLayer",
## "popupInfo": {
## "popupElements": [
## {
## "type": "fields"
## },
## {
## "type": "attachments",
## "displayType": "auto"
## }
## ],
## "showAttachments": true,
## "fieldInfos": [
## {
## "fieldName": "FID",
## "isEditable": false,
## "label": "FID",
## "visible": false
## },
## {
## "fieldName": "COUNTY",
## "isEditable": true,
## "label": "COUNTY",
## "visible": true
## },
## {
## "fieldName": "PROVINCE",
## "isEditable": true,
## "label": "PROVINCE",
## "visible": true
## },
## {
## "fieldName": "Shape__Area",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": false,
## "label": "Shape__Area",
## "visible": true
## },
## {
## "fieldName": "Shape__Length",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": false,
## "label": "Shape__Length",
## "visible": true
## },
## {
## "fieldName": "Shape_Area",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": true,
## "label": "Shape_Area",
## "visible": true
## },
## {
## "fieldName": "Shape_Leng",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": true,
## "label": "Shape_Leng",
## "visible": true
## }
## ],
## "title": "ARCGISAFP03_TAILT_ADM_CountyBoundaries"
## }
## }
## ],
## "baseMap": {
## "baseMapLayers": [
## {
## "id": "gray-base-layer",
## "opacity": 0.5,
## "title": "Light Gray Base",
## "visibility": true,
## "layerType": "VectorTileLayer",
## "styleUrl": "https://www.arcgis.com/sharing/rest/content/items/291da5eab3a0412593b66d384379f89f/resources/styles/root.json"
## },
## {
## "id": "gray-reference-layer",
## "opacity": 1,
## "title": "Light Gray Reference",
## "visibility": true,
## "layerType": "VectorTileLayer",
## "styleUrl": "https://www.arcgis.com/sharing/rest/content/items/1768e8369a214dfab4e2167d5c5f2454/resources/styles/root.json",
## "isReference": true
## }
## ],
## "title": "My Basemap Title"
## },
## "authoringApp": "ArcGISMapViewer",
## "authoringAppVersion": "2024.2",
## "initialState": {
## "viewpoint": {
## "targetGeometry": {
## "spatialReference": {
## "latestWkid": 3857,
## "wkid": 102100
## },
## "xmin": -1011387.4532643256,
## "ymin": 7030018.536914008,
## "xmax": -1003495.3300938918,
## "ymax": 7038971.223851897
## }
## }
## },
## "spatialReference": {
## "latestWkid": 3857,
## "wkid": 102100
## },
## "timeZone": "system",
## "version": "2.31"
##}
The Item object does not have any cool methods for interacting with the layers and tables in the WebMap itself. Functionality such as adding and removing layers, updating popups and symbology are all handled via the WebMap class and not the Item class. You can however, manipulate the JSON printed from the get_data() method to update the Popups and Symbology for layers and even the Web Map extent. Any updating of the WebMap Item JSON requires the Item object update() method to be called to commit the changes.
We will see in the next section that you can also access the same information as the get_data() method via the WebMap object definition property.
NOTE: even if you manipulate the JSON via the definition property, you still need to perform update through the Item object.
The Item Class JSON Configuration
Behind each Item there is a JSON configuration. See below.
## print to item JSON to screen
print(json.dumps(wm_item, indent=4))
##{
## "id": "e5af618cbffe4d5b8de004d86bd78c19",
## "owner": "FinalDraftMapping",
## "created": 1724414565000,
## "isOrgItem": true,
## "modified": 1724428641000,
## "guid": null,
## "name": null,
## "title": "WebMap_Item_v_Object",
## "type": "Web Map",
## "typeKeywords": [
## "ArcGIS API for JavaScript",
## "ArcGIS Online",
## "Collector",
## "Data Editing",
## "Explorer Web Map",
## "Map",
## "Online Map",
## "Web Map"
## ],
## "description": "This is the description for our WebMap item",
## "tags": [
## "Tag1",
## "Tag2",
## "Tag3"
## ],
## "snippet": "This is the summary for our WebMap item",
## "thumbnail": "thumbnail/ago_downloaded.png",
## "documentation": null,
## "extent": [
## [
## -9.085448074340619,
## 53.253454993239124
## ],
## [
## -9.014551925659074,
## 53.30154332522864
## ]
## ],
## "categories": [],
## "spatialReference": "",
## "accessInformation": "",
## "classification": null,
## "licenseInfo": "",
## "culture": "en-us",
## "properties": null,
## "advancedSettings": null,
## "url": "",
## "proxyFilter": null,
## "access": "private",
## "size": 2096,
## "subInfo": 0,
## "appCategories": [],
## "industries": [],
## "languages": [],
## "largeThumbnail": null,
## "banner": null,
## "screenshots": [],
## "listed": false,
## "ownerFolder": null,
## "protected": false,
## "commentsEnabled": true,
## "numComments": 0,
## "numRatings": 0,
## "avgRating": 0,
## "numViews": 4,
## "itemControl": "admin",
## "scoreCompleteness": 70,
## "groupDesignations": null,
## "apiToken1ExpirationDate": -1,
## "apiToken2ExpirationDate": -1,
## "contentOrigin": "self",
## "lastViewed": 1724425200000
##}
Some of the information present in this JSON represents what we can see from the Item homepage. title, description, tags, snippet, thumbnail, accessInformation, and licenseInfo can all be altered via the API using the
Item object update() method. 
The WebMap Object
The
WebMap class represents a Web Map and provides access to its basemaps and operational layers and tables as well as functionality to visualize and interact the content of the Web Map..
## create a WebMap object
wm_obj = WebMap(wm_item)
## print the object type
print(type(wm_obj))
# >>> <class 'arcgis.mapping._types.WebMap'>
The WebMap Class Properties and Methods
The
WebMap object has class properties and methods. Check out the documentation here. Some properties include basemap (get and set), bookmarks (get and set), and layers (get-only). WebMap object methods include add_layer(), add_table(), get_layer(), get_table(), and update_drawing_info().
While not in the documentation (at time of writing), the definition property returns the same information as the Item get_data() method.
## create a WebMap object
wm_obj = WebMap(wm_item)
## print the object type
print(type(wm_obj))
# >>> <class 'arcgis.mapping._types.WebMap'>
##{
## "operationalLayers": [
## {
## "id": "1917ff49190-layer-2",
## "title": "County Boundaries",
## "url": "https://services-eu1.arcgis.com/xImpnbbhc3YDkwTJ/arcgis/rest/services/County Boundaries/FeatureServer/0",
## "itemId": "f1935e7c63744117b83b2de6edb5988f",
## "layerType": "ArcGISFeatureLayer",
## "popupInfo": {
## "popupElements": [
## {
## "type": "fields"
## },
## {
## "type": "attachments",
## "displayType": "auto"
## }
## ],
## "showAttachments": true,
## "fieldInfos": [
## {
## "fieldName": "FID",
## "isEditable": false,
## "label": "FID",
## "visible": false
## },
## {
## "fieldName": "COUNTY",
## "isEditable": true,
## "label": "COUNTY",
## "visible": true
## },
## {
## "fieldName": "PROVINCE",
## "isEditable": true,
## "label": "PROVINCE",
## "visible": true
## },
## {
## "fieldName": "Shape__Area",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": false,
## "label": "Shape__Area",
## "visible": true
## },
## {
## "fieldName": "Shape__Length",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": false,
## "label": "Shape__Length",
## "visible": true
## },
## {
## "fieldName": "Shape_Area",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": true,
## "label": "Shape_Area",
## "visible": true
## },
## {
## "fieldName": "Shape_Leng",
## "format": {
## "digitSeparator": true,
## "places": 2
## },
## "isEditable": true,
## "label": "Shape_Leng",
## "visible": true
## }
## ],
## "title": "ARCGISAFP03_TAILT_ADM_CountyBoundaries"
## }
## }
## ],
## "baseMap": {
## "baseMapLayers": [
## {
## "id": "gray-base-layer",
## "opacity": 0.5,
## "title": "Light Gray Base",
## "visibility": true,
## "layerType": "VectorTileLayer",
## "styleUrl": "https://www.arcgis.com/sharing/rest/content/items/291da5eab3a0412593b66d384379f89f/resources/styles/root.json"
## },
## {
## "id": "gray-reference-layer",
## "opacity": 1,
## "title": "Light Gray Reference",
## "visibility": true,
## "layerType": "VectorTileLayer",
## "styleUrl": "https://www.arcgis.com/sharing/rest/content/items/1768e8369a214dfab4e2167d5c5f2454/resources/styles/root.json",
## "isReference": true
## }
## ],
## "title": "My Basemap Title"
## },
## "authoringApp": "ArcGISMapViewer",
## "authoringAppVersion": "2024.2",
## "initialState": {
## "viewpoint": {
## "targetGeometry": {
## "spatialReference": {
## "latestWkid": 3857,
## "wkid": 102100
## },
## "xmin": -1011387.4532643256,
## "ymin": 7030018.536914008,
## "xmax": -1003495.3300938918,
## "ymax": 7038971.223851897
## }
## }
## },
## "spatialReference": {
## "latestWkid": 3857,
## "wkid": 102100
## },
## "timeZone": "system",
## "version": "2.31"
##}
It is important to note, any time you set a
WebMap object property, the class properties, the ones you see in the documentation, or call a WebMap object method, you must use the WebMap object update() method to commit the changes.
Cast your mind back to the note from the previous section, if we manipulated the JSON for the WebMap Item object, the JSON returned from the get_data() method, we must update the Item object. The WebMap object definition returns the same information as the get_data(), and as such, when the JSON in the definition property is manipulated, it is the Item object that must be updated to take affect. Updating the WebMap Item Object versus the WebMap Object
Whenever we update a property of the WebMap object or use a WebMap object method to update a property, we must call the WebMap object update() method to commit the change. These methods include
basemap_title(), move_from_basemap(), move_to_basemap(), and get_layer().
wm_obj.update()
When we call the WebMap object definition property, we are returned the same dictionary as the Item object get_data() method. We can manipulate the dictionary/JSON returned. After manipulating the JSON we must update the Item object properties.
item_properties = {"text":webmap.definition}
wm_item.update(item_properties=item_properties)
Geospatial Professionals, GIS Analysts, and enthusiasts will discover the power of automation and script-based operations to efficiently interact and update WebMaps in ArcGIS Online. Throughout this course, you will gain practical, hands-on experience in leveraging the ArcGIS API for Python to perform a wide range of WebMap tasks with ease.
We will dissect WebMaps for all that they are and by the end of this course you will be comfortable with manipulating the JSON, which is the behind the scenes configuration of a WebMap, to produce scripts for workflows where there is currently no API Python method, such as grouping layers.
