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="/path/to/mycert.pfx", password="password1")

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

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

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

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

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

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

# Usage Example 11: Using a CA_BUNDLE specifying multiple SSL certificates
certs = [r"./CA_CERTS/cacert.pem", r"./CA_CERTS/cacert2.pem", ..., r"./CA_CERTS/cacertN.pem"]
gis = GIS(profile="your_enterprise_admin_profile", ca_bundles=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: list

Provides access to representation of all the services running on the hosting server for an organizational deployment. See ArcGIS Server Services Directory REST API for full explanation.

Returns:

• ArcGIS Online: list of AGOLServicesDirectory objects

• ArcGIS Enterprise and ArcGIS Enterprise on Kubernetes: list of ServicesDirectory objects.

# Usage Example #1: ArcGIS Online:
>>> from arcgis.gis import GIS
>>> gis = GIS(profile="your_online_admin_profile")

>>> svc_directory_list = gis.hosting_servers
>>> for svc_dir in svc_directory_list:
>>>     print(f"{svc_dir}")

< AGOLServicesDirectory @ https://servicesX.arcgis.com/<org_id>/arcgis/rest/services >
< AGOLServicesDirectory @ https://tiles.arcgis.com/tiles/<org_id>/arcgis/rest/services >

# Usage Example #2: ArcGIS Enterprise:
>>> gis = GIS(profile="your_enterprise_admin_profile")

>>> for svc_dir in gis.hosting_servers:
>>>     print(f"{svc_dir}")

< ServicesDirectory @ https://example.org_url.com/web_adaptor_name/rest/services >

property hub

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

property languages: list[dict[str, Any]]

Lists the available languages.

Returns:

List[Dict[str, Any]]

map(location: str | None = None, mode: str = '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 geocoder. Provided a match is found, the geographic extent of the matched address is used as the extent of the map. 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: list['NotebookServer'] | list['AGOLNotebookManager']

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.

To see all the properties that can be found in the GIS object, refer to the portal properties documentation at Portal Properties.

Returns:

A dictionary-like object called a PropertyMap of the properties of the GIS object.

property regions: list[dict[str, Any]]

Lists the available regions.

Returns:

List[Dict[str, Any]]

property servers: dict

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

Returns:

dict

property session: EsriSession

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

Returns the ArcGIS Online Subscription Information for a Site.

Returns:

dictionary

property symbol_service: SymbolService | None

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: dict[str, Any])

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: str)

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: Item, rel_type: str)

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 attachments_size: int | None

The attachments_size property returns the total size of the attachments for the item. The item has to support this property.

Note

The size is returned in bytes. To get the size in megabytes, divide the size by 1024*1024. This is only supported for ArcGIS Online.

Returns:

The size in bytes.

property can_delete: bool

Checks if the Item can be removed from the system.

Returns:

bool

can_reassign(target_user: str | User) → tuple[bool, dict[str, Any]]

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 org_authoritative public_authoritative deprecated Note See Organization verification for requirements to use public_authoritative status. Also, authoritative will be converted to org_authoritative status.

#Usage Example: Setting status to org_authoritative:

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

>>> dep_item = gis.content.get("<item_id>")
>>> dep_item.content_status = "org_authoritative"
>>> print(dep_item.content_status)

org_authoritative

copy(title: str | None = None, tags: list[str] | str | None = None, snippet: str | None = None, description: str | None = None, layers: list[int] | None = 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: str, layers: list[int] | str | None = None, tables: list[int] | str | None = None, folder: str | None = None, description: str | None = None, snippet: str | None = None, owner: str | User | None = 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: str | None = None, tags: list[str] | str | None = None, folder: str | None = None, include_resources: bool = False, include_private: bool = 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: bool = 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: str, min_scale: float, max_scale: float, cache_info: dict[str, Any] | None = None, build_cache: bool = False, *, extent: list[float] | None = None)

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. This is the furthest zoom level out that a layer will display. Note This number should be larger than max_scale.
max_scale	Required float. The largest scale at which to view data. This is is the furthest zoom level in that a layer will display. Note This number should be less than min_scale. See Note on scale properties for more information.
cache_info	Optional dictionary defining the tiling scheme. See Map caching for full details, including information on defining a scheme. Note If none provided, the cache defaults to the the ArcGIS Online tiling scheme.
build_cache	Required boolean. If not provided, True will be used. Note The cache will always be built if in ArcGIS Online.

Returns:

The Tile Layer Item object if successfully added, None if unsuccessful.

# Usage Example

>>> from arcgis.gis import GIS

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

>>> flyr_item = gis.content.get("<item id of feature layer>")
>>> tile_lyr_item = flyr_item.create_tile_service(
>>>                                 title="SeasideHeightsNJTiles",
>>>                                 min_scale=36978596,
>>>                                 max_scale=9244648
>>>                                 build_cache=True
>>>                                )

delete(force: bool = False, dry_run: bool = False, permanent: bool = 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: str)

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: Item, rel_type: str)

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() → bool

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: str | None = None, file_name: str | None = 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("/path/to/output", "hurricane_data")

download_metadata(save_folder: str | None = 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: str | None = 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: str, export_format: str, parameters: str | None = None, wait: bool = True, enforce_fld_vis: bool | None = None, tags: list[str] | str | None = None, snippet: str | None = None)

This method exports an Item to the format specified in the export_format argument.

Note

Only the item owner or a user with an administrator role can run this method, unless a Location Tracking Service or Location Tracking View is used.

