Map

Summary

The Map is the primary object for referencing and managing layers and tables within an ArcGIS Pro project.

Discussion

A Map in ArcGIS Pro represents a collection of tabular and symbolized geographic layers and also persists information like coordinate system, default views of the data, and various other metadata. The only way to visualize the contents of a Map is in either a map view, that is, as a tab in the application with its own table of contents, or in a map frame on a page layout. The same map can be displayed in multiple map views or map frames. If a layer is added to a map, all map views and map frames that reference that map will display the added layer. If you want a different collection of layers or tables to be displayed in different views, you will need to build and use different maps.

Maps are accessed using the listMaps function from the ArcGISProject object and it returns a Python list of Map objects. It is important to uniquely name each map so a specific map can be easily referenced using its name property. A map can also be accessed from a MapFrame object using the map property. Note: arcpy.mp does not provide access to map views within the application; it only provides access to MapFrames.

There are a number methods available on the Map object that allow you to manage its collection of tabular and symbolized geographic layers. Layers and tables can be added (addLayer, addLayerToGroup, addTable, or insertLayer), removed (removeLayer or removeTable), and rearranged (moveLayer) within the list of existing layers and tables. The listLayers and listTables methods are how you reference Layers and Tables in a map.

Every map has a mapType property. It either has the value MAP, which represents a 2D map, or the value SCENE, which is a 3D map. One example for needing to know the mapType property is if you want to set the defaultCamera property. You can't apply a 3D Camera object to a 2D map or the other way around. Therefore, you should check the mapType value ahead of time.

Properties

Property	Explanation	Data Type
defaultCamera (Read and Write)	Provides the ability to get or set default Camera settings for a map. Note: Modifying the defaultCamera will not affect an existing view. This property is only applied when a new MapView is opened or a new MapFrame is inserted into a layout.	Camera
defaultView (Read Only)	Used in conjunction with ConvertWebMapToArcGISProject in a web map printing web tool to return a map view to print or export.	MapView
mapType (Read Only)	Returns a string value that reports the Map object's type information. If the Map is 2D, MAP is returned. If the Map is 3D, SCENE is returned.	String
mapUnits (Read Only)	Returns a string value that represents the map units set for the Map.	String
metadata (Read and Write)	Get or set the map's Metadata class information. Note: Setting metadata is dependent on the isReadOnly property value.	Metadata
name (Read and Write)	Provides the ability to get or set the Map object's name as it appears in the table of contents and also the actual name of the element in a layout.	String
referenceScale (Read and Write)	Provides the ability to get or set the reference scale for the Map. To clear the reference scale, set the value to 0.0	Double
spatialReference (Read and Write)	Provides the ability to get or set the SpatialReference associated with the map.	SpatialReference
URI (Read Only)	The Universal Resource Indicator for a map. It is a unique identifier for a map in a project and is sometimes required when using Python CIM access. Once a map is added and the URI is established, the value does not change over time. For example, if you modify the map's name, the URI will not change.	String

Method Overview

Method	Explanation
addBasemap (basemap_name)	addBasemap provides the ability to add or replace a basemap layer within a map.
addDataFromPath (data_path)	addDataFromPath provides the ability to add a Layer to a map in a project (.aprx) by providing a local path or URL.
addLayer (add_layer_or_layerfile, {add_position})	Provides the ability to add a Layer or LayerFile to a map within a project (.aprx) using basic placement options.
addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})	Provides the ability to add a Layer or the contents of a LayerFile to an existing group layer in a map within a project (.aprx) using basic placement options.
addTable (add_table)	Provides the ability to add a Table to a map within a project (.aprx).
clearSelection ()	Clears the selection for all layers and tables in a map.
exportToMAPX (out_mapx)	Exports a Map to a map file.
getDefinition (cim_version)	Gets a map's CIM definition.
getWebLayerSharingDraft (server_type, service_type, service_name, {layers_and_tables})	Creates a sharing draft from a map that can be configured and shared to ArcGIS Enterprise or ArcGIS Online.
insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})	Provides the ability to add a Layer or LayerFile to a map within a project (.aprx) by specifying a specific location.
listBookmarks ({wildcard})	Returns a Python list of bookmark objects in a Map.
listBrokenDataSources ()	Returns a Python list of Layer or Table objects that have broken connections to their original source data within a map.
listLayers ({wildcard})	Returns a Python list of Layer objects that exist within a map.
listTables ({wildcard})	Returns a Python list of Table objects that exist within a map.
moveLayer (reference_layer, move_layer, {insert_position})	Provides the ability to move a layer or group layer in a map to a specific location in the layer stack.
removeLayer (remove_layer)	Provides the ability to remove a layer from a map in a project.
removeTable (remove_table)	Provides the ability to remove a table from a map in a project.
setDefinition (definition_object)	Sets a map's CIM definition.
updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})	Replaces connection properties using a dictionary or a path to a workspace.

