Summary
The Map object 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 such as 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 MapView, that is, as a tab in the application with its own table of contents, or in a map frame on a 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 the function returns a Python list of Map objects. It is important to uniquely name each map so a specific map can be easily referenced with the wildcard parameter that uses the name property. A map can also be accessed from a MapFrame object using the map property.
The createMap method on the ArcGISProject class allows you to create a map in a project. If you run a script from within the application, it will honor the basemap settings. If you run a script outside of the application, it will automatically add a topographic basemap and you will need to remove the basemap layer if not needed.
The openView method is also a way to open a map view. You may want to do a couple of things before calling openView. First, setting the defaultCamera prior to opening a new view will control the initial extent. Second, you may want to close other views with the closeViews method on the ArcGISProject class before opening your new view. The third sample below illustrates this workflow.
There are a number of 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 vice versa. Therefore, you should check the mapType value ahead of time.
The map class also supports getDefinition and setDefinition methods. For more detailed help, see Python CIM access.
Properties
Property | Explanation | Data Type |
defaultCamera (Read and Write) | Provides the ability to get or set default Camera settings for a map. | 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 |
transformations (Read Only) | Returns the horizontal and vertical transformations associated with the map as a Python Dictionary. The dictionary key for horizontal transformations is 2D and 3D for vertical transformations. To modify the existing transformations, use updateTransformations. | Dictionary |
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, {web_service_type}, {custom_parameters}) | addDataFromPath allows you 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). |
addTableToGroup (target_group_layer, add_table) | Provides the ability to add a Table to an existing group layer in a map within a project (.aprx). |
clearSelection () | Clears the selection for all layers and tables in a map. |
createGroupLayer (name, {group_layer}) | Allows you to create a group layer in a map within a project (.aprx). |
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. |
openView () | Opens and activates a new map view pane in the application. |
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}) | The updateConnectionProperties method replaces connection properties using a dictionary or a path to a workspace. |
updateTransformations (transformations) | The updateTransformations method replaces a map's transformations using a dictionary. |
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, {web_service_type}, {custom_parameters})
Parameter | Explanation | Data Type |
data_path | A string that represents a local path or URL. (The default value is None) | String |
web_service_type | A string that represents the type of web service connection. When you are working with a service URL that is hosted on a third-party server and the URL is not deterministic, you must specify the service type from the list to add the data. The default value of AUTOMATIC will not work if the custom_parameters dictionary is provided.
(The default value is AUTOMATIC) | String |
custom_parameters | A Python dictionary of custom connection parameters. The KML data_service_type does not support custom properties. (The default value is None) | Dictionary |
Data Type | Explanation |
Layer | A Layer object. |
The addDataFromPath method allows you 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.
When you add ArcGIS Server services, vector tile services, or WMS services, you can add custom request parameters. These are key-value pairs that can be appended to the URL for all resources and operations fetched by the service layer. These are often access keys to allow access to restricted data. In some cases, you must specify the access key-value pair to add the data. Contact the administrator of the service for the access keys if you are working with restricted access services.
For more information, see Add layers to a map or scene.
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.
(The default value is AUTO_ARRANGE) | String |
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.
(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 |
Data Type | Explanation |
Table | A reference to a Table object. |
addTableToGroup (target_group_layer, add_table)
Parameter | Explanation | Data Type |
target_group_layer | A reference to an existing group layer. | Layer |
add_table | A reference to a Table object. | Table |
The addTableToGroup method is the only way to add a table to an existing group layer in a map. The table that is added can reference an already existing table in the same project, a table in a separate project, or a table in a layer file (.lyrx) on disk.
If you reference a table already in the same map and you add the table to a group, it will create a duplicate table and you may want to delete the original table reference.
clearSelection ()
Clears the selection for all layers and tables in a map.
createGroupLayer (name, {group_layer})
Parameter | Explanation | Data Type |
name | A string that represents the name of the new group layer. | String |
group_layer | A reference to an existing group layer into which to insert the new group layer. Use this parameter to create nested group layers. | Layer |
Data Type | Explanation |
Layer | A reference to the new group layer. |
The createGroupLayer method allows you to create a group layer in a map. The group layer will be created at the first position in the map's table of contents. The group layer can also be created within an existing group layer to create nested group layers. After the group layer is created, it can be moved to another position in the map's table of contents by using the moveLayer method.
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 ArcGIS Pro 2.4. When you want to return an object's CIM definition, you must specify a cim_version. Esri follows the semantic versioning specification. This means that at major releases—for example, 3.0—breaking API changes are allowed. This allows Python script authors control over which version of the CIM is used during a script run if there is a possibility breaking changes may be introduced in the new version. If you are authoring scripts for ArcGIS Pro 2.x, specify the cim_version to be 'V2'. If you are authoring scripts for ArcGIS Pro 3.x, specify the cim_version to be 'V3'. Scripts authored using cim_version 'V2' will continue to work in ArcGIS Pro 3.x.
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:
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:
| 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 contain alphanumeric characters, spaces, and underscores. No 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. Note:If you specify a layer or table that participates in a relationship class when publishing a web feature layer or a map image layer, all layers or tables involved in the relationship class will be published. | List |
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 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.
(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 |
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 ()
Data Type | Explanation |
List |
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 |
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 |
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.
(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.
openView ()
This is useful if the map view is not already open or another view is active in the application. The method creates a map view zoomed to its default extent and activates it. To close other, existing views before opening a new view, use the ArcGISProject closeViews method.
There are two techniques for controlling the desired extent of your map view. First, prior to opening the view, you can set the defaultCamera for your map. Second, you can change the MapView camera extent after it is opened.
Note:
This method is designed to be run in the application using a script tool, Notebook, or the Python window. It will have no effect if run outside of the application.
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. If an empty string or None is used in current_connection_info, all connection properties will be replaced with the new_workspace_info, depending on the value of the validate parameter. | 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 value, regardless of a valid match. In this case, if a match does not exist, the data sources would be broken. (The default value is True) | Boolean |
ignore_case | Determines whether searches will be case sensitive. By default, queries are case sensitive. To perform queries that are not case sensitive, set ignore_case to True. (The default value is False) | Boolean |
For more detailed discussion, parameter information, scenarios, and code samples, see Updating and fixing data sources.
updateTransformations (transformations)
Parameter | Explanation | Data Type |
transformations | The dictionary keys are defined below.
| Dictionary |
To update a map's transformations, you must set the entire set of transformations. You cannot add, remove, or update a single transformation at a time. You can build a new dictionary from scratch or you can modify the dictionary returned by the transformations property and push the entire dictionary back to the map using the updateTransformations method.
Code sample
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")
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.defaultCamera = mpFrm2D.camera
elif m.mapType == "SCENE":
m.defaultCamera = mpFrm3D.camera
aprx.save()
del aprx
The following script uses the keyword current, so it should be run from the Python window. The script creates a new map and adds new layers to it. The map's default camera property is updated, which controls the extent of newly opened views. The map view is then exported to PDF. The newly created map is then removed from the project.
aprx = arcpy.mp.ArcGISProject("CURRENT")
#Create a copy of an existing map
newMap = aprx.createMap("Ranger Stations", "Map")
#Add ranger stations layer file
lyrx1 = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Park Boundary.lyrx")
newMap.addLayer(lyrx1)
lyrx2 = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Ranger Stations.lyrx")
newMap.addLayer(lyrx2)
#Close any current map or layout views
aprx.closeViews("MAPS_AND_LAYOUTS")
#Set the default map camera to the extent of the park boundary before opening the new view
#default camera only affects newly opened views
lyr = newMap.listLayers("*Park Boundary")[-1]
newMap.defaultCamera.setExtent(arcpy.Describe(lyr).extent)
newMap.openView()
#export the newly opened active view to PDF, then delete the new map
mv = aprx.activeView
mv.exportToPDF(r"C:\Temp\RangerStations.pdf", width=700, height=500, resolution=96)
aprx.deleteItem(newMap)