Using the GIS

The GIS object in the gis module is the most important object when working with the ArcGIS API for Python. The GIS object represents the GIS you are working with, be it ArcGIS Online or an instance of ArcGIS Enterprise. You use the GIS object to consume and publish GIS content and administrators may use it to manage GIS users, groups and datastores. This object becomes your entry point in your Python script when using the API.

To use the GIS object, import GIS from the arcgis.gis module:

from arcgis.gis import GIS

To create the GIS object, we pass in the url and our login credentials as shown below:

gis = GIS('home')

If connecting to an ArcGIS Enterprise in your premises, your URL becomes Your GIS can support a number of authentication schemes, refer to this section of the guide to know how to authenticate your scripts and notebooks for various such schemes.

Below, we're connecting to ArcGIS Online (the default GIS used when the url is not provided) as an anonymous user:

gis = GIS()

Adding a '?' mark after an object and querying it brings up help for that object in the notebook:


The notebook provides intellisense and code-completion. Typing a dot after an object and hitting tab brings up a drop-down with its properties and methods:

Helper objects

The GIS object provides helper objects to manage the GIS resources, i.e. the users, groups, content and datastores. These helper utilities are in the form of helper objects named: users, groups, content and datastore respectively. The helper utility for managing user roles named roles is available as a property on the helper object users.

Each such helper object has similar patterns of usage: there are methods to get(), search() and create() the respective resources.

The prescribed programming pattern is to not create the GIS resources (user, group, item, role, datastore) directly using their constructor, but to access them through their corresponding helper objects described above.

Thus, to access a user, you would use the users property of your gis object which gives you an instance of UserManager class. You would then call the get() method of the UserManager object and pass the user name of the user you are interested in.

user = gis.users.get('john.smith')

Rich IDE experience with Jupyter notebooks

The ArcGIS API for Python is integrated with Jupyter Notebook to make it easy to visualize and interact with GIS resources. The user object has a rich representation that can be queried like this:

John Smith

Bio: None
First Name: John
Last Name: Smith
Username: john.smith
Joined: October 28, 2014

The resources are implemented as Python dictionaries. You can query for the resource properties using the resource['property'] notation:


The properties are also available as properties on the resource object, so you can use the dot notation to access them:


The resources provide methods to update(), delete() and use the object. The reminder of topics in this module talk in detail about using the various helper objects and resource objects.

Embedded maps in Jupyter notebooks

The GIS object includes a map widget that can be used to visualize the content of your GIS as well as see the results of your analysis. Let's bring up a map of Palm Springs, CA:

map1 ="Palm Springs, CA")

We can search for content in our GIS. Let's search for Hiking Trails in the Palm Springs region. We do that by calling and for each web map or web layers that gets returned, we can display its rich representation within the notebook:

from IPython.display import display

items ='Palm Springs Trails', item_type='feature layer')
for item in items:
Original Plan Remaining from Basin and Range svc
Route and directions for Original Plan Remaining from Basin and RangeFeature Layer Collection by geeknixta
Last Modified: June 21, 2017
0 comments, 368 views
Victor Loop TrailFeature Layer Collection by kgrahamACBCI
Last Modified: March 01, 2018
0 comments, 43,801 views
Palm Springs Trails
Trails in the Palm Springs area affected by the BLM - Agua Caliente land exchangeFeature Layer Collection by paniello_geodesign
Last Modified: March 13, 2015
0 comments, 912 views
PS Base Map_WFL1
PSP Web MapFeature Layer Collection by KOAOCarcgis
Last Modified: December 08, 2020
0 comments, 2,024 views
West Fork LoopFeature Layer Collection by kgrahamACBCI
Last Modified: March 01, 2018
0 comments, 10,888 views
Andreas Loop TrailFeature Layer Collection by kgrahamACBCI
Last Modified: March 01, 2018
0 comments, 99,735 views
Palmer Lake Water
Town of Palmer Lake -Water MappingFeature Layer Collection by gmsesrigis
Last Modified: October 15, 2021
0 comments, 703 views
East Fork LoopFeature Layer Collection by kgrahamACBCI
Last Modified: March 01, 2018
0 comments, 11,921 views
Basin and Range north then end in AZ svc
Route and directions for Basin and Range north then end in AZFeature Layer Collection by geeknixta
Last Modified: June 21, 2017
0 comments, 456 views
Dry Wash Loop Feature Layer Collection by kgrahamACBCI
Last Modified: March 01, 2018
0 comments, 6,103 views

We can then add the returned web layers to our map. To add the last layer returned above, we call the add_layer() method and pass in the layer for Palm Springs Trail:

# Let us filter out the item with title 'Trails' that we want to add
item_to_add = [temp_item for temp_item in items if 'Trail' in temp_item.title]
[<Item title:"Palm Springs Trails" type:Feature Layer Collection owner:paniello_geodesign>]

The above cell updated the map widget, if you scroll to the top, you can notice a new trail layer being rendered on the map.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.