arcgis.gis module

The GIS class is representative of a single ArcGIS Online organization or an ArcGIS Enterprise deployment. The GIS object provides helper objects to manage (search, create, retrieve) GIS resources such as content, users, and groups.

Additionally, the GIS object has properties to query its state, which is accessible using the properties attribute.

The constructor constructs a GIS object given a url and user credentials to ArcGIS Online or an ArcGIS Enterprise portal. User credentials can be passed in using username/password pair, or key_file/cert_file pair (in case of PKI). Supports built-in users, LDAP, PKI, Integrated Windows Authentication (using NTLM and Kerberos) and Anonymous access.

If no url is provided, ArcGIS Online is used. If username/password or key/cert files are not provided, the currently logged-in user’s credentials (IWA) or anonymous access is used.

Persisted profiles for the GIS can be created by giving the GIS authorization credentials and specifying a profile name. The profile stores all of the authorization credentials (except the password) in the user’s home directory in an unencrypted config file named .arcgisprofile. The profile securely stores the password in an O.S. specific password manager through the keyring python module.

Once a profile has been saved, passing the profile parameter by itself uses the authorization credentials saved in the configuration file/password manager by that profile name. Multiple profiles can be created and used in parallel.

See Working with different authentication schemes in the ArcGIS API for Python guide for examples.

# Retrieving a token from a GIS object
>>> from arcgis.gis import GIS

>>> gis = GIS(
        url="url to Web GIS",
        username="user_name",
        password="secure_password"
    )

>>> token = gis.session.auth.token
>>> token

'3BMHr9i ... RTxekAdWkSmF9cKQIkM7DLy.'

In addition to explicitly named parameters, the GIS object supports optional key word arguments:

# Usage Example 1: Anonymous Login to ArcGIS Online

gis = GIS()

# Usage Example 2: Built-in Login to ArcGIS Online

gis = GIS(username="someuser", password="secret1234")

# Usage Example 3: Built-in Login to ArcGIS Enterprise

gis = GIS(url="http://pythonplayground.esri.com/portal",
      username="user1", password="password1")

# Usage Example 4: Built-in Login to ArcGIS Enterprise, ignoring SSL errors

gis = GIS(url="http://pythonplayground.esri.com/portal", username="user1",
          password="password1", verify_cert=False)

# Usage Example 5: Anonymous ArcGIS Online Login with Proxy

gis = GIS(proxy={'http': 'http://127.0.0.1:8888', 'https': 'http://127.0.0.1:8887'})

# Usage Example 6: PKI Login to ArcGIS Enterprise, using PKCS12 user certificate

gis = GIS(url="https://pkienterprise.esri.com/portal",
          cert_file="C:\users\someuser\mycert.pfx", password="password1")

# Usage Exmaple 7: Login with token (actual token abbreviated for this illustration)

gis = GIS(token="3G_e-FSoJdwxBgSA0RiOZg7zJVVqlOG-ENw83UtoUzDdz4 ... _L2aQMrthrEq7vKYBn39HGSc.",
          referer="https://www.arcgis.com")

# Usage Exmaple 8: Login with API Key (actual token abbreviated for this illustration)

gis = GIS(api_key="APKSoJdwxBgSA0RiOZg7zJVVqlOG-ENw83UtoUzDdz4 ... _L2aQMrth39HGSc.",
          referer="https")

# Usage Exmaple 9: Using a Proxy
proxy = {
    'http': 'http://10.10.1.10:3128',
    'https': 'http://10.10.1.10:1080',
}
gis = GIS(proxy=proxy)

# Usage Exmaple 10: Using a CA_BUNDLE specifying SSL certificates
certs = r"./CA_CERTS/cacert.pem"
gis = GIS(profile="your_enterprise_admin_profile", verify_cert=certs)

property api_keys

The api_keys property returns an instance of APIKeyManager object which allows the User to generate, manage and modify API Keys for controlled application access.

Note

The API Key manager is only available for ArcGIS Online

Returns:

An APIKeyManager object

property content

The content property is the resource manager for GIS content. See ContentManager for more information.

property datastore

The datastore property returns the manager for user-managed data store items.

Note

This is only available with ArcGIS Enterprise 10.7+. See PortalDataStore for more information.

Returns:

A PortalDataStore object

property groups

The groups property is resource manager for GIS groups. See GroupManager for more information.

property hosting_servers

Returns the hosting servers for the GIS

Returns:

list

property hub

The hub property is the resource manager for GIS hub. See Hub for more information.

property languages

Lists the available languages.

Returns:

List[Dict[str, Any]]

map(location=None, mode='2D')

The map method creates a map widget centered at the declared location with the specified zoom level. If an address is provided, it is geocoded using the GIS’s configured geocoders. Provided a match is found, the geographic extent of the matched address is used as the extent of the map. If a zoomlevel is also provided, the map is centered at the matched address instead and the map is zoomed to the specified zoomlevel. See Map for more information.

Note

The map widget is only supported within a Jupyter Notebook. IE11 is no longer supported. Please use the latest version of Google Chrome, Mozilla Firefox, Apple Safari, or Microsoft Edge.

Parameter	Description
location	Optional string. The address or lat-long tuple of where the map is to be centered.
mode	Optional string of either ‘2D’ or ‘3D’ to specify map mode. Defaults to ‘2D’.

Note

If the Jupyter Notebook server is running over http, you need to configure your ArcGIS Enterprise portal or ArcGIS Online organization to allow your host and port; or else you will run into CORS issues when displaying this map widget.

This can be accomplished by signing into your ArcGIS Enterprise portal or ArcGIS Online organization in a browser, then navigating to:

Organization > Settings > Security > Allow origins > Add > http://localhost:8888 (replace with the host/port you are running on)

# Usage Example

>>> gis = GIS(url="http://pythonplayground.esri.com/portal", username="user1", password="password1")

>>> gis.map("Durham,NC")

Returns:

A map or scene.

property notebook_server

The notebook_server property provides access to the NotebookServer registered with the organization or enterprise. :return: List [NotebookServer]

property org_settings

The portal settings resource is used to return a view of the portal’s configuration as seen by the current users, either anonymous or logged in. Information returned by this resource includes helper services, allowed redirect URIs, and the current configuration for any access notices or information banners.

Parameter

Description

settings

Required Dict. A dictionary of the settings Fields Description anonymousAccessNotice Dict. A JSON object representing a notice that is shown to your organization’s anonymous users. Ex: {‘title’: ‘Anonymous Access Notice Title’, ‘text’: ‘Anonymous Access Notice Text’, ‘buttons’: ‘acceptAndDecline’, ‘enabled’: True} authenticatedAccessNotice Dict. A JSON object representing a notice that is shown to your organization’s authenticated users. Ex: {‘title’: ‘Authenticated Access Notice Title’, ‘text’: ‘Authenticated Access Notice Text’, ‘buttons’: ‘okOnly’, ‘enabled’: True} informationalBanner Dict. A JSON object representing the informational banner that is shown at the top of your organization’s page. Ex: {‘text’: ‘Header Text’, ‘bgColor’: ‘grey’, ‘fontColor’: ‘blue’, ‘enabled’: True} clearEmptyFields Bool. If True, any empty dictionary will be set to null.

Returns:

Dictionary indicating ‘success’ or ‘error’

property pages

The pages property is the resource manager for a Page of an Enterprise Site. See pages for more information.

property properties

properties manages the actual properties of the GIS object.

property regions

Lists the available regions.

Returns:

List[Dict[str, Any]]

property servers

Returns the servers registered with ArcGIS Entperise. For ArcGIS Online, the return value is None.

Returns:

dict

property session

Provides the raw Esri Session object

Returns:

An EsriSession object.

property sites

The sites property is the resource manager for Enterprise Sites. See sites for more information.

property subscription_information

Returns the ArcGIS Online Subscription Information for a Site.

Returns:

dictionary

property symbol_service

Symbol service is an ArcGIS Server utility service that provides access to operations to build and generate images for Esri symbols to be consumed by internal and external web applications.

Returns:

A SymbolService object or None

update_properties(properties_dict)

The update_properties method updates the GIS’s properties from those in properties_dict. This method can be useful for updating the utility services used by the GIS.

Parameter	Description
properties_dict	Required dictionary. A dictionary of just those properties and values that are to be updated.

Returns:

A boolean indicating success (True), or failure (False)

Note

For examples of the property names and key/values to use when updating utility services, refer to the Common parameters page in the ArcGIS REST API.

# Usage Example: Update the geocode service

