Introduction - What is the ArcGIS API for Python?

Introduction - What is the ArcGIS API for Python?

What is an “API”?

API is short for Application Programming Interface, but really it’s just a term for a set of commands sent from a local machine (client) to a remote server framework via the internet. A Google search, for example, involves using the Google Search API: when you enter a search term on Google’s home page and hit enter, your browser forms a request via the Google Search API, which is sent off to the Google servers, which then post back a reply of your search results.

The format of this API call is in the URL:

https://www.google.com/search?q=Duke+University

and the response is text in html format that your browser understands and can process into a tidy looking web page of search results.

A simple, but powerful concept: If we know the commands of an API (and have access to the servers), we have just unlocked a vast amount of new resources that reside on the cloud! And we don’t necessarily need a web browser to interact with these resources; we can use scripting tools like Python to send the API requests and handle the server’s responses.

What is the “ArcGIS API for Python”?

Like Google, ESRI hosts a number of resource on the cloud (ArcGIS Online). ESRI also provides software so other organizations can host resources on the cloud (ArcGIS Enterprise). In short, there is a vast amount of data and geoprocessing capabilities in the cloud awaiting us to leverage it – if we know how.

ESRI has long provided a REST API for interacting with cloud-based resources. Those well-versed in HTML and JavaScript are well equipped to leverage this resource. For those who prefer Python, ESRI has created a whopper of a Python package that includes a huge number of classes and functions for working with data served via AGOL and ArcGIS Enterprise.

Put simply: the ArcGIS API for Python is a Python package that enables us to work with hosted geospatial resources (data and services).

Key features of the ArcGIS API for Python: https://developers.arcgis.com/python/latest/guide/key-features/

Evolution of the ArcGIS API for Python

Cloud-based resources evolve much faster than typical desktop software. Additionally, we have no control when those changes occur. (We can’t hold off on an upgrade of ESRI’s AGOL infrastructure!) This makes it both tricky and exciting for working with APIs. The tricky part is that we have to maintain our code so it keeps up with changes on-line. The exciting part, and this certainly applies to the ArcGIS API for Python, is that the capabilities of an API can grow rapidly, facilitating more and more analysis from our coding platform.

In fact, the ArcGIS API for Python now includes much more functionality than just accessing data stored on AGOL. Its more recent updates have introduced the ability to do complex tasks such as data enrichment, deep learning, object detection, network routing, and even the automated publishing of online apps such as StoryMaps. The API also includes a surprising amount of geoprocessing capability, overlapping with the ArcPy package - but without requiring ArcGIS Pro to be installed or access to an ArcGIS Pro license. (Some tools do require an ArcGIS Online account and perhaps consume credits, but a good many can be run without. )

Learning the ArcGIS API for Python

Mastering the ArcGIS API for Python is a bit more complicated than learning your typical Python package because of its size and the fact that it evolves so quickly. That said, however, the fundamental approach to learning the package is fairly typical:

  • Familiarize yourself with the documentation and structure of the API
  • Play with the API - on your own and using some existing examples
  • Refer back to the documentation as needed - both to hone syntax, but also to understand the overall structure of the classes and functions.
  • Use web searches and AI to facilitate

To be honest, this lesson presents itself as a great opportunity to wean you off instructor-led lessons and teach you how to teach yourselves!

Learning Objectives

  • Review useful approaches for learning a new technology
  • Become familiar with what the ArcGIS Python API is and what it can do
  • Engage the API to locate and download content or use in directly in your Python environment

Getting to know the ArcGIS Python API

Now that you heard about this new API thing, where should you go next to learn more? The obvious place is ESRI’s documentation for it - and ESRI really does do a good job of documenting its resources.

Task 1: Familiarize yourself with the documentation

  • Open the main page for the ArcGIS Python API (Google to find the link).

    :exclamation: Note that the API documentation may not match the version of the API you have installed. Fortunately, ESRI usually provides links to previous versions of the documentation.

  • Browse the page, asking yourself: What does this new technology do?

  • Get a feel for the structure of the documentation.

  • You may also want to explore where this page lives in the context of other related resources:

    • Note the URL: This page is a subpage of https://developers.arcgis.com. What's on that link?
    • You may also notice the Sign In link in the upper right. Can you sign in? What are you signing in to?

*At first you might only get a vague idea of what the API can do, and that’s fine. But you’ll also see that this site offers many different pathways to learn more. There are links to a Guide, Sample Notebooks, an API Reference, and link to several blog posts where everyday folks share their knowledge. It also has links to a number of samples using this API - plenty of ways to dive in.


Task 2: Play! (and learn)

The exact path you take to learn the API is up to you. Just note that the ArcGIS Python API is a particularly vast API with more capabilities than you will likely ever use and that you shouldn’t expect to master all it has to offer in a day or two or even a month or two. Instead, I recommend you explore various aspects of the API to various depths – all the while making an effort to understand commonalities among the various components and building a mental structure of what this resource can do and how it might be useful to you.

I provide you with a GitHub repository with some curated examples to get you started - as well as address some of the needs a few of you have noted for your course projects.

Setup

Fork and clone the https://github.com/ENV859/ArcGIS-PythonAPI repository. As you might expect, this contains a number of Python notebooks containing examples for learning the concepts mentioned above. Included is a link to open Jupyter using your ArcGIS Pro default environment (“arcgispro-py3”).

Some lesson’s I’ve learned…

While I want to leave the exploration of the API in your hands, I do feel it useful to offer a few brief tips that might help overcome some initial humps in the learning curve. I also offer a few Jupyter notebooks to help out with these provided in the form of a GitHub repository.

♦ On the general structure of the API

A bulk of the API’s utility is interacting with resources found on ArcGIS Online. It’s organized into a number of modules (see https://developers.arcgis.com/python/guide/overview-of-the-arcgis-api-for-python/#Architecture-of-the-API) loosely categorized into three themes: accessing GIS content at various levels (green), augmenting interaction with these data (blue), and visualizing the data (orange).

API Modules

Also useful is the discussion centered on the architecture of the GIS Module:

GIS module

More info: https://developers.arcgis.com/python/guide/the-gis-module

I suggest focusing first on techniques for accessing content , and then perhaps on analyzing content. Using the ArcGIS Python API for analyzing content, however, may consume credits or possibly be disabled - something I need to explore more myself. However, if you can access content from within Python, you can perhaps use open source GIS (e.g., GeoPandas) to perform analysis…