Python and the ArcGIS Python API

Workshop Requirements

For an easy setup that most will already have access to, I suggest one of the following:

• A Notebook in ArcGIS Pro
• The Notebooks tab in AGOL

All you really need is the arcgis Python library in your environment, and you can run these commands anywhere. Python terminal, Jupyter Notebook, VSCode, an AGOL Notebook.

Workshop Objectives

Following this workshop, participants will learn how to:

• Connect to AGOL / Portal
• Search for content
• Query feature services
• View web maps

Stretch goal: administering content

A Note on Notebooks

We’re using Jupyter Noteboks in this workshop, because it’s interactive, and parts of the Python API work very nicely with it.

If you haven’t used one before, a Notebook is organized in cells.

We can write and execute individual “chunks” of code, but all as part of one larger process.

There can also be non-executable Markdown in the notebook to include images, documentation, or extensive notes.

Getting Connected

The GIS object

You’ll start most of your scripts / notebooks like this:

from arcgis.gis import GIS
gis = GIS("https://arcgis.com") # <-- swap in your portal url if not AGOL

Now any time you call gis, you’ll be working directly with your GIS portal.

Go ahead and run a cell with just gis in it.

gis

GIS @ https://arcgis.com

Connecting with Authentication

Just include your username as the second parameter.

In an interactive context like this, the Notebook will ask you for your password.

gis = GIS("https://arcgis.com", 'carlsonj9')

You can confirm your login by running:

gis.users.me

Finding Content

The ContentManager

Your gis object has a class called the ContentManger. You can access it by calling gis.content, and then using its various methods.

We’ll start with something simple: a search.

Search

gis.content.search('highways')

[<Item title:"Streets (Night)" type:Web Map owner:esri>,
 <Item title:"Navigation" type:Web Map owner:esri>,
 <Item title:"Topographic" type:Web Map owner:esri>,
 <Item title:"Modern Antique Map" type:Web Map owner:esri>,
 <Item title:"Colored Pencil Map" type:Web Map owner:esri>,
 <Item title:"Human Geography Map" type:Web Map owner:esri>,
 <Item title:"ArcGIS Online Directions and Routing Services Coverage" type:Web Map owner:esri>,
 <Item title:"Streets (with Relief)" type:Web Map owner:esri>,
 <Item title:"Find Location by Feature Offset Code Sample" type:Code Sample owner:RoadsAndHighwaysTeam>,
 <Item title:"ESRI Gulf Oil Spill Map" type:Web Mapping Application owner:ESRI_response_team>]

This… doesn’t look very helpful?