Methods

addBasemap (basemap_name)

Parameter	Explanation	Data Type
basemap_name	The name of the basemap as it appears in the basemap gallery.	String

The addBasemap method works in the same way as the Basemap control works on the Map ribbon. If a basemap does not exist, a new one will be added. If one or more basemaps already exist, they will be replaced by the one being added.

If you want to add more than one basemap to your map, save a basemap to a layer file and add it using the LayerFile and addLayer methods.

addDataFromPath (data_path)

Parameter	Explanation	Data Type
data_path	A string that represents a local path or URL. (The default value is None)	String

Return Value

Data Type	Explanation
Layer	A Layer object.

The addDataFromPath method provides a way to add a layer to a map in a similar way to how the Add Data From Path button works in the application; it places each layer based on layer weight rules and geometry type. For more precise layer placement control, refer to the moveLayer method.

addLayer (add_layer_or_layerfile, {add_position})

Parameter	Explanation	Data Type
add_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
add_position	A constant that determines the placement of the added layer or layers in a map. AUTO_ARRANGE—Automatically places the layer or layers based on its layer weight rules and geometry. BOTTOM—Places the layer or layers at the bottom of the TOC layer stack. TOP—Places the layer or layers at the top of the TOC layer stack. (The default value is AUTO_ARRANGE)	String

Return Value

Data Type	Explanation
List	A Python list of Layer objects.

The addLayer method provides a way to add a layer or collection of layers into a map. The default add_position adds the layers using the same auto-arrange logic that places layers in a map similarly to how the Add Data button works in the application; it places each layer based on layer weight rules and geometry type. The other placement choices are either at the TOP or the BOTTOM of a the layer stack. For more precise layer placement control, refer to the insertLayer method.

The layer that is added can reference an already existing layer in a the same project or separate project, or reference a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file. Refer to LayerFile for more information on layer files.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through addLayer.

addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})

Parameter	Explanation	Data Type
target_group_layer	A reference to an existing group Layer object.	Layer
add_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
add_position	A constant that determines the placement of the added layer or layers in the target_group_layer. AUTO_ARRANGE—Automatically places the layer based on its layer weight rules and geometry. BOTTOM—Places the layer at the bottom of the TOC layer stack. TOP—Places the layer at the top of the TOC layer stack. (The default value is AUTO_ARRANGE)	String

The addLayerToGroup method is the only way to add a layer or collection of layers into an existing, empty group layer in a map. The default add_position adds the layers using the same auto-arrange logic that places layers in a map similarly to how the Add Data button works in the application; it places each layer based on layer weight rules and geometry type. The other placement choices are either at the TOP or the BOTTOM of the layer stack. For more precise layer placement control, refer to the insertLayer method.

The layer that is added can reference an already existing layer in the same project or separate project, or reference a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file. Refer to LayerFile for more information on layer files.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through addLayerToGroup.

addTable (add_table)

Parameter	Explanation	Data Type
add_table	A reference to a Table object representing the table to be added.	Table

Return Value

Data Type	Explanation
Table	A reference to a Table object.

The addTable method provides a way to add tables into a map. The table you want to add can either be a table in an existing map using the listTables method on the Map object or it can be a table on disk or in a database that is referenced with the Table function.

clearSelection ()

Clears the selection for all layers and tables in a map.

exportToMAPX (out_mapx)

Parameter	Explanation	Data Type
out_mapx	A string used to save a Map to a map file (.mapx).	String

This method is useful if you want to save a map to a map file that can be imported later into a project using the ArcGISProject importDocument method.

getDefinition (cim_version)

Parameter	Explanation	Data Type
cim_version	A string that represents the major version of the CIM.	String

