Skip To Content ArcGIS for Developers Sign In Dashboard

ArcGIS API for Python

arcgis.mapping module

The arcgis.mapping module contains classes and functions to represent and interact with web maps, scenes, and certain layer types such as map image and vector tiles. In this page we will observe how to visualize maps, scenes and layers using the map widget in Jupyter notebook environment.

Contents of this page:

Using the map widget

The GIS object includes a map widget for displaying geographic locations, visualizing GIS content, as well as the results of your analysis. To use the map widget, call and assign it to a variable, that you can then query to bring up the widget in the notebook:

In [1]:
import arcgis
from arcgis.gis import GIS
# Create a GIS object, as an anonymous user for this example
gis = GIS()
In [2]:
# Create a map widget
map1 ='Paris') # Passing a place name to the constructor
                        # will initialize the extent of the map.

paris map

Setting the map properties

Zoom level

The map widget has several properties that you can query and set, such as its zoom level, basemap, height, etc:

In [3]:

Assigning a value to the zoom property will update the widget.

In [4]:
map1.zoom = 10

You can also set rotation in 2D mode. This can also be achieved by right-clicking and dragging on the map.

In [5]:
map1.rotation = 45

Your notebook can have as many of these widgets as you wish. Let us create another map widget and modify some of its properties.

Map center

The center property reveals the coordinates of the center of the map.

In [6]:
map2 = # creating a map object with default parameters
In [7]:
{'spatialReference': {'latestWkid': 3857, 'wkid': 102100},
 'x': 0,
 'y': 1.30385160446167e-08}

If you know the latitude and longitude of your place of interest, you can assign it to the center property.

In [8]: = [34,-118] # here we are setting the map's center to Los Angeles

You can use geocoding to get the coordinates of place names and drive the widget. Geocoding converts place names to coordinates and can be used using arcgis.geocoding.geocode() function.

Let us geocode Times Square, NY and set the map's extent to the geocoded location's extent.

In [10]:
location = arcgis.geocoding.geocode('Times Square, NY', max_locations=1)[0]
map2.extent = location['extent']


Basemap are layers on your map over which all other operational layers that you add are displayed. Basemaps typically span the full extent of the world and provide context to your GIS layers. It helps viewers understand where each feature is located as they pan and zoom to various extents.

Your map can have a number of different basemaps. To see what basemaps are included with the widget, query the basemaps property

In [11]:
map3 =

You can assign any one of the supported basemaps to the basemap property to change the basemap. For instance, you can change the basemap to the dark gray vector basemap as below:

In [12]:
map3.basemap = 'dark-gray-vector'

Query the basemap property to find what the current basemap is

In [13]:

Let us animate a new map widget by cycling through basemaps and assigning it to the basemap property of the map widget.

In [14]:
map4 ='New York City, NY')

basemap animation

In [15]:
import time

for basemap in map4.basemaps:
    map4.basemap = basemap

3D Mode

The map widget also includes support for 3D mode! You can specify the 'mode' parameter through"foo"), or by setting the mode property of any instatiated map object. Run the below cell:

In [38]:
from arcgis.gis import GIS
gis = GIS()
usa_map ='USA', zoomlevel=4, mode="3D") #Notice `mode="3D"`

Just like 2D mode, you can pan by click-and-drag with the left mouse button, and you can zoom with the mouse wheel. In 3D mode, click-and-drag with the right mouse button modifies the tilt field and the heading field.

tilt is a number from 0-90: 0 represents a top-down 'birds-eye' view, while 90 represents being completely parallel to the ground, facing the horizon.

It's important to note that 2D mode uses rotation to specify the number of angles clockwise from due north, while 3D mode uses heading to specify the number of degrees counterclockwise of due north. See the API reference for more information.

Try running the below two cells, and replace them with your own values!

In [39]:
usa_map.tilt = 45
In [ ]:
usa_map.heading = 45

Read more about 3D mode by reading the advanced map widget useage guide page, or by reading the API reference.

Adding layers to the map

An important functionality of the map widget is its ability to add and render GIS layers. To a layer call the add_layer() method and pass the layer object as an argument.

In [39]:
# Log into to GIS as we will save the widget as a web map later
gis = GIS("", "arcgis_python", "P@ssword123")
usa_map ='USA', zoomlevel=4)  # you can specify the zoom level when creating a map