The square bracket [ should be a clue to you, though: this is a list.

Let’s get a single item from our list.

One Item

gis.content.search('highways')[0]

Streets (Night)
This world basemap provides a custom "night time" street map style designed for use at night or in other low-light environments. (World Edition)
Web Map by esri
Last Modified: August 20, 2026
3 comments, 167483612 views

Specific Searching

There are a lot of options we can include in our search function to get more specific results. Things like:

• item type (map, layer, dashboard)
• item category
• tags
• owner

The parameter max_items may be useful as well, if you want to see more than 10 items at a time.

gis.content.search(
    'highways',
    item_type = 'Feature Layer',
    filter = 'tags:"OpenStreetMap"',
    max_items = 20
)

[<Item title:"OpenStreetMap Waterways for North America" type:Feature Layer Collection owner:smoore_osm>,
 <Item title:"OpenStreetMap Highways for Central America" type:Feature Layer Collection owner:smoore_osm>,
 <Item title:"OpenStreetMap Highways for South America" type:Feature Layer Collection owner:smoore_osm>,
 <Item title:"OpenStreetMap Highways for Europe" type:Feature Layer Collection owner:smoore2_osm>,
 <Item title:"OpenStreetMap Highways for North America" type:Feature Layer Collection owner:smoore_osm>,
 <Item title:"GeoCam Filtered Roads for Analysis OpenStreetMap Highways for North America" type:Feature Layer Collection owner:groundvu>,
 <Item title:"OpenStreetMap Пътища" type:Feature Layer Collection owner:nicolestrat17_fpls>,
 <Item title:"Vialidad" type:Feature Layer Collection owner:cindynt07>,
 <Item title:"OpenStreetMap Highways for Asia" type:Feature Layer Collection owner:GoshaYugo>,
 <Item title:"NM_OSM_Highways" type:Feature Layer Collection owner:keary.howley@dgf.nm.gov_nmdgf>,
 <Item title:"osm_buildings_sandiego" type:Feature Layer Collection owner:bjor3345@esri.com_ProdTesting>,
 <Item title:"BK6425_OpenStreetMap_Openbare_ruimte_voorzieningen" type:Feature Layer Collection owner:waad_zHS4ong9wMgmGRDKIouuyX4NC_reyNQ8uBbf9Br7jlw_RHK>,
 <Item title:"Overture Roads (CONUS)" type:Feature Layer Collection owner:smoore_omf>,
 <Item title:"OpenStreetMap Highways for Asia" type:Feature Layer Collection owner:smoore3_osm>,
 <Item title:"quantity of school bullings" type:Feature Layer Collection owner:EASL2025>,
 <Item title:"MDOT SHA Crosswalk Analysis (ROW Prefilter)" type:Feature Layer Collection owner:elliott.plack2>,
 <Item title:"OSMCyclewaysInPA_07082020" type:Feature Layer Collection owner:rtcderek>,
 <Item title:"OpenStreetMap Highways for North America_MB" type:Feature Layer Collection owner:5238_285_1128_4_byui>,
 <Item title:"別府市 主要道路 L3 (露天風呂の日2026)" type:Feature Layer Collection owner:ej_nakamae>,
 <Item title:"Road Labels" type:Feature Layer Collection owner:Brandon.Gregg_APCA>]

Working with Search Results

The default display of portal items isn’t always helpful. Since the returned object is a list, we can loop over our list to pull out specific details from each item.

items = gis.content.search(
    'highways',
    item_type = 'Feature Layer',
    filter = 'tags:"OpenStreetMap"',
    max_items = 20
)

for i in items:
    print(i.id)
    print(i.title)
    print(i.url, '\n')

Working with Search Results

a3b8b68385734660be84dc5de4425914
OpenStreetMap Waterways for North America
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_Waterways_NA/FeatureServer 

a22dc4dc053e45008157f3bcf2894105
OpenStreetMap Highways for Central America
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_CA_Highways/FeatureServer 

70c79ab73c15445492edecc53dac00c8
OpenStreetMap Highways for South America
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_SA_Highways/FeatureServer 

898b1393e5764825b6148730f8becdd5
OpenStreetMap Highways for Europe
https://services-eu1.arcgis.com/zci5bUiJ8olAal7N/arcgis/rest/services/OSM_Highways_EU/FeatureServer 

7afec250e02845868db89c83949a672f
OpenStreetMap Highways for North America
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_NA_Highways/FeatureServer 

b7f847b2bd2542ea9385c9a6307f80b4
GeoCam Filtered Roads for Analysis OpenStreetMap Highways for North America
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_NA_Highways/FeatureServer 

53e34c41e3904b229159b631933cc292
OpenStreetMap Пътища
https://services-eu1.arcgis.com/zci5bUiJ8olAal7N/arcgis/rest/services/OpenStreetMap_Highways_for_Europe/FeatureServer 

95988ced6b2f42d0a18dd746305c07d2
Vialidad
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_CA_Highways/FeatureServer 

39107cb6ff564823b19e9163fdc76d69
OpenStreetMap Highways for Asia
https://services-ap1.arcgis.com/iA7fZQOnjY9D67Zx/arcgis/rest/services/OSM_AS_Highways/FeatureServer 

436e98a0251d4746a7887be9982778ab
NM_OSM_Highways
https://services2.arcgis.com/CjbW1bVhK4dB3WOa/arcgis/rest/services/NM_OSM_Highways/FeatureServer 

7b091972873447e78ab060311467b0c2
osm_buildings_sandiego
https://services5.arcgis.com/9cBkZtsx7PSOoaCF/arcgis/rest/services/osm_buildings_sandiego/FeatureServer 

aee3f44b1c8f4c21ae36940be5d7cf6a
BK6425_OpenStreetMap_Openbare_ruimte_voorzieningen
https://services.arcgis.com/zmBQLV64TsFvEpV0/arcgis/rest/services/BK6425_OpenStreetMap_Openbare_ruimte_voorzieningen/FeatureServer 

f40a092737274783b223dfc7a0c9d92d
Overture Roads (CONUS)
https://services1.arcgis.com/SvBZpJ7eKEZhhKPa/arcgis/rest/services/OMF_Roads_CONUS_Beta/FeatureServer 

a9f8d83a69fc4f2c92e5f83f87df6aaf
OpenStreetMap Highways for Asia
https://services-ap1.arcgis.com/iA7fZQOnjY9D67Zx/arcgis/rest/services/OSM_AS_Highways/FeatureServer 

31c963f62c9c41548fd98684c736d9b5
quantity of school bullings
https://services3.arcgis.com/1tWe8DOygqtrHXCa/arcgis/rest/services/quantity_of_school_bullings/FeatureServer 

e5e1fcf2147f4a1aafac365fad6dc83f
MDOT SHA Crosswalk Analysis (ROW Prefilter)
https://services.arcgis.com/njFNhDsUCentVYJW/arcgis/rest/services/MDOT_SHA_Crosswalk_Analysis_(ROW_Prefilter)/FeatureServer 

3c89a26da2544931b9394fc4d6eacf25
OSMCyclewaysInPA_07082020
https://services5.arcgis.com/ZrPVNtByTK88ebut/arcgis/rest/services/OSMCyclewaysInPA_07082020/FeatureServer 

eb5f94bdcc1f4a8982f40a2933a0ebdd
OpenStreetMap Highways for North America_MB
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_NA_Highways/FeatureServer 

af77270d13354fffaff3b9c29ec7715f
別府市 主要道路 L3 (露天風呂の日2026)
https://services1.arcgis.com/KbxBPISGJFVF6WCN/arcgis/rest/services/L3_2026/FeatureServer 

bb62c066f7894e8da1ce3ce7f8277ecb
Road Labels
https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_NA_Highways/FeatureServer 

Aside: Items in a DataFrame

import pandas as pd

pd.DataFrame([{'id': i.id, 'title': i.title, 'url': i.url, 'owner': i.owner} for i in items])

	id	title	url	owner
0	a3b8b68385734660be84dc5de4425914	OpenStreetMap Waterways for North America	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	smoore_osm
1	a22dc4dc053e45008157f3bcf2894105	OpenStreetMap Highways for Central America	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	smoore_osm
2	70c79ab73c15445492edecc53dac00c8	OpenStreetMap Highways for South America	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	smoore_osm
3	898b1393e5764825b6148730f8becdd5	OpenStreetMap Highways for Europe	https://services-eu1.arcgis.com/zci5bUiJ8olAal...	smoore2_osm
4	7afec250e02845868db89c83949a672f	OpenStreetMap Highways for North America	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	smoore_osm
5	b7f847b2bd2542ea9385c9a6307f80b4	GeoCam Filtered Roads for Analysis OpenStreetM...	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	groundvu
6	53e34c41e3904b229159b631933cc292	OpenStreetMap Пътища	https://services-eu1.arcgis.com/zci5bUiJ8olAal...	nicolestrat17_fpls
7	95988ced6b2f42d0a18dd746305c07d2	Vialidad	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	cindynt07
8	39107cb6ff564823b19e9163fdc76d69	OpenStreetMap Highways for Asia	https://services-ap1.arcgis.com/iA7fZQOnjY9D67...	GoshaYugo
9	436e98a0251d4746a7887be9982778ab	NM_OSM_Highways	https://services2.arcgis.com/CjbW1bVhK4dB3WOa/...	keary.howley@dgf.nm.gov_nmdgf
10	7b091972873447e78ab060311467b0c2	osm_buildings_sandiego	https://services5.arcgis.com/9cBkZtsx7PSOoaCF/...	bjor3345@esri.com_ProdTesting
11	aee3f44b1c8f4c21ae36940be5d7cf6a	BK6425_OpenStreetMap_Openbare_ruimte_voorzieni...	https://services.arcgis.com/zmBQLV64TsFvEpV0/a...	waad_zHS4ong9wMgmGRDKIouuyX4NC_reyNQ8uBbf9Br7j...
12	f40a092737274783b223dfc7a0c9d92d	Overture Roads (CONUS)	https://services1.arcgis.com/SvBZpJ7eKEZhhKPa/...	smoore_omf
13	a9f8d83a69fc4f2c92e5f83f87df6aaf	OpenStreetMap Highways for Asia	https://services-ap1.arcgis.com/iA7fZQOnjY9D67...	smoore3_osm
14	31c963f62c9c41548fd98684c736d9b5	quantity of school bullings	https://services3.arcgis.com/1tWe8DOygqtrHXCa/...	EASL2025
15	e5e1fcf2147f4a1aafac365fad6dc83f	MDOT SHA Crosswalk Analysis (ROW Prefilter)	https://services.arcgis.com/njFNhDsUCentVYJW/a...	elliott.plack2
16	3c89a26da2544931b9394fc4d6eacf25	OSMCyclewaysInPA_07082020	https://services5.arcgis.com/ZrPVNtByTK88ebut/...	rtcderek
17	eb5f94bdcc1f4a8982f40a2933a0ebdd	OpenStreetMap Highways for North America_MB	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	5238_285_1128_4_byui
18	af77270d13354fffaff3b9c29ec7715f	別府市 主要道路 L3 (露天風呂の日2026)	https://services1.arcgis.com/KbxBPISGJFVF6WCN/...	ej_nakamae
19	bb62c066f7894e8da1ce3ce7f8277ecb	Road Labels	https://services6.arcgis.com/Do88DoK2xjTUCXd1/...	Brandon.Gregg_APCA

Getting a Specific Item

Every Item in a portal has a unique ID. If you know the id of an item, you can just ask for it.

Here’s the OSM Waterways layer:

waterways = gis.content.get('a3b8b68385734660be84dc5de4425914')

waterways

OpenStreetMap Waterways for North America
This feature layer provides access to OpenStreetMap waterways data for North America, which is updated frequently. Zoom in to medium scales (e.g. 1:80k) to see the waterway features display. Click on layer for popup.
Feature Layer Collection by smoore_osm
Last Modified: May 03, 2020
0 comments, 446919 views

Querying Feature Layers

The Feature Service

So we have our waterways service, but it’s still just an Item.

When the item type is Feature Service, we can pull out its layers and tables.

waterways.layers

[<FeatureLayer url:"https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_Waterways_NA/FeatureServer/0">]

A Feature Layer

As before, this is a list, so we have to retrieve an individual layer by its index.

feature_layer = waterways.layers[0]

feature_layer

<FeatureLayer url:"https://services6.arcgis.com/Do88DoK2xjTUCXd1/arcgis/rest/services/OSM_Waterways_NA/FeatureServer/0">

Aside: List Index ≠ Layer Index

Not all services are published with a perfectly sequential, zero-indexed list of layers!

gis.content.get('4a6c4c6e73344fd2b61a8f7ef2637a02').layers[0]

<FeatureLayer url:"https://services.arcgis.com/xOi1kZaI0eWDREZv/arcgis/rest/services/Community_Transportation_Database/FeatureServer/4">

A Simple Query

feats = feature_layer.query(
    return_all_records = False,
    result_record_count = 1000
)

feats

A Simple Query

<FeatureSet> 1000 features

Maps

gis.map('Illinois')

More Information

Authentication Methods

If you’re automating a process that requires authentication, you can’t rely on the password entry. And you may not want to store your password in plain text somewhere.

Fortunately, there are a number of articles on how to authenticate with your portal, a number of which will work in in a scheduled script.