CIM-level access to additional object properties was introduced at version 2.4. Esri follows the semantic versioning specification. This means that until the next major release—for example, 3.0—when breaking API changes are allowed, the value to be used with cim_version is V2. Once 3.0 is released, a new V3 option will become available. This gives Python script authors control over the CIM version that will be used during execution if there is a possibility that breaking changes may be introduced in the new version.

For more information about working with the CIM and samples, see Python CIM Access.

getWebLayerSharingDraft (server_type, service_type, service_name, {layers_and_tables})

Parameter	Explanation	Data Type
server_type	A string representing the server type. The following server types are supported: HOSTING_SERVER—Supports publishing either a web feature layer or a web tile layer to ArcGIS Enterprise or ArcGIS Online. Use this option when specifying FEATURE or TILE in the service_type parameter. FEDERATED_SERVER—Supports publishing a map image layer to a ArcGIS Enterprise portal federated server. Use this option when specifying MAP_IMAGE in the service_type parameter. Tip: The getWebLayerSharingDraft function does not support publishing map services to ArcGIS Server. Instead, use the arcpy.sharing.CreateSharingDraft function.	String
service_type	A string representing the service type. The following service types are supported: FEATURE— Creates a FeatureSharingDraft for a web feature layer. TILE— Creates a TileSharingDraft for a web tile layer. MAP_IMAGE— Creates a MapImageSharingDraft for a map image layer.	String
service_name	A string that represents the name of the service. This is the name people will see and use to identify the service. The name can only contain alphanumeric characters and underscores. No spaces or special characters are allowed. The name cannot be more than 120 characters in length.	String
layers_and_tables	A list of layers and tables from the map. If left blank, the entire map will be published. This parameter allows you to choose a subset of layers and tables from the map to publish. The layers and tables must be from the same map that is being published.	List

Return Value

Data Type	Explanation
Object	Returns either a FeatureSharingDraft, TileSharingDraft, or MapImageSharingDraft class object.

The getWebLayerSharingDraft function creates a sharing draft from a map in an ArcGIS Pro project. A sharing draft is a configurable set of properties for a web layer. After the sharing draft has been configured, it can then be saved to a service definition draft (.sddraft) file using the exportToSDDraft function from either the FeatureSharingDraft, TileSharingDraft, or MapImageSharingDraft classes. It can then be staged and shared to either ArcGIS Enterprise or ArcGIS Online using the Stage Service and Upload Service Definition tools. For more information, see Introduction to the sharing module.

insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})

Parameter	Explanation	Data Type
reference_layer	A Layer object representing an existing layer that determines the location where the new layer will be inserted.	Layer
insert_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
insert_position	A constant that determines the placement of the added layer or layers relative to the reference_layer. AFTER—Inserts the new layer after or below the reference layer. BEFORE—Inserts the new layer before or above the reference layer. (The default value is BEFORE)	String

The insertLayer method is a more precise way of positioning a layer into a map or a group layer because a reference_layer is used to specify the exact location. The layer is either added before or after the reference_layer.

If the reference_layer references a layer at the root level of a map, the inserted layer will be added to the root level. If the reference_layer references a layer within a group layer, the inserted layer will be added into the group. Because a reference_layer is a required parameter, it is not possible to use insert_layer to add a layer into an empty map or an empty group layer. UseaddLayer or addLayerToGroup methods to add a layer or collection of layers into an empty map or group layer, respectively.

The layer that is inserted can reference an already existing layer in a the same project or separate project, or reference a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file. Refer to LayerFile for more information on layer files.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through insertLayer.

listBookmarks ({wildcard})

Parameter	Explanation	Data Type
wildcard	A wildcard is based on the bookmark name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list. (The default value is None)	String

Return Value

Data Type	Explanation
List	The listBookmarks method always returns a Python list object even if only one broken layer or table is returned.

Returns a Python list of bookmark objects in a Map.

listBrokenDataSources ()

Return Value

Data Type	Explanation
List	A Python list of Layer or Table objects.

The listBrokenDataSources method always returns a Python list object even if only one broken layer or table is returned.

listLayers ({wildcard})

Parameter	Explanation	Data Type
wildcard	A wildcard is based on the layer name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list. (The default value is None)	String

Return Value

Data Type	Explanation
List	Returns a Python list of Layer objects in a map.

Returns a Python list of Layer objects that exist in a map. ListLayers always returns a list object even if only one table is returned.

