About Jupyter Notebooks

The ArcGIS API for Python can be used from any application that can execute Python code. You can use the API from any of your favorite IDEs such as PyCharm, MS Visual Studio, Eclipse, Spyder, Rodeo, IDLE etc.

Jupyter Notebook is a web based IDE that is great for not only beginners but also seasoned programmers and scientists. This IDE is installed by default when you install the Python API. It allows you to type Python code, execute them and evaluate the results in a step-by-step interactive manner. Jupyter Notebooks can display not just Python code and its output, but also MarkDown, making them an excellent medium to document your workflows, scientific methods and share instructional material. Refer to this blog post to find how GIS professionals can make use of Jupyter notebooks.

Your first notebook

This section provides a quick introduction to the Jupyter Notebook environment where you can run Python code in an interactive manner and visualize the output as maps and charts. This section will help you get comfortable with using the notebook environment. Refer to the official Jupyter documentation and this quick start guide if you are looking for specific or advanced information.

Starting the Jupyter Notebook environment

Once conda and the ArcGIS API for Python is installed, you can start the Jupyter Notebook environment by typing the following command in your terminal.

jupyter notebook

If you are running a Windows OS, this could be your command prompt or PowerShell window. Similarly if you are running a Mac or Linux OS, this could be your terminal. Below is a screen shot of how it would appear if you were running the command from Windows command prompt.

Windows terminal starting Jupyter Notebook

**Note**: You should leave the terminal running for as long as you are using the notebook. Closing the terminal while using the notebook will make your notebooks lose connection with the Python shell.
**Note**: If you installed the ArcGIS API for Python in a conda environment other than the default `root`, you need to activate that environment before starting the Jupyter Notebook. For more information on the benefits of using environments and how to create and manage them, refer to this [help page](http://conda.pydata.org/docs/using/envs.html).

If you are running a sample notebook for the API, you need to 'cd' into the directory where you downloaded the samples. In the example above, the samples have been downloaded and extracted into c:\code directory.

The command starts Jupyter Notebook and opens it in your default web browser as shown below.

Jupyter dashboard The page you see in this image is called the Notebook Dashboard. Click and pull down the 'New' button from top right corner to create a new notebook, then type in the following sections.

Getting started with the API

The first step is to import the ArcGIS API for Python in your notebook

In [1]:
from arcgis.gis import GIS

You can 'run' or 'execute' a cell by clicking on the 'run cell' button from the toolbar. Alternately, you can hit Shift + Enter in your keyboard. When a cell is executing the cell number turns to an asterisk (*) and the circle next to the kernal name turns solid.

To get started, create an anonymous connection to ArcGIS Online as shown below:

In [2]:
gis = GIS()

You can search for content as shown below. Since you are connected to ArcGIS Online and as an anonymous user, the query shown below will return public content that is shared on ArcGIS Online

In [3]:
public_content = gis.content.search("Fire", item_type="Feature Layer", max_items=5)

To see the contents of the variable public_content you created above, simply type it in a new cell and run it (by hitting Shift + Enter)

**Note**: Expect to see different results when you run this each time on your computer. The code above performs a new search each time you execute it and the search results may vary based on which layers are available publicly.
In [4]:
public_content
Out[4]:
[<Item title:"Collier County Emergency Services" type:Feature Layer Collection owner:philsherman_collierbcc>,
 <Item title:"WRI_BeforeAndAfterPhotos" type:Feature Layer Collection owner:BuckEhler>,
 <Item title:"Ecological Overlay Feature Service (Cnps FS10)" type:Feature Layer Collection owner:charlesc>,
 <Item title:"FireHistory_Hazard_LA_County" type:Feature Layer Collection owner:cgujtangenberg>,
 <Item title:"Ecological Overlay Feature ServiceB (CNPS FS10B)" type:Feature Layer Collection owner:charlesc>]

The ArcGIS API for Python extends the Jupyter Notebook IDE to display ArcGIS Items in rich HTML notation. Thus, you can loop through each of the items in the search result and display it with thumbnails and metadata as shown below:

In [5]:
from IPython.display import display
for item in public_content:
    display(item)
Collier County Emergency Services
Emergency Facilities in Collier CountyFeature Layer Collection by philsherman_collierbcc
Last Modified: May 22, 2014
0 comments, 3,732 views
WRI_BeforeAndAfterPhotos
WRI Projects with Before and After PhotosFeature Layer Collection by BuckEhler
Last Modified: February 13, 2017
0 comments, 9,324 views
Ecological Overlay Feature Service (Cnps FS10)
Ecological Overlay Feature Service (Cnps FS10)Feature Layer Collection by charlesc
Last Modified: January 12, 2015
0 comments, 523 views
FireHistory_Hazard_LA_County
50 year fire history and hazard zones for LA CountyFeature Layer Collection by cgujtangenberg
Last Modified: January 06, 2015
0 comments, 288 views
Ecological Overlay Feature ServiceB (CNPS FS10B)
Ecological Overlay Feature ServiceB (CNPS FS10B)Feature Layer Collection by charlesc
Last Modified: January 12, 2015
0 comments, 169 views

Display layers on a map

The ArcGIS API for Python adds a map widget to the Jupyter Notebook. You can easily pull up a map as shown below. It may take a few seconds for the map to display the first time.

In [12]:
map1 = gis.map('Collier County, FL')
map1

Get the first item from your search result and add it the map you created

In [13]:
#get the first item
fire = public_content[0]

#add to map
map1.add_layer(fire)

Congratulations!

You have successfully created your first notebook. You can save it by clicking on the save button from the cell toolbar or by selecting it from the File menu. Refer to the guide on using the Jupyter notebook environment for more information and to the blog post five tips to get started with Jupyte Notebook for more tips and patterns to follow.


Feedback on this topic?