This method is particularly useful for long running exports that could hold up a script since it can be run ansynchronously.

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 values: Shapefile CSV File Geodatabase Feature Collection GeoJson Scene Package KML Excel geoPackage Vector Tile Package
parameters	Optional string. A JSON object describing the layers to be exported and the export parameters for each layer. See the Export Item in the REST API for guidance on structuring the object. # Usage Example: Parameters object entered as string argument >>> import json >>> from arcgis.gis import GIS >>> flyr_item = gis.content.get("<feature_lyr_item_id>") >>> for flyr in flyr_item.layers: >>> print(f"{flyr.properties.id:<5}{flyr.properties.name}") 0 city_streets 1 city_river_boundary 3 city_parks >>> lyr_obj = { >>> "layers": [ >>> {"id": 3, "designated_owner": "County Parks and Rec"} >>> ] >>> } >>> lyr_str = json.dumps(lyr_obj) >>> export_output = flyr_item.export( >>> .... >>> parameters = lyr_str >>> )
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 all attribute columns are exported. If the operation is in a view, set this value to True to ensure only the view’s columns are exported. When 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: Export Feature Layer item to csv item

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

>>> hurricane_item = gis.content.search(
>>>                      query=f"Hurricane * AND owner:{gis.users.me.username}",
>>>                      type="Feature Layer",
>>>                      max_items=1
>>> )[0]

>>> hurrican_csv_item = hurricane_item.export(
>>>                       title="hurricane_src_data_item",
>>>                       export_format="CSV",
>>>                       wait=True,
>>>                       tags="Hurricane, Natural Disasters, source_content"
>>>                     )

property favorite: bool

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

generate_api_token(slot: int = 1, regenerate: bool = False, expiration: datetime | None = None) → dict

Generates a Developer Token from an Developer Token Item.

Parameter	Description
slot	Optional int. API keys support 2 API tokens. The slot allows users to specifiy which API Key to create or regenerate.
regenerate	Optional bool. When True, this will re-create the API token. The default is False.
expiration	Optional datetime.datetime. The time when the expiration expires. The maximum value is 1 year from the time you create the API Key.

Returns:

dict

get_data(try_json: bool = 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_dependencies(deep: bool = False, outside_org: bool = False, out_format: str = 'item')

Gets the dependencies of the Item. The method can return the immediate dependencies, meaning other items the item contains in its structure, or the full deep dependency list, which contains all items that must exist for the item to function, including dependencies of dependencies.

Note

Not all items/item types have dependencies.

Parameter	Description
deep	Optional boolean. When True, every item needed for the item to exist is contained in the result. When False, only immediate dependendencies of the item or those referenced directy within the item’s structure are in the results. Default is False.
outside_org	Optional boolean. When True, the output list will include items from outside the GIS. Default is True. When False, only items in the same organization as the item are returned.
out_format	Optional string. Determines the format of the output list. Options: item - results are Item objects id, - results are item id strings graph - result is an ~arcgis.apps.itemgraph.ItemGraph object. Default is item.

Returns:

A list containing the dependencies of the item either as items, item id values, or an ItemGraph.

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

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: str | Folder)

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

Parameter	Description
folder	Required string or Folder instance. The name of the folder to move the item to or the Folder class instance representing this folder. 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

>>> folder = gis.content.folders.get(folder="my folder")
>>> item.move(folder)

package_info(folder: str | None = None) → str

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: bool = 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: dict[str, Any] | None = None, address_fields: dict[str, str] | None = None, output_type: str | None = None, overwrite: bool = False, file_type: str | None = None, build_initial_cache: bool = False, item_id: str | None = None, geocode_service=None, future: bool = False) → Item | Future

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 files 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. A mapping of column names to address fields necessary for geocoding.
output_type	Optional string. Note Only used when a Feature Layer Item is published as a Tile Layer item. Options: tiles - For Tile Layer items sourced by Map Service vectorTiles - For Tile Layer items sourced by a Vector 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 as one of the below: serviceDefinition shapefile csv excel tilePackage featureService featureCollection fileGeodatabase geojson scenepackage vectortilepackage imageCollection mapService sqliteGeodatabase
build_initial_cache	Optional boolean. The boolean value. Default value is False, unless output_type argument is tiles or vectorTiles and publishing to ArcGIS Online. If True and applicable for the file_type, the cache will be built at time of publishing. Note Cache will always be built for Tile Layers for ArcGIS Online. See Map caching for full details on caching.
item_id	Optional string. 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. Note Available starting at ArcGIS Enterprise 10.8.1. Not available in ArcGIS Online. If the item_id is already being used, an error will be raised during the 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 whose result() method can be queried for result.

# 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 details on publish_parameters options, see Publish Item in the ArcGIS REST API documentation.

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: str | User, target_folder: str | None = 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: str, redirect_uris: list[str] | None = None, http_referers: list[str] | None = None, privileges: list[str] | None = None, personal_token: bool | None = 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.
personal_token	Optional Boolean. When providing privileges that relate to anything regarding operations on a user or administrative privileges, this must be set to true, or else the token will not be generated properly.

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: str, direction: str = '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: dict[str, str], force=False, **kwargs)

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

Returns a ResourceManager object for the Item

Returns:

A ResourceManager object

share(everyone: bool = False, org: bool = False, groups: list[Group] | list[str] | None = None, allow_members_to_edit: bool = 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: SharingManager

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

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: str | None = None, job_type: str | None = 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: list[str] | list[Group])

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: dict[str, Any] | None | ItemProperties = None, data: str | None = None, thumbnail: str | None = None, metadata: str | None = 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: str, folder_name: str | None = 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: str | None = None, encoded_image: str | None = None, file_name: str | None = None, url: str | None = None) → bool

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: str = '7D', as_df: bool = 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: ViewManager | None

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

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: dict[str, Any]

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

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, 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 initialized 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: Group | str) → bool

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() → list[Group]

Lists all the groups that the item is shared with.

Returns:

list[Group] A Python list of group objects.

remove(group) → bool

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: str, depend_value: str)

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: str, depend_value: str)

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