Your first notebook

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.

**Note**: You should leaving 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](

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.

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

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:

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

public_content ="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.
[<Item title:"Natuurrampen" type:Feature Layer Collection owner:Esri_NL_Content>,
 <Item title:"Collier County Emergency Services" type:Feature Layer Collection owner:philsherman_collierbcc>,
 <Item title:"Intact Forest Landscapes (2000)" type:Feature Layer Collection owner:GlobalForestWatch>,
 <Item title:"Fire Perimeters" type:Feature Layer Collection owner:cferner_CALFIRE>,
 <Item title:"WRI_BeforeAndAfterPhotos" type:Feature Layer Collection owner:BuckEhler>]

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:

from IPython.display import display
for item in public_content:
Deze service toont de typen 'Natuurbrand' en 'Aardbeving' uit het thema 'Natuurrampen' van de risicokaartFeature Layer Collection by Esri_NL_Content
Last Modified: September 07, 2017
0 comments, 4,133 views
Collier County Emergency Services
Emergency Facilities in Collier CountyFeature Layer Collection by philsherman_collierbcc
Last Modified: May 22, 2014
0 comments, 4,436 views
Intact Forest Landscapes (2000)
Identifies the world’s last remaining unfragmented forest landscapes, large enough to retain all native biodiversity and showing no signs of human alteration as of the year 2013. This layer also shows the reduction in the extent of Intact Forest Landscapes from 2000 to 2013.Feature Layer Collection by GlobalForestWatch
Last Modified: October 20, 2017
0 comments, 1,979 views
Fire Perimeters
Current calendar year fire perimeters in California from GeoMACFeature Layer Collection by cferner_CALFIRE
Last Modified: October 24, 2017
0 comments, 16,841 views
WRI Projects with Before and After PhotosFeature Layer Collection by BuckEhler
Last Modified: February 13, 2017
0 comments, 9,340 views

Display layers on a map

The ArcGIS API for Python adds a map widget to the Jupyter Notebook. This map widget can be used to display layers from any of the above public content items. Pick an example item:

example_item = public_content[0]
Deze service toont de typen 'Natuurbrand' en 'Aardbeving' uit het thema 'Natuurrampen' van de risicokaartFeature Layer Collection by Esri_NL_Content
Last Modified: September 07, 2017
0 comments, 4,133 views

You can then easily pull up a map, as shown below. It may take a few seconds for the map to display the first time.

#Create a new map object
map1 =
#Focus the map to the part of the world containing the example item
map1.extent = example_item.extent
#Display the map

You can now add your example item to the map you just created.



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.

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