gis = GIS(profile='xyz')
upd = {'geocodeService': [{
  "singleLineFieldName": "Single Line Input",
  "name": "AtlantaLocator",
  "url": "https://some.server.com/server/rest/services/GeoAnalytics/AtlantaLocator/GeocodeServer",
  "itemId": "abc6e1fc691542938917893c8944606d",
  "placeholder": "",
  "placefinding": "true",
  "batch": "true",
  "zoomScale": 10000}]}

gis.update_properties(upd)

property url

The url property is a read-only URL of your GIS connection.

property users

The users property is the resource manager for GIS users. See UserManager for more information.

property velocity

The resource manager for ArcGIS Velocity. See Velocity :return: Velocity

property version

The version property returns the GIS version number

Bases: dict

The Item class represents an item in the GIS, where an item is simply considered a unit of content in the GIS. Each item has a unique identifier and a well-known URL that is independent of the user owning the item. For a comprehensive list of properties of an item please see the REST API documentation here . Additionally, each item can have associated binary or textual data that’s available via the item data resource. For example, an item of type Map Package returns the actual bits corresponding to the map package via the item data resource.

Items that have layers (eg FeatureLayerCollection items and ImageryLayer items) and tables have the dynamic layers and tables properties to get to the individual layers/tables in this item.

add_comment(comment)

The add_comment method adds a comment to an item.

Note

The add_comment method is only available only to authenticated users who have access to the item.

Parameter	Description
comment	Required string. Text to be added as a comment to a specific item.

Returns:

Comment ID if successful, None if failure occurs.

# Usage Example

>>> item.add_comment("Detailed Comment on the Item")

add_relationship(rel_item, rel_type)

The add_relationship method adds a relationship from the current item to rel_item.

Note

Note: Relationships are not tied to an item. Instead, they are directional links from an origin item to a destination item and have a type. The type of the relationship defines the valid origin and destination item types as well as some rules. See Relationship types in REST API help for more information. Users don’t have to own the items they relate unless so defined by the rules of the relationship type.

Users can only delete relationships they create.

Relationships are deleted automatically if one of the two items is deleted.

Parameter	Description
rel_item	Required Item object corresponding to the related item.
rel_type	Required string. The type of the related item; is one of [‘Map2Service’, ‘WMA2Code’, ‘Map2FeatureCollection’, ‘MobileApp2Code’, ‘Service2Data’, ‘Service2Service’]. See Relationship Types in the REST API help for more information on this parameter.

Returns:

A boolean indicating success (True), or failure (False)

# Usage Example

>>> item.add_relationship(reL_item=item2, rel_type='Map2FeatureCollection')
<True>

property app_info

The app_info property is a resource for accessing application information. If the parent item is registered using the register app operation, app_info returns information pertaining to the registered app. Every registered app gets an App ID and App Secret, which are titled client_id and client_secret, respectively, in the terminology of OAuth.

Returns:

A Dictionary

property can_delete

Checks if the Item can be removed from the system.

Returns:

bool

can_reassign(target_user)

Checks if the Item can be reassigned to a new user. Users assigned the default administrator role, or a custom role with administrative privileges, can perform this operation. The item owner can also use this operation; if the item owner that performs this operation is not a default administrator, or assigned a custom role with administrative privileges, they must have the portal:user:reassignItems privilege assigned to them to transfer content to another user.

Parameter	Description
target_user	Required string or User. The string must be a username value. This will be the user receiving the item.

Returns:

tuple[bool, dict[str,Any]]

property comments

The comments property gets a list of comments for a given item.

property content_status

The content_status property states if an Item is authoritative or deprecated. This givens owners and administrators of Item the ability to warn users that they should be either this information or not.

Parameter	Description
value	Optional string or None. Defines if an Item is deprecated or authoritative. If a value of None is given, then the value will be reset. Allowed Values: authoritative, deprecated, or None

copy(title=None, tags=None, snippet=None, description=None, layers=None)

The copy method allows for the creation of an item that is derived from the current Item.

For layers, copy will create a new item that uses the URL as a reference. For non-layer based items, these will be copied and the exact same data will be provided.

If title, tags, snippet of description is not provided the values from item will be used. The copy method can be used in a variety of situations, such as:

1. Vector tile service sprite customization

2. Limiting feature service exposure

3. Sharing content by reference with groups

4. Creating backup items.

Parameter	Description
title	Optional string. The name of the new item.
tags	Optional list of string. Descriptive words that help in the searching and locating of the published information.
snippet	Optional string. A brief summary of the information being published.
description	Optional string. A long description of the Item being published.
layers	Optional list of integers. If you have a layer with multiple and you only want specific layers, an index can be provided those layers. If nothing is provided, all layers will be visible.

Returns:

An Item object

**Usage Example**

>>> item.copy()
<Item title:"gisslideshow - Copy 94452b" type:Microsoft Powerpoint owner:geoguy>

>>> item.copy(title="GIS_Tutorial")
<Item title:"GIS_Tutorial" type:Microsoft Powerpoint owner:geoguy>

>>> item.copy()
<Item title:"NZTiles - Copy 021a06" type:Vector Tile Layer owner:geoguy>

copy_feature_layer_collection(service_name, layers=None, tables=None, folder=None, description=None, snippet=None, owner=None)

The copy_feature_layer_collection method allows users to copy existing Feature Layer Collections and select the layers/tables that the user wants in the service. It is quite similar to the copy method, but only copies the selected Feature Layer Collections.

Parameter	Description
service_name	Required string. It is the name of the service.
layers	Optional list/string. This is a either a list of integers or a comma seperated list of integers as a string. Each index value represents a layer in the feature layer collection.
tables	Optional list/string. This is a either a list of integers or a comma seperated list of integers as a string. Each index value represents a table in the feature layer collection.
folder	Optional string. This is the name of the folder to place in. The default is None, which means the root folder.
description	Optional string. This is the Item description of the service.
snippet	Optional string. This is the Item’s snippet of the service. It is no longer than 250 characters.
owner	Optional string/User. The default is the current user, but if you want the service to be owned by another user, pass in this value.

Returns:

If successful, returns an Item object. Otherwise, returns None on failure.

# Usage Example

>>> item.copy_feature_layer_collection(service_name="service_name", layers="1,4,5,8")

copy_item(*, title=None, tags=None, folder=None, include_resources=False, include_private=False)

The copy_item operation creates a new Item that is a copy of the original Item on the server side. It is quite similar to the copy method, but only creates a new Item.

The copy_item method is allowed for the following:

1. Original item being copied is owned by the user invoking the copy operation.

2. The User object is an administrator.

3. The User object has itemControl update capability.

Additionally, there are several caveats to the copy_item method. First, the new item created by the copy_item operation will have a system generated itemID. Additionally, hosted services are copied as reference only. Reserved keywords, ratings, views, comments and listing properties are reset for the new item. Sharing access of the original item is not preserved and sharing access of new item is set to private. Lastly, relationships and dependencies of the original item are not maintained in the new item.

Note

This method is only available on ArcGIS Online or ArcGIS Enterprise 10.9 or higher

Returns:

An Item object

create_thumbnail(update=True)

The create_thumbnail method creates a Thumbnail for a feature service portal item using the service’s symbology and the print service registered for the enterprise.

Parameter	Description
update	Optional boolean. When set to True, the item will be updated with the thumbnail generated in this call, else it will not update the item. The default is True.

Returns:

A DataFile object

create_tile_service(title, min_scale, max_scale, cache_info=None, build_cache=False)

The create_tile_service method allows publishers and administrators to publish hosted feature layers and hosted feature layer views as a tile service.

Parameter	Description
title	Required string. The name of the new service.
min_scale	Required float. The smallest scale at which to view data.
max_scale	Required float. The largest scale at which to view data.
cache_info	Optional dictionary. If not none, administrator provides the tile cache info for the service. The default is the ArcGIS Online scheme.
build_cache	Optional boolean. Default is False; if True, the cache will be built at publishing time. This will increase the time it takes to publish the service.

Returns:

The Item object if successfully added, None if unsuccessful.

# Usage Example

>>> item.create_tile_service(title="SeasideHeightsNJTiles", min_scale= 70000.0,max_scale=80000.0)

delete(force=False, dry_run=False, permanent=False)

The delete method deletes the item. If the item is unable to be deleted , a RuntimeException is raised. To know if you can safely delete the item, use the optional parameter ‘dry_run’ in order to test the operation without actually deleting the item.

Parameter	Description
force	Optional boolean. Available in ArcGIS Enterprise 10.6.1 and higher. Force deletion is applicable only to items that were orphaned when a server federated to the ArcGIS Enterprise was removed accidentally before properly unfederating it. When called on other items, it has no effect.
dry_run	Optional boolean. Available in ArcGIS Enterprise 10.6.1 and higher.If True, checks if the item can be safely deleted and gives you back either a dictionary with details. If dependent items are preventing deletion, a list of such Item objects are provided.
permanent	Optional boolean. Available in ArcGIS Online, setting to True will permanently delete the item rather than sending it to the recycle bin.

