An Introduction to the ArcGIS API for Python from ArcGIS Pro

Automation has always been a great bonus for the GIS professional using Esri’s ArcGIS tools. Many experienced users will have used Visual Basic for Applications in ArcMap to author custom workflows for both GIS and GIS administration tasks. While VBA is largely frowned upon by professional developers (according to Wikipedia, VBA has held its position as "most dreaded" language for developers for the last 2 years) its strength lay in its low barrier for entry and ease of use. However, when your workflows got more complex and your VBA codebase grew over several iterations of enhancements and improvements, the cracks started to show, and maintaining complex VBA became troublesome.

Esri, along with many in the wider IT industry, have embraced Python as the customisation language of choice. Python also has the benefits of a low barrier for entry and ease of use, but enjoys wide spread support among professional and casual developers alike (as of December 2020 Python ranked third in TIOBE's index of most popular programming languages, behind C and Java).

Python runs on many operating systems. The language design encourages code readability (the use of whitespace, for example, has significant meaning within the code). Python can be written as procedural or object-oriented code. There are many supporting libraries which extend the core functionality of Python in all manner of areas, for example, Machine Learning, Data Science, Image Manipulation, Graphing, and, of course, GIS.

In this post I’m going to concentrate on using Python, and the ArcGIS API for Python from within ArcGIS Pro to automate administration tasks for your ArcGIS Online or ArcGIS Enterprise.

The aim is to demonstrate the ease of use of the language and its environment, and to encourage you to explore some more complex use cases. There’s a lot of community support, both for Python in general and for the ArcGIS API for Python. Hopefully you can find answers to your questions there, or even contribute some of your code and experiences.

First up, though, how do you get started?

Well you’ll be glad to know that if you are an existing ArcGIS Pro user, there are no additional installations or configurations required to get started. Python and a Jupyter Notebooks environment are both installed along with ArcGIS Pro, and while you can enhance your environment, you can get a lot done and explore many areas with what comes out-of-the-box.

So, how do you access Python from within ArcGIS Pro?
 

From your ArcGIS Pro project, select “New Notebook” from the “Insert” tab on the toolbar ribbon. This will create and initialise a new Python notebook called “New Notebook”.
 

I like to right-click on the Notebook in the Catalog view and rename it to something more relevant.
 

You are then faced with a “cell” labelled “In”. This is your interactive Python environment. Code entered in the “In” cell is executed when the cursor is in the cell and you hit the Run button. A new “Out” cell will display any output from your Python code.
 

Note: There is a lot of help/how-to content online for Python, Jupyter Notebooks, and the ArcGIS API for Python. This post can’t hope to cover enough, it’s just a taster of what is possible.
Check out Python help at https://www.python.org/about/gettingstarted/ , the Jupyter help for details on the notebook environment https://jupyter.org/, and the ArcGIS API for Python at https://developers.arcgis.com/python/ for everything from starting out, to deep dives into the technologies.
 

Let’s look at who is registered with your portal. In these examples, I’ll be using our ArcGIS Online organisation account, for which I’m an admin user. Many of the same options will be available against a local deployment of ArcGIS Enterprise or your own ArcGIS Online account. Note that you will be afforded the same privileges by the ArcGIS API for Python as you are interactively, so you will require administrator privileges to get results from some of the examples below.

First, we need to import the ArcGIS API for Python, and establish a connection to our portal.
 

By using the “home” parameter when connecting and creating my gis object, I’m defaulting to connecting to the same portal, with the same user, that ArcGIS Pro is connected to. In this case, I’m connected with my user to the Esri Ireland ArcGIS Online organisation.
 

If I was going to administer a different portal, I would supply the appropriate URL and user credentials.
 

Here, I’m also importing a library called “getpass” which allows me to solicit a password without it showing up on the screen.  I’ve specified the URL an ArcGIS Enterprise instance; you’d replace that with your local URL.

Not much to see yet, just confirmation of the gis connected.

Now that we have our connection, we can query which users are registered. There are a couple of different ways to do this, in this example I’ll be querying what types of users are registered, and how many of each there are.
 

I can then extend this to drill into a specific type of user to retrieve the details for each of the users.
 

Note: The # symbol in Python denotes a comment – the lines starting with the # aren’t code that is executed, merely a note of what the intent of the code is.
Code indentation in python is an integral part of the language. The code within the for loops above, for example, is only deemed to be within the loop by virtue of the indent. It’s one of those things you’ll either love, or hate, about python!
\t is used to put a [tab] in the output.

We have 96 creator user types in our organisation, of which my user (acullen) is one. I can use the following line to retrieve my user directly, and then I can see fine grained details for that user, including when I last logged into the portal.
 

We could use this method to determine who is actively using our portal, and those less active.

To investigate the content owned by this user, select items belonging to the username and iterate through them.
 

I own several hundred items in ArcGIS Online, and the output cell from the above is formatted in a scrolling panel for ease of reading.

Each Content Item in ArcGIS Online or ArcGIS Enterprise has an ItemID – this can be found programmatically, or, as shown below, just looking at the item in the browser interface.

The ItemID for this AllIslandWindfarms test layer is highlighted in the URL. Using the ID we could directly reference the layer from our Python code.

The content_status is used to flag an item’s status. It can be blank, or set to 'org_authoritative' or 'deprecated'.

Looking at the windfarm data in ArcGIS Online (below), we can see it doesn’t have Delete Protection set. Delete Protection gives an extra prompt to a user to avoid the item being accidentally deleted.

Let’s set it from Python.

Refreshing the item’s page, we can see it’s now Delete Protected.

Here’s a fun one, I can programmatically send my users a notification.

Which then shows up in their alerts status.

This is just the tip of the iceberg in terms of automating administration of your ArcGIS Portal. You can create and maintain Groups, share content, manage your Movers/Joiners/Leavers, and keep an eye on what is and isn’t being used regularly in your Organisation.

The Python Notebooks created in ArcGIS Pro can be shared with colleagues, and better still be saved and executed directly on ArcGIS Online even without ArcGIS Pro.

Of course, these are just some simple examples, and even with these, I’m skipping over many of the nuances to the code I’m presenting. What I hope it demonstrates, though, is how, with a few lines of Python, some powerful automations can be achieved.

I’d encourage you to delve into the world of Python and the ArcGIS API for Python, and would love to get feedback on the custom automations you create to help you with your workflows, be it from an administration point of view (on boarding new users, for example), or a GIS or data analysis task.

Get Started: https://developers.arcgis.com/python/

The code snippets referenced in this article can be downloaded here.