ArcGIS API for Python

2.4.2 · active · verified Fri Apr 17

The ArcGIS API for Python is a powerful, open-source library for working with GIS data and services. It provides a rich set of tools for spatial analysis, data management, and mapping, enabling automation and scripting workflows with ArcGIS Online and ArcGIS Enterprise portals. The current version is 2.4.2, and it follows a regular release cadence with several updates per year, often aligning with major ArcGIS platform releases.

Common errors

```
AttributeError: 'GIS' object has no attribute 'manager'
```
cause Attempting to access a 'manager' attribute on GIS object properties (like gis.users.manager) which was removed in version 2.0.0.

fix Remove the `.manager` attribute. For example, change `gis.content.manager.search()` to `gis.content.search()` and `gis.users.manager.get()` to `gis.users.get()`.
```
ImportError: cannot import name 'Geoenrichment' from 'arcgis.geoenrichment'
```
cause The `geoenrichment` module was moved from `arcgis.geoenrichment` to `arcgis.features.geoenrichment` in ArcGIS API for Python version 2.0.0.

fix Update your import statement from `from arcgis import geoenrichment` to `from arcgis.features import geoenrichment`.
```
ValueError: Invalid username or password
```
cause The credentials provided to the `GIS` object constructor are incorrect, or the portal URL is inaccessible/incorrect.

fix Double-check your `username`, `password`, and `portal_url`. Ensure the user has the necessary permissions to access the portal. Verify network connectivity to the portal URL.
```
requests.exceptions.SSLError: HTTPSConnectionPool(...): Max retries exceeded with url: ... Failed to establish a new connection: [SSL: CERTIFICATE_VERIFY_FAILED]
```
cause The Python environment cannot verify the SSL certificate of the ArcGIS portal. This is common with self-signed certificates or corporate proxies.

fix Ensure the necessary root certificates are trusted by your system. For testing, you can pass `verify_cert=False` to the `GIS` constructor (e.g., `gis = GIS(url, username, password, verify_cert=False)`). *Use with caution and only in controlled environments.*

Warnings

breaking Version 2.0.0 (March 2021) introduced significant API changes, particularly in how users, groups, and content are managed. Direct access to `manager` objects (e.g., `gis.users.manager`) was removed in favor of direct properties/methods (e.g., `gis.users.search()`).
Fix: Update your code to use the direct properties and methods on `gis.users`, `gis.groups`, and `gis.content`. For example, replace `gis.content.manager.search()` with `gis.content.search()`.
deprecated The `gis.map()` method for creating map widgets was deprecated in version 2.0.0 and replaced by `gis.map_view()`. While `gis.map()` might still work in some contexts, `gis.map_view()` is the recommended and actively maintained approach.
Fix: Replace calls to `gis.map()` with `gis.map_view()`.
breaking Several modules and classes were reorganized or moved in version 2.0.0. A notable example is `arcgis.geoenrichment` moving to `arcgis.features.geoenrichment`.
Fix: Review the API reference for the 2.x series and update import paths for affected modules (e.g., `from arcgis.features import geoenrichment` instead of `from arcgis import geoenrichment`).
gotcha In enterprise environments, SSL certificate verification issues (e.g., self-signed certificates or corporate proxies) can prevent successful connections. This often manifests as `requests.exceptions.SSLError`.
Fix: Configure trusted root certificates on your system, or for development/testing, you can temporarily set `verify_cert=False` in the `GIS` constructor (e.g., `gis = GIS(url, verify_cert=False)`). *Caution: Disabling certificate verification is not recommended for production environments.*

Install

pip install arcgis Install stable version

Imports

GIS
wrong:
```
from arcgis import GIS
```
correct:
```
from arcgis.gis import GIS
```
GIS is part of the gis submodule, not directly under arcgis
SpatialDataFrame
wrong:
```
from arcgis.geometry import SpatialDataFrame
```
correct:
```
from arcgis.features import SpatialDataFrame
```
SpatialDataFrame was moved from arcgis.geometry to arcgis.features in version 1.5

Quickstart

Demonstrates how to connect to ArcGIS Online or an ArcGIS Enterprise portal using the GIS object. It shows how to authenticate and perform a basic content search. It is highly recommended to use environment variables for sensitive credentials.

import os
from arcgis.gis import GIS

# Connect to ArcGIS Online or a specific portal
# It's recommended to store credentials securely, e.g., using environment variables or secret management.
# For ArcGIS Online, use 'https://www.arcgis.com'
# For ArcGIS Enterprise, use your portal URL, e.g., 'https://yourportal.com/portal'

# Option 1: Anonymous access (limited)
# gis = GIS()

# Option 2: Connect using username and password (for scripting)
# Replace with your actual credentials or retrieve from secure storage
portal_url = os.environ.get('ARCGIS_PORTAL_URL', 'https://www.arcgis.com')
username = os.environ.get('ARCGIS_USERNAME', 'YOUR_USERNAME')
password = os.environ.get('ARCGIS_PASSWORD', 'YOUR_PASSWORD')

if username == 'YOUR_USERNAME' or password == 'YOUR_PASSWORD':
    print("Warning: Please set ARCGIS_USERNAME and ARCGIS_PASSWORD environment variables or replace placeholders.")
    # Attempt anonymous access if credentials aren't set
    try:
        gis = GIS(portal_url)
        print("Connected anonymously to " + gis.url)
    except Exception as e:
        print(f"Failed to connect anonymously: {e}")
        gis = None
else:
    try:
        gis = GIS(portal_url, username, password)
        print("Logged in as " + gis.properties.user.username + " to " + gis.url)
    except Exception as e:
        print(f"Failed to connect with credentials: {e}")
        gis = None

if gis:
    # Example: Search for content
    items = gis.content.search(query="type:'Web Map'", num_items=5)
    for item in items:
        print(f"- {item.title} ({item.owner})")

view raw JSON →