Returns:

A boolean indicating success (True), or failure (False). When dry_run is used, a dictionary containing details of the item is returned.

USAGE EXAMPLE: Successful deletion of an item

item1 = gis.content.get('itemId12345')
item1.delete()

>> True

USAGE EXAMPLE: Failed deletion of an item

item1 = gis.content.get('itemId12345')
item1.delete()

>> RuntimeError: Unable to delete item. This service item has a related Service item
>> (Error Code: 400)

USAGE EXAMPLE: Dry run to check deletion of an item

item1 = gis.content.get('itemId12345abcde')
item1.delete(dry_run=True)

>> {'can_delete': False,
>> 'details': {'code': 400,
>> 'message': 'Unable to delete item. This service item has a related Service item',
>> 'offending_items': [<Item title:"Chicago_accidents_WFS" type:WFS owner:sharing1>]}}

Note

During the dry run, if you receive a list of offending items, attempt to delete them first before deleting the current item. You can in turn call dry_run on those items to ensure they can be deleted safely.

delete_info(file)

This is available for all items and allows you to delete an individual file from an item’s esriinfo folder.

Parameter	Description
file	Required String. The file to be deleted.

delete_rating()

The delete_rating method removes the rating the calling user added for the specified item.

delete_relationship(rel_item, rel_type)

The delete_relationship method deletes a relationship between this item and the rel_item.

Parameter	Description
rel_item	Required Item object corresponding to the related item.
rel_type	Required string. The type of the related item; is one of [‘Map2Service’, ‘WMA2Code’, ‘Map2FeatureCollection’, ‘MobileApp2Code’, ‘Service2Data’, ‘Service2Service’]. See Relationship Types in the REST API help for more information on this parameter.

Returns:

A boolean indicating success (True), or failure (False)

# Usage Example

item.delete_relationship(item2, 'Map2FeatureCollection')

delete_thumbnail()

Deletes the item’s thumbnail

Returns:

bool

property dependencies

The dependencies property returns a class to manage an item’s dependencies.

Returns:

ItemDependency object.

dependent_to()

The dependent_to method returns items, urls, etc that are dependent to this item.

Note

This method only available for items in an ArcGIS Enterprise organization.

dependent_upon()

The dependent_upon method returns items, urls, etc that this item is dependent on.

Note

This method only available for items in an ArcGIS Enterprise organization.

download(save_path=None, file_name=None)

The download method downloads the data to the specified folder or a temporary folder, if a folder is not provided.

Parameter	Description
save_path	Optional string. Folder location to download the file to.
file_name	Optional string. The name of the file.

Returns:

The download path if data was available, otherwise None.

# Usage Example

>>> item.download("C:\ARCGIS\Projects", "hurricane_data")

download_metadata(save_folder=None)

The download_metadata method is similar to the download method but only downloads the item metadata for the specified item id. Items with metadata have ‘Metadata’ in their typeKeywords.

Parameter	Description
save_folder	Optional string. Folder location to download the item’s metadata to.

Returns:

A file path, if the metadata download was successful. None if the item does not have metadata.

download_thumbnail(save_folder=None)

The download_thumbnail method is similar to the download method but only downloads the item thumbnail.

Parameter	Description
save_folder	Optional string. Folder location to download the item’s thumbnail to.

return:

A file path, If the download was successful. None if the item does not have a thumbnail.

export(title, export_format, parameters=None, wait=True, enforce_fld_vis=None, tags=None, snippet=None)

The export method is used to export a service item to the specified export format. However, it is available only to users with an organizational subscription and can only be invoked by the service item owner or an administrator, unless a Location Tracking Service or Location Tracking View is used. The export method is useful for long running exports that could hold up a script.

Parameter	Description
title	Required string. The desired name of the exported service item.
export_format	Required string. The format to export the data to. Allowed types: Shapefile, CSV, File Geodatabase, Feature Collection, GeoJson, Scene Package, KML, Excel, geoPackage, or Vector Tile Package.
parameters	Optional string. A JSON object describing the layers to be exported and the export parameters for each layer.and the export parameters for each layer. See Export Item in the REST API for guidance.
wait	Optional boolean. Default is True, which forces a wait for the export to complete; use False for when it is okay to proceed while the export continues to completion.
enforce_fld_vis	Optional boolean. Be default when you are the owner of an item and the export operation is called, the data provides all the columns. If the export is being perform on a view, to ensure the view’s column definition is honor, then set the value to True. When the owner of the service and the value is set to False, all data and columns will be exported.
tags	Optional String. A comma seperated value of item descriptors.
snippet	Optional String. A short descriptive piece of text.

Returns:

An Item object or a dictionary. Item is returned when wait=True. A dictionary describing the status of the item is returned when wait=False. See the status method for more information.

# Usage Example

>>> item.export("hurricane_data", "CSV", wait =True, tags= "Hurricane, Natural Disasters")

property favorite

Gets/Sets if the Item is in the user’s favorites

get_data(try_json=True)

The get_data method retrieves the data associated with an item.

Note

This call may return different results for different item types: some item types may even return None. See Working with users, groups, and items in the ArcGIS REST API for more information.

Parameter	Description
try_json	Optional string. Default is True. For JSON/text files, if try_json is True, the method tries to convert the data to a Python dictionary (use json.dumps(data) to convert the dictionary to a string), otherwise the data is returned as a string.

Returns:

Dependent on the content type of the data. For non-JSON/text data, binary files are returned and the path to the downloaded file. For JSON/text files, a Python dictionary or a string. All others will be a byte array, that can be converted to string using data.decode(‘utf-8’). Zero byte files will return None.

get_thumbnail()

The get_thumbnail method retrieves the bytes that make up the thumbnail for this item.

Returns:

Bytes that represent the item’s thumbnail.

Example

>>> response = item.get_thumbnail()
>>> f = open(filename, 'wb')
>>> f.write(response)

get_thumbnail_link()

The get_thumbnail_link method is similar to the get_thumbnail method, but retrieves the link to the item’s thumbnail rather than the bytes that make up the thumbnail for this item.

Returns:

The link to the item’s thumbnail.

property homepage

The homepage property gets the URL to the HTML page for the item.

property item_card

Returns an XML representation of the Item

Returns:

A string path to the downloaded XML file.

property metadata

The metadata property gets and sets the item metadata for the specified item. metadata returns None if the item does not have metadata.

Note

Items with metadata have ‘Metadata’ in their typeKeywords.

move(folder)

The move method moves the current item to the name of the folder passed when move is called.

Parameter	Description
folder	Required string. The name of the folder to move the item to. Use ‘/’ for the root folder. For other folders, pass in the folder name as a string, or a dictionary containing the folder ID, such as the dictionary obtained from the folders property.

Returns:

A json object in the following format: { “success”: true | false, “itemId”: “<item id>”, “owner”: “<owner username>”, “folder”: “<folder id>” }

# Usage Example

>>> item.move("C:\Projects\ARCGIS\ArcGis_data")

package_info(folder=None)

Items will have a package info file available only if that item is an ArcGIS package (for example, a layer package or map package). It contains information that is used by clients (ArcGIS Pro, ArcGIS Explorer, and so on) to work appropriately with downloaded packages. Navigating to the URL will result in a package info file (.pkinfo) being downloaded.

Parameter	Description
folder	Optional string. The save location of the pkinfo file.

Returns:

str

protect(enable=True)

The protect method enables or disables delete protection on this item, essentially allowing the item to be deleted or protecting it from deletion.

Parameter	Description
enable	Optional boolean. Default is True which enables delete protection, False to disable delete protection.

Returns:

A json object in the following format: {“success”: true | false}

property proxies

The proxies property gets the ArcGIS Online hosted proxy services, set on a registered app, item with the Registered App type keyword. Additionally, this resource is only available to the item owner and the organization administrator.

publish(publish_parameters=None, address_fields=None, output_type=None, overwrite=False, file_type=None, build_initial_cache=False, item_id=None, geocode_service=None, future=False)

The publish method is used to publish a hosted service based on an existing source item (this item). Publishers can then create feature, tiled map, vector tile and scene services. Feature services can be created from input files of various types, including

1. csv files

2. shapefiles

3. service definition files

4. feature collection files

5. file geodatabase files

CSV files that contain location fields (i.e. address fields or XY fields) are spatially enabled during the process of publishing. Shapefiles and file geodatabases should be packaged as *.zip files.

