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 [2]:
import arcgis
from arcgis.gis import GIS
# Create a GIS object, as an anonymous user for this example
gis = GIS()
In [42]:
# 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 [43]:

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

In [44]:
map1.zoom = 10

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 [46]:
map2 = # creating a map object with default parameters
In [51]:
[0, 0]

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

In [52]: = [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 [53]:
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 [15]:
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 [16]:
map3.basemap = 'dark-gray-vector'

Query the basemap property to find what the current basemap is

In [17]:

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

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

basemap animation

In [ ]:
import time

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

Using custom basemaps

Basemaps are essentially web map items and the help here can walk you through the steps involved in creating your own basemaps. The administrator of a GIS has the ability to designate a particular group in the GIS as the basemap gallery group. Web maps from this group are treated as custom basemaps for that GIS.

To find the list of custom basemaps available from this group, use the gallery_basemaps property.

In [28]:
# Log into to GIS that has basemap gallery option enabled.
gis = GIS("", "arcgis_python", "P@ssword123")
map5 ='London, UK', zoomlevel=10)
In [19]:

To create a map using the custom basemap, simply assign that to the basemap property of your map.

In [29]:
map5.basemap = 'os_open_carto'

img: custom basemap

Note: Gallery basemaps serve another important purpose. They allow you to publish basemaps with layers that can be used in disconnected environments where the notebooks cannot connect to ArcGIS Online to display the default basemap layers. If you are using the Python API and Jupyter notebooks in such environments, you can publish a few basemaps to the gallery basemaps of your GIS and make use of them in your map widgets.

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 [3]:
# 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

img: map with different layers

Next, search from some layers to add to the map

In [4]:
flayer_search_result ="owner:esri","Feature Layer", outside_org=True)
[<Item title:"USA Block Groups" type:Feature Layer Collection owner:esri>,
 <Item title:"USA Detailed Streams" type:Feature Layer Collection owner:esri>,
 <Item title:"USA Tracts" type:Feature Layer Collection owner:esri>,
 <Item title:"USA Core Based Statistical Area" type:Feature Layer Collection owner:esri>,
 <Item title:"World Regions" type:Feature Layer Collection owner:esri>,
 <Item title:"World Time Zones" type:Feature Layer Collection owner:esri>,
 <Item title:"World Continents" type:Feature Layer Collection owner:esri>,
 <Item title:"USA Freeway System" type:Feature Layer Collection owner:esri>,
 <Item title:"World Countries" type:Feature Layer Collection owner:esri>,
 <Item title:"USA Census Populated Places" type:Feature Layer Collection owner:esri>]

Adding Item objects to the map

You can add Item objects to a map by passing it to the add_layer() method.

In [5]:
world_timezones_item = flayer_search_result[5]

Adding layer objects to the map

You can add a number of different layer objects such as FeatureLayer, FeatureCollection, ImageryLayer, MapImageLayer to the map. You can add a FeatureLayer as shown below:

In [6]:
world_countries_item = flayer_search_result[-2]
world_countries_layer = world_countries_item.layers[0]
<FeatureLayer url:"">
In [7]:
usa_map.add_layer(world_countries_layer, options={'opacity':0.4})

Adding layers with custom symbology

While calling the add_layer() method, you can specify a set of renderer instructions as a dictionary to the options parameter. The previous cell shows how you can set the transparency for a layer. The opacity value ranges from 0 - 1, with 0 being fully transparent and 1 being fully opaque.

You can make use of the "smart mapping" capability to render feature layers with symbology that varies based on an attribute field of that layer. The cell below adds the 'USA Freeway System' layer to the map and changes the width of the line segments based on the length of the freeway.

In [8]:
usa_freeways = flayer_search_result[-3].layers[0]
usa_map.add_layer(usa_freeways, {'renderer':'ClassedSizeRenderer',

Refer to the guide on smart mapping to learn more about this capability.

Adding imagery layers

Similar to FeatureLayers, you can also add ImageryLayers and imagery layer items. You can also specify either a built-in raster function or a custom one for rendering.

In [13]:
world_terrain_item = gis.content.get('58a541efc59545e6b7137f961d7de883')
terrain_imagery_layer = world_terrain_item.layers[0]
In [14]:

Listing the layers added to the map

You can list the layers added to be map using the layers property.

In [15]:
[<FeatureLayer url:"">,
 <FeatureLayer url:"">,
 <FeatureLayer url:"">,
 <ImageryLayer url:"">]

Removing layers from the map

To remove one or more layers, call the remove_layers() method and pass a list of layers that you want removed. To get a list of valid layers that can be removed, call the layers property as shown in the previous cell.

The code below shows how to remove the USA freeways layer

In [16]:

To remove all layers, call the remove_layers() method with any parameters.

Drawing graphics on the map

You can draw or sketch graphics on the map using the draw() method. For instance, you can draw and annotate rectangles, ellipses, arrow marks etc. as shown below:

In [24]:

Now scroll to the map and draw a rectangle.

In [27]:

Scoll back to the map again and place an 'up arrow' below Los Angeles. Refer to the API reference documentation for draw to get the list of supported shapes that you can sketch on the map.

Drawing FeatureSet objects on the map

In addition to sketches, you can send FeatureSet objects to the draw() method. This capability comes in handy as you can get a FeatureSet object through various different operations using the Python API. For instance, you can get results of a geocoding operation as a FeatureSet, results of a query() operation on a FeatureLayer as a FeatureSet that can you visualize on the map using the draw() method.

The snippet below geocodes the locations of a few capitol buildings in the USA.

In [19]:
from arcgis.geocoding import geocode
usa_extent = geocode('USA')[0]['extent']
{'xmax': -45.931619189999935,
 'xmin': -152.89761918999994,
 'ymax': 84.9,
 'ymin': -14.084296843999937}
In [25]:
usa_capitols_fset = geocode('Capitol', search_extent=usa_extent, max_locations=10, as_featureset=True)
<FeatureSet> 10 features

Drawing with custom symbols

While drawing a graphic, you can specify a custom symbol. Users of the Python API can make use of a custom symbol selector web app and pick a symbol for point layers. For instance, you can pick a business marker symbol for the capitol buildings as shown below:

In [26]:
capitol_symbol = {"angle":0,"xoffset":0,"yoffset":0,"type":"esriPMS",

usa_map.draw(usa_capitols_fset, symbol=capitol_symbol)

Clearing the drawn graphics

You can clear all drawn graphics from the map by calling the clear_graphics() method.

In [ ]:

Saving the map as a web map

Starting with the Python API version 1.3, you can save the map widget as a web map in your GIS. This process persistes all the basemaps, layers added with or without your custom symbology including smart mapping, pop-ups, extent, graphics drawn with or without custom symbols as layers in your web map.

To save the map, call the save() method. This method creates and returns a new Web Map Item object. As parameters, you can specify all valid Item properties as shown below:

In [28]:
webmap_properties = {'title':'USA time zones and capitols',
                    'snippet': 'Jupyter notebook widget saved as a web map',
                    'tags':['automation', 'python']}

webmap_item =, thumbnail='./webmap_thumbnail.png', folder='webmaps')
USA time zones and capitols
Jupyter notebook widget saved as a web mapWeb Map by arcgis_python
Last Modified: December 06, 2017
0 comments, 0 views

You can use this web map back in the notebook, or in any ArcGIS app capabale of rendering web maps. To learn how you can use this read this web map using the Python API, refer to the guide titled working with web maps and scenes

Feedback on this topic?