It is possible that there might be layers in a map that have the same name. If that is the case, then other properties may need to be used to isolate a specific layer. Properties such as a layer's datasource or definitionQuery could be used to do this. It is ideal that all layers in a map be uniquely named.

listTables ({wildcard})

Parameter	Explanation	Data Type
wildcard	A wildcard is based on the layer name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list. (The default value is None)	String

Return Value

Data Type	Explanation
List	A Python list of Table objects in a map.

Returns a Python list of Table objects that exist within a map. ListTables always returns a list object even if only one table is returned.

It is possible that there might be tables in a map that have the same name. If that is the case, then other properties may need to be used to isolate a specific layer. Properties such as a tables's datasource or definitionQuery could be used to do this. It is ideal that all tables in a map be uniquely named.

moveLayer (reference_layer, move_layer, {insert_position})

Parameter	Explanation	Data Type
reference_layer	A Layer object representing an existing layer that determines the location where the new layer will be moved.	Layer
move_layer	A reference to a Layer object representing the layer to be moved.	Layer
insert_position	A constant that determines the placement of the moved layer relative to the reference layer. AFTER—Moves the layer after or below the reference layer. BEFORE—Moves the layer before or above the reference layer. (The default value is BEFORE)	String

The moveLayer method will move a layer within a map and also into and out of group layers in the same map. The move_layer and reference_layer must reside in the same map. A layer cannot be moved from one map to a different map even within the same project. Use addLayer, addLayerToGroup, or insertLayer instead.

removeLayer (remove_layer)

Parameter	Explanation	Data Type
remove_layer	A reference to a Layer object representing the layer to be removed.	Layer

RemoveLayer will remove a single layer or group layer from a specific map. If there is more than one layer that meets the criteria, then only the first layer will be removed unless the script iterates through each layer in a returned list.

removeTable (remove_table)

Parameter	Explanation	Data Type
remove_table	A reference to a Table object representing the layer to be removed.	Table

RemoveTable will remove a single table from a specific map. If there is more than one table that meets the criteria, then only the first table will be removed unless the script iterates through each table in a returned list.

setDefinition (definition_object)

Parameter	Explanation	Data Type
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

For more information about working with the CIM and samples, see Python CIM Access.

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})

Parameter	Explanation	Data Type
current_connection_info	A string that represents the workspace path or a Python dictionary that contains connection properties to the source you want to update.	String
new_connection_info	A string that represents the workspace path or a Python dictionary that contains connection properties with the new source information.	String
auto_update_joins_and_relates	If set to True, the updateConnectionProperties method will also update the connections for associated joins or relates. (The default value is True)	Boolean
validate	If set to True, the connection properties will only be updated if the new_connection_info value is a valid connection. If it is not valid, the connection will not be replaced. If set to False, the method will set all connections to match the new_connection_info, regardless of a valid match. In this case, if a match does not exist, then the data sources would be broken. (The default value is True)	Boolean
ignore_case	Determines whether searches will be case sensitive or not. By default, queries are case sensitive. To perform case-insensitive queries, set ignore_case to True. (The default value is False)	Boolean

For more detailed discussion, parameter information, scenarios, and code samples, refer to the Updating and fixing data sources help topic.

Code sample

Map example 1

The following script references a layer file and inserts the layer into a map above a layer that already exists in the map.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
insertLyr = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Ranger Stations.lyrx")
m = aprx.listMaps("Yosemite National Park")[0]
refLyr = m.listLayers("Points of Interest")[0]
m.insertLayer(refLyr, insertLyr, "BEFORE")
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite_updated.aprx")

Map example 2

The following script will set the defaultCamera property for all maps and scenes currently in a project. The camera properties will be copied from existing map frames that have the desired viewer settings. All maps will be copied from a 2D map frame, and all scene viewer settings will be copied from a 3D map frame.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions*")[0]
mpFrm2D = lyt.listElements("mapframe_element", "Yose*")[0]
mpFrm3D = lyt.listElements("mapframe_element", "Inset1")[0]
for m in aprx.listMaps():
    if m.mapType == "MAP":
        m.defaultMapViewer = mpFrm2D.mapViewer
    elif m.mapType == "SCENE":
        m.defaultMapViewer = mpFrm3D.mapViewer
aprx.save()
del aprx