Tiled map services can be created from service definition (*.sd) files, tile packages, and existing feature services.

Vector tile services can be created from vector tile package (*.vtpk) files.

Scene services can be created from scene layer package (*.spk, *.slpk) files.

Service definitions are authored in ArcGIS Pro or ArcGIS Desktop and contain both the cartographic definition for a map as well as its packaged data together with the definition of the geo-service to be created.

Note

ArcGIS does not permit overwriting if you published multiple hosted feature layers from the same data item.

Note

ArcGIS for Enterprise for Kubernetes does not support publishing service definition file generated by ArcMap.

Parameter	Description
publish_parameters	Optional dictionary. containing publish instructions and customizations. Cannot be combined with overwrite. See Publish Item in the ArcGIS REST API for details.
address_fields	Optional dictionary. containing mapping of df columns to address fields,
output_type	Optional string. Only used when a feature service is published as a tile service.
overwrite	Optional boolean. If True, the hosted feature service is overwritten. Only available in ArcGIS Enterprise 10.5+ and ArcGIS Online.
file_type	Optional string. Some formats are not automatically detected, when this occurs, the file_type can be specified: serviceDefinition, shapefile, csv, excel, tilePackage, featureService, featureCollection, fileGeodatabase, geojson, scenepackage, vectortilepackage, imageCollection, mapService, and sqliteGeodatabase are valid entries. This is an optional parameter.
build_initial_cache	Optional boolean. The boolean value (default False), if true and applicable for the file_type, the value will built cache for the service.
item_id	Optional string. Available in ArcGIS Enterprise 10.8.1+. Not available in ArcGIS Online. This parameter allows the desired item id to be specified during creation which can be useful for cloning and automated content creation scenarios. The specified id must be a 32 character GUID string without any special characters. If the item_id is already being used, an error will be raised during the publish process.
geocode_service	Optional Geocoder. When publishing a table of data, an optional Geocoder can be supplied in order to specify which service geocodes the information. If no geocoder is given, the first registered Geocoder is used.
future	Optional Boolean indicating whether to run the operation in an asynchronous manner. When True, the return value is a concurrent.futures.Future object that can be queried for job status and results. The default is False.

Returns:

When future=False, an Item object corresponding to the published web layer. When future=True, a concurrent.futures.Future object.

# Publishing a Hosted Table Example

>>> csv_item = gis.content.get('<csv item id>')
>>> analyzed = gis.content.analyze(item=csv_item, file_type='csv')
>>> publish_parameters = analyzed['publishParameters']
>>> publish_parameters['name'] = 'AVeryUniqueName' # this needs to be updated
>>> publish_parameters['locationType'] = "none" # this makes it a hosted table
>>> published_item = csv_item.publish(publish_parameters)

# Publishing a Tile Service Example

>>> item.publish(address_fields= { "CountryCode" : "Country"},
>>>               output_type="Tiles",
>>>               file_type="CSV",
>>>               item_id=9311d21a9a2047d19c0faaebd6f2cca6
>>>             )

Note

For publish_parameters, see Publish Item in the ArcGIS REST API for more details.

property rating

Get/Set the rating given by the current user to the item. Set adds a rating to an item to which you have access - Only one rating can be given to an item per user. If this call is made on a currently rated item, the new rating will overwrite the existing rating. A user cannot rate their own item. Available only to authenticated users.

Parameter	Description
value	Required float. The rating to be applied for the item. The value must be a floating point number between 1.0 and 5.0.

reassign_to(target_owner, target_folder=None)

The reassign_to method allows the administrator to reassign a single item from one user to another.

Note

If you wish to move all of a user’s items (and groups) to another user then use the user.reassign_to() method. The item.reassign_to method (this method) only moves one item at a time.

Parameter	Description
target_owner	Required string or User. The string must be a username value.
target_folder	Optional string. The folder title to move the item to.

Returns:

A boolean indicating success (True) with the ID of the reassigned item, or failure (False).

# Usage Example

>>> item.reassign_to("User1234")

register(app_type, redirect_uris=None, http_referers=None, privileges=None)

The register method registers an app item with the enterprise, resulting in an APPID and APPSECRET (also known as client_id and client_secret in OAuth speak, respectively) being generated for that app. Upon successful registration, a Registered App type keyword gets appended to the app item.

Note

The register method is available to the item owner.

Parameter	Description
app_type	Required string. The type of app that was registered indicating whether it’s a browser app, native app, server app, or a multiple interface app. Values: browser, native, server, or multiple
redirect_uris	Optional list. The URIs where the access_token or authorization code will be delivered upon successful authorization. The redirect_uri specified during authorization must match one of the registered URIs, otherwise authorization will be rejected. A special value of urn:ietf:wg:oauth:2.0:oob can also be specified for authorization grants. This will result in the authorization code being delivered to a portal URL (/oauth2/approval). This value is typically used by apps that don’t have a web server or a custom URI scheme where the code can be delivered. The value is a JSON string array.
http_referers	Optional List. A list of the http referrers for which usage of the APIKey will be restricted to. Note Http Referrers can be configured for non apiKey type apps as well. The list configured here will be used to validate the app tokens sent in while accessing the sharing API. The referrer checks will not be applied to user tokens.
privileges	Optional List. A list of the privileges that will be available for this APIKey. Note Privileges can be configured for non API Key type apps as well. The list configured here will be used to grant access to items when item endpoint is accessed with app tokens. The checks will not be applied to user tokens and they can continue accessing items based on the current item sharing model. With app tokens, all items of app owner can be accessed if the privileges list is not configured.

Returns:

A dictionary indicating ‘success’ or ‘error’

# Usage Example

>>> item.register(app_type = "browser",
>>>             redirect_uris = [ "https://app.example.com", "urn:ietf:wg:oauth:2.0:oob" ],
>>>             http_referers = [ "https://foo.com", "https://bar.com" ],
>>>            privileges = ["portal:apikey:basemaps", "portal:app:access:item:itemId",
>>>                         "premium:user:geocode", "premium:user:networkanalysis"]
                  )

related_items(rel_type, direction='forward')

The related_items method retrieves the items related to this item. Relationships can be added and deleted using item.add_relationship() and item.delete_relationship(), respectively.

Note

With WebMaps items, relationships are only available on local enterprises.

Parameter	Description
rel_type	Required string. The type of the related item; is one of [‘Map2Service’, ‘WMA2Code’, ‘Map2FeatureCollection’, ‘MobileApp2Code’, ‘Service2Data’, ‘Service2Service’]. See Relationship Types in the REST API help for more information on this parameter.
direction	Required string. One of [‘forward’, ‘reverse’]

Returns:

The list of related items.

# Usage Example

>>> item.related_items("Service2Service", "forward")

remap_data(item_mapping, force=False)

Method to help users easily replace data in web maps, applications, and other item types that may contain references to other items. Users pass in a dictionary of item ids specifying the original item id and the item id of the item meant to replace it, and the function will automatically replace the id’s and other associated data with the item. Useful for workflows such as replacing corrupted datasources in an application with valid ones, updating outdated datasources, replacing test data with production data, and more. Can be used by advanced users to replace any string in the item’s structure.

Parameter	Description
item_mapping	Required dict. A dictionary of the items to be remapped. The key is the item id of the original item and the value is the item id of the item meant to replace the original. Note This dictionary can also be used for regex replacements of other strings that are in the structure of the item (not just item id’s), but only if the force parameter is set to True. This is only recommended for advanced users with a thorough understanding of their item’s data structure.
force	Optional boolean. If False, the function will check if the item ids in the item_mapping dictionary exist correspond to valid, accessible items item in the GIS, and that all original/replacement item pairs are of matching type. If True, the function will not check and replace all instances of the item_mapping keys with their corresponding values in the item’s data. Default is False, is strongly recommended to remain False unless the user has a specific reason to circumvent item id validation.

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example 1: Replace web maps within an application

storymap = gis.content.get("storyid12345")

# say we have a webmap with id 'webmapid12345' and want to replace it with another
map_dict = {"webmapid12345": "webmapid67890"}
storymap.remap_data(map_dict)

# Usage Example 2: Fix a typo everywhere in an item

dashboard = gis.content.get("dashboardid12345")

# say we realized we've been spelling "arcgis" wrong this whole time
repl_dict = {"arkgis": "arcgis"}
dashboard.remap_data(repl_dict, force=True)

property resources

The resources property returns the Item’s Resource Manager

Returns:

A ResourceManager object

share(everyone=False, org=False, groups=None, allow_members_to_edit=False)

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

The share method allows you to set the list of groups the Item will be shared with. You can also set the Item to be shared with your org or with everyone(public including org).

