Are you interested in using the ArcGIS API for Python to automate your ArcGIS Online or ArcGIS Enterprise workflow, but find the number of components and software options daunting?
The ArcGIS API for Python can seem overwhelming due to the complexity and number of installation options, as well as the different Python environments that are possible. The ArcGIS API for Python also integrates third-party products, such as Anaconda and Jupyter Notebook, which may be new to many.
However, the ArcGIS API for Python can be very useful and intuitive, especially when best practices are followed. It can also greatly simplify your scripts. For example, if you are writing a script for reassigning content from one user to another user and don’t use the ArcGIS API for Python, you will have to create text strings for URL requests for every action you want to perform. This will be a very long script.
In contrast, to perform the same workflow using the ArcGIS API for Python, you will have a lovely short script because the ArcGIS API for Python constructs URL requests for you. In this example, using the ArcGIS API for Python could reduce the number of lines of code from 117 to 19 to complete the same task.
Before you start using the ArcGIS API for Python, it is nice to have a good grasp on what the ArcGIS API for Python is and some best practices in using it. This article breaks down the components and how they relate to each other, explains the concepts behind the ArcGIS API for Python, and provides some best practices for using it.
The ArcGIS API for Python, Defined
The definition “A Python API developed by Esri to manage Web GIS via the ArcGIS REST API” may not be very useful because it assumes that you already know what Python, an API, the ArcGIS REST API, and Web GIS are.
Although I assume you already understand Web GIS, just to get everyone on the same page, let me note that Web GIS is a concept that contains any GIS data management system using the web to share, edit, or manage the data. Esri uses Web GIS to refer to both ArcGIS Online and ArcGIS Enterprise (particularly Portal for ArcGIS). The rest of this article dives into the other concepts and how they allow you to manage your Web GIS.
Understanding Python Installation
Python is an open-source programming language that Esri, along with many other software companies, uses to create processing tools. A Python installation comes with core code (a python.exe and associated files) and a package of additional tools and functions. The user can add other packages to expand functionality.
Python Installation for ArcGIS Desktop
The Python installation that comes with ArcGIS Desktop has the ArcPy package, which contains all ArcGIS geoprocessing tools. Other common packages include numpy, urllib, and requests. Numpy, which has mathematical functions, is usually installed by default with Python, but the user must install urllib and requests, which allow you to construct and send URL requests through your Python script.
ArcGIS Desktop comes with a Python installation, but not all ArcGIS Python installations are the same. Between the development of ArcMap and ArcGIS Pro, Python came out with several new versions. An ArcMap installation comes with Python 2.7 because the ArcPy package in ArcMap works with Python 2.7.
ArcGIS Pro was developed using Python 3.5, and the ArcGIS Pro ArcPy package requires a Python 3.5 installation. Similarly, the ArcGIS API for Python can only be installed on a client using Python 3.5, and the Python package for ArcGIS API for Python is called arcgis.
ArcGIS Pro Python 3.5 Installation
“But wait,” you may be thinking, “I thought the ArcGIS API for Python was an API. Why are you referring to it as a Python package?”
Good question!
The ArcGIS API for Python is both a Python package and an API. Python packages are packages of tools that can be installed in a Python environment, and that is exactly what the ArcGIS API for Python is. However, the ArcGIS API for Python is also an API. Which leads us to the next question: What is an API?
What Is an API?
API stands for application programming interface. It is a library of tools that allows two applications to interact with each other. Examples include the ArcGIS API for JavaScript and the ArcGIS REST API.
Imagine you have a colleague who wants a drink from a vending machine. You have an application (a thirsty colleague) that would like to make a request (buy a soda) from a server (the vending machine). To do this, there must be an interface that both the application and the server can understand and interact with. In this case, the keypad acts as the interface between the application and the server.
An Application Making a Request from a Server
A real-world example of an API is the ArcGIS REST API. It is a set of tools that allows applications to make requests of ArcGIS Server sites. As the name implies, the ArcGIS REST API contains the tools to allow applications to make REST requests of the RESTful ArcGIS Server sites. Since the ArcGIS API for Python interacts with the ArcGIS REST API, let’s dig into what it means to say a server site is RESTful.
What Is REST?
REST, or Representational State Transfer, is an architectural style that, among other functions, organizes a site in a way that allows people to read URLs. ArcGIS Server sites use the REST architectural style to create sites that can be navigated the same way you navigate through computer folders.
Look at an example of a RESTful site in figure 1, which shows https://sampleserver6.arcgisonline.com/arcgis/rest/services. If I open the Energy folder in the Service Directory, /Energy gets added to the URL just as it would in Windows Explorer. Inside the Energy folder, I can open Geology (FeatureServer), which will also get added to the URL as Geology/FeatureServer, as shown in figure 2. If I want to work with a specific service layer, such as the Fault layer, the number of the layer (0) will be added to the URL.
Once the URL is pointing to a specific service or service layer, operations you want to perform on that service or layer can be appended to the end of the URL. For example, if you want to query a specific feature by its ObjectID from the Fault (0) layer of the Geology service, you could add the query? operation from the ArcGIS REST API and any parameters for the operation (for example, objectIds=41568). The URL request now looks like this:
When you send the URL request, SampleServer6 responds to the request with information on feature 41568 in the first layer of the Geology feature service.
The ArcGIS REST API is a list of all the operations you (or an application) can perform on services in ArcGIS Server sites. These operations are then applied to the services using the REST architecture in the URL request.
The ArcGIS API for Python versus the ArcGIS REST API
If an API is the interface between two applications, and the ArcGIS REST API is the interface between an application and ArcGIS Server sites, what is the ArcGIS API for Python an interface between?
There are two ways to think about this. You can think of the ArcGIS API for Python as the interface between a Python script and the ArcGIS REST API. The ArcGIS REST API then interfaces between the ArcGIS API for Python and the ArcGIS Server site.
What Is the ArcGIS API for Python?
Now that we have dissected Python, Python packages, APIs, and the ArcGIS REST API, we can come up with this final definition.
The ArcGIS API for Python is both an API and a Python package. It includes tools that help a Python script use the ArcGIS REST API, which in turn includes the tools to make requests of ArcGIS Server services. The ArcGIS API for Python helps you write Python scripts to manage your content and users in your Web GIS.
The Python API interfaces between Python scripts and the REST API. Alternatively, you can think of the ArcGIS API for Python as a Pythonic wrapper around the ArcGIS REST API, and both work together as the interface between the script and the ArcGIS Server site.
The ArcGIS API for Python wraps the construction of ArcGIS REST API URLs in Pythonic functions, so instead of having to construct a URL manually in a script, you can call on prebuilt functions that will construct the URLs in the back end.
About the author