Parameter	Description
everyone	Optional boolean. If True, this item will be shared with everyone, meaning that it will be publicly accessible and available to users outside of the organization. If set to False (default), the item will not be shared with the public.
org	Optional boolean. If True, this item will be shared with the organization. If set to False (default), the item will not be shared with the organization.
groups	Optional list of group ids as strings, or a list of arcgis.gis.Group objects. Default is None, don’t share with any specific groups.
allow_members_to_edit	Optional boolean. Set to True when the item will be shared with groups with item update capability so that any member of such groups can update the item that is shared with them.

Returns:

A dictionary with a key titled “notSharedWith”,containing array of groups with which the item could not be shared as well as “itemId” key containing the item id.

# Usage Example

>>> item.share(org = True, allow_members_to_edit = True)

property shared_with

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

The shared_with property reveals the privacy or sharing status of the current item. An item can be private or shared with one or more of the following:

1. A specified list of groups

2. All members in the organization

3. Everyone (including anonymous users).

Note

If the return is False for org, everyone and contains an empty list of groups, then the item is private and visible only to the owner.

Returns:

A Dictionary in the following format: { ‘groups’: [], # one or more Group objects ‘everyone’: True | False, ‘org’: True | False }

property sharing

The sharing property accesses a SharingManager object to allow users and administrators to control how the current Item is shared throughout the GIS.

Returns:

SharingManager

# Usage example:
>>> gis = GIS(profile="your_organization_admin_profile")

>>> an_item = gis.content.get("<item_id>")
>>> sharing_mgr = an_item.sharing
>>> sharing_mgr

< <item_id> SharingManager >

property snapshots

The snapshots property provides access to the Notebook Item’s Snapshots. If the user is not the owner of the Item, the snapshots will be an empty list.

Returns:

List[SnapShot]

status(job_id=None, job_type=None)

The status method provides the status of an Item in the following situations:

1. Publishing an Item

2. Adding an Item in async mode

3. Adding with a multipart upload. Partial is available for Add Item Multipart when only a part is uploaded and the Item object is not committed.

Parameter	Description
job_id	Optional string. The job ID returned during publish, generateFeatures, export, and createService calls.
job_type	Optional string. The type of asynchronous job for which the status has to be checked. Default is none, which checks the item’s status. This parameter is optional unless used with the operations listed below. Values: publish, generateFeatures, export, and createService

Returns:

The status of a publishing Item object.

# Usage Example

>>> item.status(job_type="generateFeatures")

unregister()

The unregister property removes the application registration from an app Item, along with the Registered App type keyword.

Note

The unregister method is available to the item owner and organization administrators.

Returns:

A boolean indicating success (True), or failure (False)

unshare(groups)

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

Deprecated since version 2.3.0: Removed in: 3.0.0. Use Item.sharing instead.

The unshare method stops sharing of the Item with the specified list of groups.

Parameter	Description
groups	Optional list of group names as strings, or a list of Group objects, or a comma-separated list of group IDs.

Returns:

A Dictionary containing the key notUnsharedFrom containing array of groups from which the item could not be unshared.

update(item_properties=None, data=None, thumbnail=None, metadata=None)

The update method updates an item in a Portal.

Note

The content can be a file (such as a layer package, geoprocessing package, map package) or a URL (to an ArcGIS Server service, WMS service, or an application).

To upload a package or other type of file, a path or URL to the file must be provided in the data argument.

For item_properties, pass in arguments for only the properties you want to be updated. All other properties will be untouched. For example, if you want to update only the item’s description, then only provide the description argument in item_properties.

Parameter	Description
item_properties	Required dictionary. See table below for the keys and values.
data	Optional string, io.StringIO, or io.BytesIO. Either a path or URL to the data or an instance of StringIO or BytesIO objects.
thumbnail	Optional string. Either a path or URL to a thumbnail image.
metadata	Optional string. Either a path or URL to the metadata.

Key:Value Dictionary Options for Argument item_properties

Key	Value
type	Optional string. Indicates type of item, see the link below for valid values.
typeKeywords	Optional string. Provide a lists all sub-types, see the link below for valid values.
description	Optional string. Description of the item.
title	Optional string. Name label of the item.
url	Optional string. URL to item that are based on URLs.
tags	Optional string. Tags listed as comma-separated values, or a list of strings. Used for searches on items.
text	Optional string. For text based items such as Feature Collections & WebMaps
snippet	Optional string. Provide a short summary (limit to max 250 characters) of the what the item is.
extent	Optional string. Provide comma-separated values for min x, min y, max x, max y.
spatialReference	Optional string. Coordinate system that the item is in.
accessInformation	Optional string. Information on the source of the content.
licenseInfo	Optional string. Any license information or restrictions regarding the content.
culture	Optional string. Locale, country and language information.
access	Optional string. Valid values are private, shared, org, or public.

Note

See Items and Item Types in the ArcGIS REST API documentation for more details.

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example

>>> item.update(item_properties = {"description":"Boundaries and infrastructure for Warren County",
                                    "title":"Warren County Feature Layer",
                                    "tags":"local government, administration, Warren County"
                                   })

update_info(file, folder_name=None)

You can upload JSON, XML, CFG, TXT, PBF, and PNG files only. The file size limit is 100K. The uploaded file is also available through the https://item-url/info/filename resource.

Must be the owner of the item to update this.

Parameter	Description
file	Required String. The path to the file that will be uploaded.
folder_name	Optional String. The name of the subfolder for added information.

Returns:

Success or Failure

update_thumbnail(file_path=None, encoded_image=None, file_name=None, url=None)

The update_thumbnail updates the thumbnail of any ArcGIS item in your organization. The updated thumbnail can be provided in a variety of formats, as either a file to be uploaded as part of a multipart request, a direct URL to the thumbnail file, or as a Base64 encoded image.

Parameter	Description
file_path	Optional String. The local path to the thumbnail.
encoded_image	Optional String. A base64 encoded image as a string.
file_name	Optional String. This is required with encoded_image is used. It is the name of the file with extension. Example thumbnail.png
url	Optional String. A URL location of a thumbnail.

# Usage Example 1: Using a base64 encoded image

gis = GIS(profile='your_profile')
item = gis.content.get(<item id>)
base64_img = (
    'data:image/png;base64,'
    'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAA'
    'LEwEAmpwYAAAB1klEQVQ4jY2TTUhUURTHf+fy/HrjhNEX2KRGiyIXg8xgSURuokX'
    'LxFW0qDTaSQupkHirthK0qF0WQQQR0UCbwCQyw8KCiDbShEYLJQdmpsk3895p4aS'
    'v92ass7pcfv/zP+fcc4U6kXKe2pTY3tjSUHjtnFgB0VqchC/SY8/293S23f+6VEj'
    '9KKwCoPDNIJdmr598GOZNJKNWTic7tqb27WwNuuwGvVWrAit84fsmMzE1P1+1TiK'
    'MVKvYUjdBvzPZXCwXzyhyWNBgVYkgrIow09VJMznpyebWE+Tdn9cEroBSc1JVPS+'
    '6moh5Xyjj65vEgBxafGzWetTh+rr1eE/c/TMYg8hlAOvI6JP4KmwLgJ4qD0TIbli'
    'TB+sunjkbeLekKsZ6Zc8V027aBRoBRHVoduDiSypmGFG7CrcBEyDHA0ZNfNphC0D'
    '6amYa6ANw3YbWD4Pn3oIc+EdL36V3od0A+MaMAXmA8x2Zyn+IQeQeBDfRcUw3B+2'
    'PxwZ/EdtTDpCPQLMh9TKx0k3pXipEVlknsf5KoNzGyOe1sz8nvYtTQT6yyvTjIax'
    'smHGB9pFx4n3jIEfDePQvCIrnn0J4B/gA5J4XcRfu4JZuRAw3C51OtOjM3l2bMb8'
    'Br5eXCsT/w/EAAAAASUVORK5CYII='
)
res = item.update_thumbnail(encoded_image=base64_img, file_name="thumbnail.png")

# Usage Example 2: URL image

gis = GIS(profile='your_profile')
item = gis.content.get(<item id>)
img_url = "https://www.esri.com/content/dam/esrisites/en-us/common/icons/product-logos/ArcGIS-Pro.png"
res = item.update_thumbnail(url=img_url)

# Usage Example 3: Using a local file

gis = GIS(profile='your_profile')
item = gis.content.get(<item id>)
fp = "c:/images/ArcGIS-Pro.png"
res = item.update_thumbnail(file_path=fp)

Returns:

bool

usage(date_range='7D', as_df=True)

Note

The usage method is available for ArcGIS Online Only.

For item owners and administrators, the usage method provides usage details about an item that help you gauge its popularity. Usage details show how many times the item has been used for the time period you select. Historical usage information is available for the past year. Depending on the item type, usage details can include the number of views, requests, or downloads, and the average number of views, requests, or downloads per day.

Views refers to the number of times the item has been viewed or opened. For maps, scenes, non-hosted layers, and web apps, the view count is increased by one when you open the item page or open the item in Map Viewer. For example, if you opened the item page for a map image layer and clicked Open in Map Viewer, the count would increase by two. For other items such as mobile apps, KML, and so on, the view count is increased by one when you open the item; the count does not increase when you open the item details page.

For hosted web layers (feature, tile, and scene), the number of requests is provided instead of views. Requests refers to the number of times a request is made for the data within the layer. For example, someone might open an app that contains a hosted feature layer. Opening the app counts as one view for the application, but multiple requests may be necessary to draw all the features in the hosted layer and are counted as such.

For downloadable file item types such as CSV, SHP, and so on, the number of downloads is displayed. For registered apps, the Usage tab also displays the number of times users have logged in to the app. Apps that allow access to subscriber content through the organization subscription show usage by credits. Additionally, the time frame for the credit usage reporting period can be changed.

Parameter	Description
date_range	Optional string. The default is 7d. This is the period to query usage for a given item. 24H Past 24 hours 7D Past 7 days (default) 14D Past 14 days 30D Past 30 days 60D Past 60 days 6M Past 6 months 1Y Past 12 months (date1,date2) Tuple of 2 datetime objects defining custom date range
as_df	Optional boolean. Returns a Pandas DataFrame when True, returns data as a dictionary when False

Returns:

Pandas DataFrame or Dictionary

# Usage Example #1: Standard date_range

>>> flyr_item = gis.content.get("8961540a52da402876e0168fa29bb82d")
>>> result = flyr_item.usage(date_range = "7D")
    Date  Usage
0 2022-08-05      0
1 2022-08-06      0
2 2022-08-07      0
3 2022-08-08      0
4 2022-08-09      0
5 2022-08-10      0
6 2022-08-11      0
7 2022-08-12      8

# Usage Example #2: Custom date_range

>>> import datetime as dt

>>> flyr_item = gis.content.get("8961540a52da402876e0168fa29bb82d")
>>> date_1 = dt.datetime(2022,7,31)
>>> date_2 = dt.datetime.now(2022,8,12)
    # Early value, later value
>>> result = flyr_item.usage(date_range = (date_1, date_2))
>>> result
         Date  Usage
0  2022-07-31      0
1  2022-08-01      0
2  2022-08-02      0
3  2022-08-03      0
4  2022-08-04      0
5  2022-08-05      0
6  2022-08-06      0
7  2022-08-07      0
8  2022-08-08      0
9  2022-08-09      0
10 2022-08-10      0
11 2022-08-11      0
12 2022-08-12     10

property view_manager

If the Item is a Feature Service and a Hosted Service, the Item can have views. This Manager allows users to work with Feature Service to create views

Returns:

A ViewManager object to administer hosted feature layer view items created from the hosted feature layer.

Bases: object

Manages the sharing operations for an Item.

This class is not meant to be initialized directly. An instance of a SharingManager is available through the sharing property of an item.

# Usage example:
>>> gis = GIS(profile="your_organization_profile", verify_cert=False)

>>> test_item = gis.content.get("4976ad...b9583e")
>>> sharing_mgr = test_item.sharing

< "4976ad...b9583e" SharingManager >

>>> type(sharing_mgr)

<class 'arcgis.gis._impl._content_manager.sharing.api.SharingManager'>

property groups

Provides access to a SharingGroupManager object to manage the group sharing properties of the Item from which the SharingManager was initialized

Returns:

SharingGroupManager object

property shared_with

The shared_with property reveals the sharing status with groups and the sharing level of the Item. An item can be private to its owner, or shared in one or more of the following ways:

• to a specified list of groups

• to all members in the organization

• to everyone (including anonymous users), aka publicly

Returns:

dict[str,Any]. A dictionary describing the sharing level.

# Usage example: Item only visible to the owner.

>>> from arcgis.gis import GIS
>>> gis = GIS(profile="your_organization_profile")

>>> data_item = gis.content.get("269029...2c482e")
>>> data_item.sharing.shared_with

{'groups': [], 'level': <SharingLevel.PRIVATE: 'PRIVATE'>}

property sharing_level

Gets or sets the sharing level of the Item.

Returns:

SharingLevel enumeration instance.

# Usage example: Setting the sharing level to organization
>>> from arcgis.gis import GIS
>>> from arcgis.gis._impl._content_manager import SharingLevel

>>> data_item = gis.content.search(query="Hurricanes 2022")
>>> sharing_mgr = data_item.sharing
>>> sharing_mgr.sharing_level

<SharingLevel.PRIVATE: 'PRIVATE'>

>>> sharing_mgr.sharing_level = SharingLevel.ORG

>>> sharing_mgr.sharing_level
<SharingLevel.ORG: 'ORGANIZATION'>

>>> type(sharing_mgr.sharing_level)
<enum 'SharingLevel'>

Bases: object

This class controls the Group sharing for a specific Item.

Objects of this class are not meant to be intialized directly, but rather accessed through the groups property of an item’s SharingManager.

# Usage example:
>>> from arcgis.gis import GIS
>>> gis = GIS(profile="your_organization_profile")

>>> org_item = gis.content.get("<item_id>")
>>> item_sharing_mgr = org_item.sharing
>>> item_grp_sharing_mgr = item_sharing_mgr.groups
>>> item_grp_sharing_mgr

<<item_id> SharingGroupManager>

>>> type(item_grp_sharing_mgr)

<class 'arcgis.gis._impl._content_manager.sharing.api.SharingGroupManager'>

add(group)

Shares an Item with the Group entered as the group argument.

Parameter	Description
group	Required Group object to share the item with.

Returns:

Boolean value indicating the status of the operation.

# Usage example:
>>> from arcgis.gis import GIS
>>> gis = GIS(profile="your_organization_profile")

>>> org_item = gis.content.get("<item_id>")
>>> org_group = gis.groups.search("Storm Data Group")[0]

>>> item_sharing_mgr = org_item.sharing
>>> item_grp_sharing_mgr = item_sharing_mgr.groups
>>> item_grp_sharing_mgr.list()
[]

>>> item_grp_sharing_mgr.add(group=org_group)
True

>>> item_grp_sharing_mgr.list()
[<Group title:"Storm Data Group" owner:web_gis_user1>]

list()

Lists all the groups that the item is shared with.

Returns:

list[Group] A Python list of group objects.

remove(group)

Removes the item from the list of items shared with the Group entered as the group argument.

Parameter	Description
group	Required Group object with which the item will no longer be shared.

Returns:

Boolean value indicating the status of the operation.

Bases: object

Manage, monitor, and control Item dependencies.

Dependencies allow users to better understand the relationships between their organizational items. This class provides the users with the following:

• Warnings during item deletion if the deletion is going to break item/layer references in a web map or web application.

• Ability to explore the dependents and dependencies of a specific item.

• Administrator ability to efficiently update the URLs of their hosted/federated services in a single edit operation.

When an item is updated, its dependencies are updated as well and always be kept in sync.

add(depend_type, depend_value)

Assigns a dependency to the current item

Parameter	Description
depend_type	Required String. This is the type of dependency that is registered for the item. Allowed values: table url itemid serverId
depend_value	Required string. This is the associated value for the type above.

Returns:

Boolean

property properties

returns the dependencies properties

remove(depend_type, depend_value)

Deletes a dependency to the current item

Parameter	Description
depend_type	Required String. This is the type of dependency that is registered for the item. The allowed values are: table, url, or itemid.
depend_value	Required string. This is the associated value for the type above.

Returns:

Boolean

remove_all()

Revokes all dependencies for the current item

Returns:

Boolean

property to_dependencies

Returns a list of items that are dependent on the current Item

Bases: dict

The User class represents a registered user of the GIS system, either ArcGIS Online or ArcGIS Enterprise. The User class has a myriad of properties that are specific to a particular user - these properties are enumerated in the table below.

property bundles

The bundles method provides the current user’s assigned application bundles.

Note

The bundles method is available in ArcGIS Online and Portal 10.7+.

Returns:

A List of Bundle objects

delete(reassign_to=None)

The delete method deletes this user from the portal, optionally deleting or reassigning groups and items.

Note

You can not delete a user in Portal if that user owns groups or items and/or is assigned an application bundle. If you specify a user in the reassign_to argument, then items and groups will be transferred to that user. If that argument is not set, the method will fail provided the user has items or groups that need to be reassigned. Additionally, see the reassign_to method for more information on reassignment.

Parameter	Description
reassign_to	Optional string. The new owner of the items and groups that belong to the user being deleted.

# Usage Example

user.delete(reassign_to="User1234")

Returns:

A boolean indicating success (True) or failure (False).

delete_thumbnail()

The delete_thumbnail removes the thumbnail from the user’s profile.

Returns:

A boolean indicating success (True) or failure (False).

disable()

The disable method disables login access for the user.

Note

The disable method is only available to the administrator of the organization.

Returns:

A boolean indicating success (True) or failure (False).

download_thumbnail(save_folder=None)

The download_thumbnail method downloads the item thumbnail for this user and saves it in the folder that is passed when download_thumbnail is called.

Parameter	Description
save_folder	Optional string. The desired folder name to download the thumbnail to.

Returns:

The file path of the downloaded thumbnail.

enable()

The enable method enables login access for the user.

Note

enable is only available to the administrator of the organization.

property esri_access

The esri_access property will return a string describing the current user’s Esri access. When setting, supply a boolean to enable or disable esri_access for that User object.

Note

Administrator privileges are required to enable or disable Esri access

A member whose account has Esri access enabled can use My Esri and Community and Forums (GeoNet), access e-Learning on the Training website, and manage email communications from Esri. The member cannot enable or disable their own access to these Esri resources.

Warning

Trial accounts cannot modify esri_access property.

Please see the Enable Esri access section in the Manage members page in ArcGIS Online Resources for more information.

Parameter	Description
value	Required boolean. The current user will be allowed to use the username for other Esri/ArcGIS logins when the value is set to True. If false, the account can only be used to access a given individual’s organization.

expire_password(temporary_password=None)

Expires the current user’s Password.

Parameter	Description
temporary_password	Optional String. Allows the administrator to set a new temporary password for a given user. This is available on ArcGIS Enterprise Only.

Returns:

Boolean

property folders

The folders property, when called, retrieves the list of the user’s folders.

Returns:

List of folders represented as dictionaries. Dictionary keys include: username, folder id (id), title, and date created (created)

# Example to get name of all folders

user = User(gis, username)
folders = user.folders
for folder in folders:
    print(folder["title"])

# Example to get id of all folders

user = User(gis, username)
folders = user.folders
for folder in folders:
    print(folder["id"])

generate_direct_access_url(store_type, expiration=None, subfolder=None)

The generate_direct_access_url method creates a direct access URL that is ideal for uploading large files to datafile share, notebook workspaces or raster stores.

Parameter	Description
store_type	Optional String. The type of upload URL to generate. Types: big_data_file, ‘notebook’, or ‘raster`.
expiration	Optional Int. The expiration of the link in minutes. The default is 1440.
subfolder	Optional String. The folder to upload to. The default is None.

Returns:

A dictionary containing the direct access URL

# Usage Example

>>> user.generate_direct_access_url(store_type="notebook")

get_thumbnail()

The get_thumbnail method returns the bytes that make up the thumbnail for this user.

Returns:

Bytes that represent the image.

Usage Example:

response = user.get_thumbnail()
f = open(filename, 'wb')
f.write(response)

get_thumbnail_link()

The get_thumbnail_link method retrieves the URL to the thumbnail image.

Returns:

The thumbnail’s URL.

property groups

The groups property retrieves a List of Group objects the current user belongs to.

property homepage

The homepage property retrieves the URL to the HTML page for the user.

property invitations

Provides a list of invitations for a given user

Returns:

UserInvitationManager

items(folder=None, max_items=100)

The item method provides a list of Item objects in the specified folder. For content in the root folder, use the default value of None for the folder argument. For other folders, pass in the folder name as a string, or as a dictionary containing the folder ID, such as the dictionary obtained from the folders property.

Parameter	Description
folder	Optional string. The specifc folder (as a string or dictionary) to get a list of items in.
max_items	Optional integer. The maximum number of items to be returned. The default is 100.

Returns:

The list of Item objects in the specified folder.

# Example to **estimate** storage for a user's items

storage = 0
for item in user.items():
    storage += item.size
try:
    for f in user.folders:
        for f_item in user.folders(folder=f):
            storage += f_item.size
    print(f"{user.username} using {storage} bytes")
except Exception as e:
    print(f"{user.username} using {storage} bytes")

# Example get items in each folder that is not root

user = User(gis, username)
folders = user.folders
for folder in folders:
    items = user.items(folder=folder["title"])
    for item in items:
        print(item, folder)

property landing_page

Gets or sets the User’s login page,

Parameter	Description
value	Required string. The values are home, gallery, map, scene, groups, content, or organization

Returns:

str

# Usage example: Setting login page

>>> user1 = gis.users.get("org_data_viewer") # approach 1: set via landing_page

>>> user1.landing_page = "map"

>>> us = user.user_settings # approach 2: set via user_settings

>>> us['landingPage']['url'] = "webmap/viewer.html"

>>> user1.user_settings = us

link_account(username, user_gis)

The link_account method allows a user to link several accounts to gether and share information between them. For example, if you use multiple accounts for ArcGIS Online and Esri websites, you can link them so you can switch between accounts and share your Esri customer information with My Esri, e-Learning, and GeoNet. You can link your organizational, public, enterprise, and social login accounts. Your content and privileges are unique to each account. From Esri websites, only Esri access-enabled accounts appear in your list of linked accounts. See the unlink_account method for more information on how to unlink linked accounts that have been produced using the link_account method.

See the Sign in page in ArcGIS Online Resources for addtional information.

Parameter	Description
username	required string/User. This is the username or User object that a user wants to link to.
user_gis	required GIS. This is the GIS object for the username. In order to link an account, a user must be able to login to that account. The GIS object is the entry into that account.

# Usage Example

>>> gis = GIS("https://www.arcgis.com", "username1", "password123")
>>> user = gis.users.get('username')
>>> user.link_account("User1234", gis)

returns: A boolean indicating success (True) or failure (False).

property linked_accounts

The linked_accounts method retrieves all linked accounts for the current user as User objects

Returns:

A list of User objects

property notifications

The notifications property retrieves the list of notifications available for the given user.

Returns:

A list containing available notifications

property provisions

The provisions property returns a list of all provisioned licenses for the current user.

Note

The provisions method is only available in ArcGIS Enterprise 10.7+.

Returns:

A list contaning provisional licenses

reassign_to(target_username)

The reassign_to method reassigns all of this user’s items and groups to another user.

Items are transferred to the target user into a folder named <user>_<folder> where user corresponds to the user whose items were moved and folder corresponds to the folder that was moved.

Note

This method must be executed as an administrator. This method also can not be undone. The changes are immediately made and permanent.

Parameter	Description
target_username	Required string. The user who will be the new owner of the items and groups from which these are being reassigned from.

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example

>>> user.reassign_to(target_username="User1234")

property recyclebin

Provides access to the user’s recyclebin.

Note

This functionality is only available for ArcGIS Online.

Returns:

RecycleBin object

# Usage Example:
>>> gis = GIS(profile="your_online_user")

>>> my_user_obj = gis.users.me
>>> my_recy_bin = my_user_obj.recyclebin
>>> type(my_recy_bin)

<class 'arcgis.gis._impl._content_manager._recyclebin.RecycleBin'>

report(report_type, *, start_time=None, duration='weekly', time_aggregate=None)

The reports operation is to generate the reports of the overall usage of the organizations. Reports define organization usage metrics in one place for the day, week, or month. Administrators can monitor who is using which services, consuming how much credits and storage within certain time period. Reports also include current state of the organization such as number of items, groups, users, level 1s vs level 2s, App license assignments and public items.

Parameter	Description
report_type	Required String. The type of organizational report to generate. The allowed arguments are: credits content (does not honor start_time) users (does not honor start_time) activity serviceUsages itemUsages
start_time	Optional Datetime. The time from which the report generates information. If duration is weekly, the day component must evaluate to a Sunday or Monday UTC If duration is monthly, the day component must evaluate to the first of the month Note Values must be in the UTC timezone. If argument is not provided: and duration is either weekly or monthly, the report will generate from the closest Sunday. and duration is daily, the report will generate from the current day/time in UTC.
duration	Optional String. The time frame for which the reports are created. The allowed values are: monthly weekly daily - only available if report_type is activity yearly quarterly Note Argument is required when setting report_type argument to activity or credits. Note The yearly value is only available when reportSubType is set to itemUsages.
time_aggregate	Optional String. When the report_type is itemUsages, the records can be aggregated on specific time groups. These are day, week, or month.

# Usage Example #1

>>> import datetime as _dt
>>> from arcgis.gis import GIS

>>> gis = GIS(profile="your_online_admin_profile")

>>> org_users = gis.users.search("*")
>>> org_user = org_users[3]

>>> sept22 = _dt.datetime(2022, 9, 1, 16)

>>> content_report = org_user.report(report_type = "content",
                                     start_time = sept22,
                                     duration = "monthly")

# Usage Example #2
>>> sun_dec10 = _dt.datetime(2023, 12, 10, 17)

>>> activity_report = org_user.report(report_type = "activity",
                                      start_time = sun_dec10,
                                      duration = "weekly")

Returns:

class:

A CSV ~arcgis.gis.Item that can be downloaded.

reset(password=None, new_password=None, new_security_question=None, new_security_answer=None, reset_by_email=False)

The reset method resets a user’s password, security question, and/or security answer. If a new security question is specified, a new security answer should be provided.

Note

This function does not apply to those using enterprise accounts that come from an enterprise such as ActiveDirectory, LDAP, or SAML. It only has an effect on built-in users.

Note

To reset the password by email, set reset_by_email to True and password to None.

Parameter	Description
password	Required string. The current password.
new_password	Optional string. The new password if resetting password.
new_security_question	Optional string. The new security question if desired.
new_security_answer	Optional string. The new security question answer if desired.
reset_by_email	Optional Boolean. If True, the user will be reset by email. The default is False. NOTE: Not available with ArcGIS on Kubernetes.

Warning

This function does not apply to those using enterprise accounts that come from an enterprise such as ActiveDirectory, LDAP, or SAML. It only has an effect on built-in users.

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example

>>> user.reset("password123",new_password="passWORD1234",reset_by_email=True)

property tasks

The tasks property retrieves the users tasks, effectively serving as sesource manager for user’s tasks. See TaskManager for more information on task managers.

transfer_content(target_user, folder=None)

This operation transfers all the current user’s content to a new user. This is an asynchronous operation that can take up to 15 minutes to complete.

Parameter	Description
target_user	Required str or User. The user who will received the current user’s content.
folder	Optional str. The folder where the content is stored.

Returns:

concurrent.futures.Future

unlink_account(username)

The unlink_account method allows for the removal of linked accounts when a user wishes to no longer have a linked account. See the link_account method for more information on how accounts are linked together.

See the Sign in page in ArcGIS Online Resources for addtional information.

Parameter	Description
username	required string/User. This is the username or User object that a user wants to unlink.

# Usage Example

>>> user.unlink_account("User1234")

returns: A boolean indicating success (True) or failure (False).

update(access=None, preferred_view=None, description=None, tags=None, thumbnail=None, fullname=None, email=None, culture=None, region=None, first_name=None, last_name=None, security_question=None, security_answer=None, culture_format=None, categories=None)

The update method updates this user’s properties based on the arguments passed when calling update.

Note

Only pass in arguments for properties you want to update. All other properties will be left as they are. If you want to update the description, then only provide the description argument.

When updating the security question, you must provide a security_answer as well.

Parameter	Description
access	Optional string. The access level for the user, values allowed are private, org, public.
preferred_view	Optional string. The preferred view for the user, values allowed are Web, GIS, null.
description	Optional string. A description of the user.
tags	Optional string. Tags listed as comma-separated values, or a list of strings.
thumbnail	Optional string. The path or url to a file of type PNG, GIF, or JPEG. Maximum allowed size is 1 MB.
fullname	Optional string. The full name of this user, only for built-in users.
email	Optional string. The e-mail address of this user, only for built-in users.
culture	Optional string. The two-letter language code, fr for example.
region	Optional string. The two-letter country code, FR for example.
first_name	Optional string. User’s first name.
last_name	Optional string. User’s first name.
security_question	Optional integer. The is a number from 1-14. The questions are as follows: What city were you born in? What was your high school mascot? What is your mother’s maden name? What was the make of your first car? What high school did you got to? What is the last name of your best friend? What is the middle name of your youngest sibling? What is the name of the street on which your grew up? What is the name of your favorite fictional character? What is the name of your favorite pet? What is the name of your favorite restaurant? What is the title of your facorite book? What is your dream job? Where did you go on your first date? Usage Example: security_question=13
security_answer	Optional string. This is the answer to security question. If you are changing a user’s question, an answer must be provided. Usage example: security_answer=”Working on the Python API”
culture_format	Optional String. Specifies user-preferred number and date format
categories	Optional List[str]. A list of category names. example: `categories = ["category11", "category12"]`

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example

>>> user.update(description="Aggregated US Hurricane Data", tags = "Hurricanes,USA, 2020")

update_level(level)

The update_level allows administrators of an organization to update the level of a user. Administrators can leverage two levels of membership when assigning roles and privileges to members. Membership levels allow organizations to control access to some ArcGIS capabilities for some members while granting more complete access to other members.

Note

Level 1 membership is designed for members who need privileges to view and interact with existing content, while Level 2 membership is for those who contribute, create, and share content and groups, in addition to other tasks.

Maximum user quota of an organization at the given level is checked before allowing the update.

Built-in roles including organization administrator, publisher, and user are assigned as Level 2, members with custom roles can be assigned as Level 1, 1PlusEdit, or Level 2.

Level 1 membership allows for limited capabilities given through a maximum of 8 privileges: portal:user:joinGroup, portal:user:viewOrgGroups, portal:user:viewOrgItems, portal:user:viewOrgUsers, premium:user:geocode, premium:user:networkanalysis, premium:user:demographics, and premium:user:elevation. If updating the role of a Level 1 user with a custom role that has more privileges than the eight, additional privileges will be disabled for the user to ensure restriction.

Note

Level 1 users are not allowed to own any content or group which can be reassigned to other users through the Reassign Item and Reassign Group operations before downgrading them. The operation will also fail if the user being updated has got licenses assigned to premium apps that are not allowed at the targeting level.

Parameter	Description
level	Required int. The values of 1 or 2. This is the user level for the given user. 1 - View only 2 - Content creator

Returns:

A boolean indicating success (True) or failure (False).

# Usage Example

>>> user.update_level(2)

update_license_type(user_type)

The update_license_type method is primarily used to update the user’s licensing type. This allows administrators to change a user from a creator to a viewer or any other custom user license type.

Note

The update_license_type method is available in ArcGIS Online and Portal 10.7+.

Parameter	Description
user_type	Required string. The user license type to assign a user. Built-in Types: creator or viewer

Returns:

A boolean indicating success (True) or failure (False).

update_role(role)

The update_role method updates this user’s role to org_user, org_publisher, org_admin, viewer, view_only, viewplusedit, or a custom role.

Note

There are four types of roles in Portal - user, publisher, administrator and custom roles. A user can share items, create maps, create groups, etc. A publisher can do everything a user can do and additionally create hosted services. An administrator can do everything that is possible in Portal. A custom roles privileges can be customized.

Parameter	Description
role	Required string. Value must be either org_user, org_publisher, org_admin, viewer, view_only, viewplusedit or a custom role object (from gis.users.roles).

Returns:

A boolean indicating success (True) or failure (False).

property user_settings

Get/set the current user’s settings that are defined in the user profile.

Parameter	Description
value	Required dict. The landingPage and appLauncher settings.

Returns:

dict

# Usage example: Getting the current user settings

>>> us = user.user_settings # similar to setting the landing_page property

>>> us['landingPage']['url'] = "webmap/viewer.html"

>>> user1.user_settings = us

user_types()

The user_types method is used to retrieve the user type and any assigned applications of the user.

Note

The user_types method is available in Portal 10.7+.

Bases: dict

The Group class is an object that represents a group within the GIS, either ArcGIS Online or ArcGIS Enterprise.

add_users(usernames=None, admins=None)

The adds_users method adds users to this group.

Note

The add_users method will only work if the user for the Portal object is either an administrator for the entire Portal or the owner of the group.

Parameter	Description
usernames	Optional list of strings or single string. The list of usernames or single username to be added.
admins	Optional List of String, or Single String. This is a list of users to be an administrator of the group.

Returns:

A dictionary containing the users that were not added to the group.

# Usage Example

>>> group.add_users(usernames=["User1234","User5678"], admins="Admin9012")

application(user)

The application method retrieves one group application for the given group.

Parameter	Description
user	Required String. The username of the user applying to join the group.

Note

The application method is available to administrators of the group or administrators of an organization if the group is part of one.

property applications

The applications property retrieves the group applications for the given group as a list.

Note

The applications method is available to administrators of the group or administrators of an organization if the group is part of one.