arcgis.widgets module¶

MapView¶

class arcgis.widgets.MapView(**kwargs)¶

Bases: ipywidgets.widgets.domwidget.DOMWidget

Mapping widget for Jupyter Notebook and JupyterLab.

Argument	Description
gis	The active GIS() instance you want this map widget to use.
item	A WebMap or WebScene item instance that you want to visualize
mode	Whether to construct a ‘2D’ map or ‘3D’ map. See the mode property for more information.

Note

Note: If the Jupyter Notebook server is running over http, you need to configure your portal/organization to allow your host and port; or else you will run into CORs issues.

This can be accomplished by signing into your portal/organization in a browser, then navigating to:

Organization > Settings > Security > Allow origins > Add > http://localhost:8888 (replace with the host/port you are running on)

add_layer(item, options=None)¶

Adds the specified layer or item to the map widget.

Argument

Description

item

Required object. You can specify Item objects, Layer objects such as FeatureLayer, ImageryLayer, MapImageLayer, FeatureSet, FeatureCollection, arcgis.raster.Raster objects, etc.

Item objects will have all of their layers individually added to the map widget.

options

Optional dict. Specify visualization options such as renderer info, opacity, definition expressions. See example below

Warning

Calling MapView.add_layer() on an arcgis.raster.Raster instance has the following limitations:

Local raster overlays do not persist beyond the notebook session on published web maps/web scenes – you would need to seperately publish these local rasters.
The entire raster image data is placed on the MapView’s canvas with no performance optimizations. This means no pyramids, no dynamic downsampling, etc. Please be mindful of the size of the local raster and your computer’s hardware limitations.
Pixel values and projections are not guaranteed to be accurate, especially when the local raster’s Spatial Reference doesn’t reproject accurately to Web Mercator (what the MapView widget uses).

# USAGE EXAMPLE: Add a feature layer with smart mapping renderer and
# a definition expression to limit the features drawn.
map1 = gis.map("Seattle, WA")
map1.add_layer(wa_streets_feature_layer, {'renderer':'ClassedSizeRenderer',
                                          'field_name':'DistMiles',
                                          'opacity':0.75})

property basemap¶

What basemap you would like to apply to the widget (‘topo’, ‘national-geographic’, etc.). See basemaps for a full list

# Usage example: Set the widget basemap equal to an item: from arcgis.mapping import WebMap widget = gis.map() # Use basemap from another item as your own widget.basemap = webmap widget.basemap = tiled_map_service_item widget.basemap = image_layer_item widget.basemap = webmap2.basemap widget.basemap - ‘national-geographic’

basemaps = ['dark-gray', 'dark-gray-vector', 'gray', 'gray-vector', 'hybrid', 'national-geographic', 'oceans', 'osm', 'satellite', 'streets', 'streets-navigation-vector', 'streets-night-vector', 'streets-relief-vector', 'streets-vector', 'terrain', 'topo', 'topo-vector']¶: A list of possible basemaps to set .basemap with

property center¶

A property that represents the map widget’s center.

getter	A dict that represents the JSON of the map widget’s center.
setter	A [lat, long] list, or a dict that represents the JSON of the map widget’s center.

clear_graphics()¶: Clear the graphics drawn on the map widget. Graphics are shapes drawn using the ‘draw()’ method.

display_message(msg)¶: Displays a message on the upper-right corner of the map widget. You can only send one message at a time, multiple messages don’t show.

draw(shape, popup=None, symbol=None, attributes=None)¶

Draws a shape on the map widget. You can draw anything from known geometries, coordinate pairs, FeatureSet objects.

Argument	Description
shape	Required object. Known geometries: Shape is one of [“circle”, “ellipse”, “polygon”, “polyline”, “multipoint”, “point”, “rectangle”, “triangle”]. Coordinate pair: specify shape as a list of [lat, long]. Eg: [34, -81] FeatureSet: shape can be a FeatureSet object. Dict object representing a geometry.
popup	Optional dict. Dict containing “title” and “content” as keys that will be displayed when the shape is clicked. In case of a FeatureSet, “title” and “content” are names of attributes of the features in the FeatureSet instead of actual string values for title and content.
symbol	Optional dict. symbol is specified in json format as described at http://resources.arcgis.com/en/help/arcgis-rest-api/index.html# //02r3000000n5000000. A default symbol is used if one is not specified. Tip: a helper utility to get the symbol format for several predefined symbols is available at http://esri.github.io/arcgis-python-api/tools/symbol.html
attributes	Optional dict. Specify a dict containing name value pairs of fields and field values associated with the graphic.

embed(output_in_cell=True, set_as_preview=True)¶

Embeds the current state of the map into the underlying notebook as an interactive HTML/JS/CSS element. This element will always display this ‘snapshot’ state of the map, regardless of any future Python code ran.

Argument	Description
output_in_cell	Optional bool, default True. Will display the embedded HTML interactive map in the output area of the cell where this function is called.
set_as_preview	Optional bool, default True. Will display the embedded HTML interactive map in the cell where the map widget is being displayed. Use this flag if you want the generated HTML previews of your notebook to have an interactive map displayed.

In all notebook outputs, each embedded HTML element will contain the entire map state and all relevant HTML wrapped in an <iframe> element. This means that the data for the embedded HTML element lives inside the notebook file itself, allowing for easy sharing of notebooks and generated HTML previews of notebooks.

Note

When this function is called with set_as_preview = True, the embedded HTML preview element will overwrite the static image preview from any previous MapView.take_screenshot(set_as_preview=True) call

Note

Any embedded maps must only reference publicly available data. The embedded map must also have access to the https://unpkg.com to load the necessry JavaScript components on the page

property end_time¶: datetime.datetime property. If time_mode == “time-window”, represents the upper bound ‘thumb’ of the time slider. For all other time_mode values, not used.

export_to_html(path_to_file, title='Exported ArcGIS Map Widget', credentials_prompt=False)¶

Takes the current state of the map widget, and exports it to a standalone HTML file that can be viewed in any web browser.

By default, only publically viewable layers will be visible in any exported html map. Specify credentials_prompt=True to have a user be prompted for their credentials when opening the HTML page to view private content.

Warning

Follow best security practices when sharing any HTML page that prompts a user for a password.

Note

You cannot successfully authenticate if you open the HTML page in a browser locally like file://path/to/file.html. The credentials prompt will only properly function if served over a HTTP/HTTPS server.

Argument	Description
path_to_file	Required string. The path to save the HTML file on disk.
title	Optional string. The HTML title tag used for the HTML file.
credentials_prompt	Optional boolean, default False. If set to True, will display a credentials prompt on HTML page load for users to authenticate and view private content.

property extent¶

A property representing the map widget’s extent.

getter

A dict that represents the JSON of the map widget’s extent.

setter

A [[xmin, ymin], [xmax, ymax]] list, Spatially Enabled Data Frame full_extent, or a dict that represents the JSON of the map widget’s extent.

Examples for each: web_map.extent = [[-124.35, 32.54], [-114.31, 41.95]] web_map.extent = data_frame.spatial.full_extent web_map.extent = {

“xmin”: -124.35, “ymin”: 32.54, “xmax”: -114.31, “ymax”: 41.95

}

property gallery_basemaps¶: View your portal’s custom basemap group

property heading¶: For 3D mode, the compass heading of the camera in degrees. Heading is zero when north is the top of the screen. It increases as the view rotates clockwise. The angles are always normalized between 0 and 360 degrees. Note that you can NOT set heading in 2D mode. 2D mode uses the ‘rotation’ property.

hide_mode_switch¶: When set to ‘True’ will hide the 2D/3D switch button from the widget. Note that once the button is hidden, it cannot be made visible again: you have to create a new MapView instance.

jupyter_target¶: A readonly string that is either ‘lab’ or ‘notebook’: represents if this widget is drawn in a Jupyter Notebook environment, or a JupyterLab environment

property layers¶: A list of the JSON representation of layers added to the map widget using the add_layers() method

legend¶: If set to True, will display a legend in the widget that will describe all layers added to the map. If set to False, will hide the legend. Default: False.

property local_raster_file_format¶

String getter/setter. When calling map.add_layer(arcgis.raster.Raster()) for a local raster file, an intermediate image file must be written to disk in order to successfully display on the map. This file format can be one of the following:

Possible Values	Description
`"jpg"` (Default)	Write raster to a `.JPG` file. This results in a lossy image, but should draw quicker than a `.PNG` file. Requires the `PIL` image processing package (distributed under the name of it’s active fork, “Pillow”)
`"png"`	Write raster to a `.PNG` file. This results in a lossless image, but it might take a longer time to draw than a `.JPG` file.

mode¶

The string that specifies whether the map displays in ‘2D’ mode (MapView) or ‘3D’ mode (SceneView). Possible values: ‘2D’, ‘3D’.

Note that you can also toggle between '2D' and '3D' mode by pressing the icon in the widget UI.

on_click(callback, remove=False)¶

Register a callback to execute when the map is clicked. The callback will be called with one argument, the clicked widget instance.

Argument	Description
remove	Optional boolean. Set to true to remove the callback from the list of callbacks.

on_draw_end(callback, remove=False)¶

Register a callback to execute when something is drawn. The callback will be called with two arguments: the clicked widget instance, and the geometry drawn

Argument	Description
remove	Optional boolean. Set to true to remove the callback from the list of callbacks.

print_service_url¶: Note

Note: this property is obselete as of >v1.6 of the Python API, since the underlying JavaScript code ran during a take_screenshot() Python call has been has been changed to MapView.takeScreenshot() instead of calling a Print Service URL. Any value you set to this property will be ignored (2D screenshots will still be taken successfully).

ready¶: A readonly bool that represents if the map widget has been drawn in the notebook

remove_layers(layers=None)¶

Removes the layers added to the map widget. You can get the list of layers added to the widget by querying the ‘layers’ property.

Argument	Description
layers	Optional list. Specify the list of layers to be removed from the map widget. You can get the list of layers on the map by querying the ‘layers’ property. If not specified, it removes all layers added to the widget.

Returns: True if layer is successfully removed. Else, False.

property rotation¶: For 2D mode, the clockwise rotation of due north in relation to the top of the view in degrees. Note that you can NOT set rotation in 3D mode. 3D mode uses the ‘heading’ property.

save(item_properties, mode=None, thumbnail=None, metadata=None, owner=None, folder=None)¶

Save the map widget object into a new web map Item or a new web scene item in your GIS.

Note

If you started out with a fresh map widget object, use this method to save it as a the webmap/webscene item in your GIS. If you started with a map widget object from an existing webmap/webscene object, calling this method will create a new item with your changes. If you want to update the existing item with your changes, call the update() method instead.

Note

Saving as a WebScene item only works in a Jupyter environment: the map must be visually displayed in the notebook before calling this method.

Argument	Description
item_properties	Required dictionary. See table below for the keys and values.
mode	Optional string. Whether to save this map instance as a 2D WebMap, or a 3D WebScene. Possible strings: “2D”, “webmap”, “3D”, or “webscene”.
thumbnail	Optional string. Either a path or URL to a thumbnail image.
metadata	Optional string. Either a path or URL to the metadata.
owner	Optional string. User object corresponding to the desired owner of this item. Defaults to the logged in user.
folder	Optional string. Name of the folder where placing item.

Key:Value Dictionary Options for Argument item_properties

Key	Value
typeKeywords	Optional string. Provide a lists all sub-types, see URL 1 below for valid values.
description	Optional string. Description of the item.
title	Optional string. Name label of the item.
tags	Optional string. Tags listed as comma-separated values, or a list of strings. Used for searches on items.
snippet	Optional string. Provide a short summary (limit to max 250 characters) of the what the item is.
accessInformation	Optional string. Information on the source of the content.
licenseInfo	Optional string. Any license information or restrictions regarding the content.
culture	Optional string. Locale, country and language information.
access	Optional string. Valid values are private, shared, org, or public.
commentsEnabled	Optional boolean. Default is true, controls whether comments are allowed (true) or not allowed (false).
culture	Optional string. Language and country information.

URL 1: http://resources.arcgis.com/en/help/arcgis-rest-api/index.html# //02r3000000ms000000 :return:

Item object corresponding to the new web map Item created.

USAGE EXAMPLE: Save map widget as a new web map item in GIS
map1 = gis.map("Italy")
map1.add_layer(Italy_streets_item)
map1.basemap = 'dark-gray'
italy_streets_map = map1.save({'title':'Italy streets',
                             'snippet':'Arterial road network of Italy',
                             'tags':'streets, network, roads'})

property scale¶

The map scale at the center of the view. If set to X, the scale of the map would be 1:X.

For continuous values to apply and not get “snapped” to the closest level of detail, set mapview.snap_to_zoom = False.

# Usage example: Sets the scale to 1:24000: map = gis.map() map.scale = 24000

classmethod set_js_cdn(js_cdn)¶

Call this function before the creation of any MapView object, and each instantiated object will use the specified js_cdn parameter as the ArcGIS API for JavaScript CDN URL instead of the default http://js.arcgis.com/4.X/. This functionality is necessary in disconnected environments if the portal you are connecting to doesn’t ship with the minimum necessary JavaScript API version.

You may not need to call this function to view the widget in disconnected environments: if your computer cannot reach js.arcgis.com, and you have a GIS() connection to a portal, the widget will automatically attempt to use that portal’s JS API that it ships with.

set_time_extent(start_time, end_time, interval=1, unit='milliseconds')¶

When time_slider = True, the time extent to display on the time slider.

Argument	Description
start_time	Required datetime.datetime. The lower bound of the time extent to display on the time slider.
end_time	Required datetime.datetime. The upper bound of the time extent to display on the time slider.
interval	Optional number, default 1. The numerical value of the time extent.
unit	Optional string, default “milliseconds”. Temporal units. Possible values: “milliseconds”, “seconds”, “minutes”, “hours”, “days”, “weeks”, “months”, “years”, “decades”, “centuries”

property snap_to_zoom¶: When True, snap to the next level of detail when zooming in or out. When False, the zoom is continous. Only applies in 2D mode

property start_time¶: datetime.datetime property. If time_mode == “time-window”, represents the lower bound ‘thumb’ of the time slider. For all other time_mode values, represents the single thumb on the time slider.

sync_navigation(mapview)¶

Synchronizes the navigation from this MapView to another MapView instance so panning/zooming/navigating in one will update the other.

Argument	Description
mapview	Either a single MapView instance, or a list of MapView instances to synchronize to.

# USAGE EXAMPLE: link the navigation of two maps together
from ipywidgets import HBox
map1 = gis.map("Chicago, IL")
map1.basemap = "gray"
map2 = gis.map("Chicago, IL")
map2.basemap = "dark-gray"
map1.sync_navigation(map2)
HBox([map1, map2])

tab_mode¶

This string property specifies the 'default' behavior of toggling a new window in a JupyterLab environment, whether that is called by pressing the icon in the widget UI, or by calling toggle_window_view() function without arguments.

Note that after a widget is ‘seperated’ from the notebook, you can drag it, split it, put it in a new tab, etc. See the JupyterLab guide pages for more information.

Value	Description
‘auto’	The default tab_mode: will move the widget to a split-right view if there are no other open windows besides the current notebook, otherwise will place the widget in a new tab.
‘split-top’	Will move the widget above the current notebook instance.
‘split-bottom’	Will move the widget below the current notebook instance.
‘split-left’	Will move the widget to the left of the current notebook instance.
‘split-right’	Will move the widget to the right of the current notebook instance.
‘tab-before’	Will move the widget to a new tab ‘before’ the tab that represents the current notebook instance.
‘tab-after’	Will move the widget to a new tab ‘after’ the tab that represents the current notebook instance.

take_screenshot(output_in_cell=True, set_as_preview=True, file_path='')¶

Takes a screenshot of the current widget view. Only works in a Jupyter Notebook environment.

Argument	Description
output_in_cell	Optional bool, default True. Will display the screenshot in the output area of the cell where this function is called.
set_as_preview	Optional bool, default True. Will set the screenshot as the static image preview in the cell where the map widget is being displayed. Use this flag if you want the generated HTML previews of your notebook to have a map image visible.
file_path	Optional String, default “”. To output the screenshot to a .png file on disk, set this String to a writeable location file path (Ex. file_path = “/path/to/documents/my_screenshot.png”).

In all notebook outputs, each image will be encoded to a base64 data URI and wrapped in an HTML <img> tag, like <img src=”base64Str”>. This means that the data for the image lives inside the notebook file itself, allowing for easy sharing of notebooks and generated HTML previews of notebooks.

Note

This function acts asyncronously, meaning that the Python function will return right away, with the notebook outputs/files being written after an indeterminate amount of time. Avoid calling this function multiple times in a row if the asyncronous portion of the function hasn’t finished yet.

Note

When this function is called with set_as_preview = True, the static image preview will overwrite the embedded HTML element preview from any previous MapView.embed_html(set_as_preview=True) call

property tilt¶: For 3D mode, the tilt of the camera in degrees with respect to the surface as projected down from the camera position. Tilt is zero when looking straight down at the surface and 90 degrees when the camera is looking parallel to the surface. Note that you can NOT set tilt in 2D mode.

time_mode¶

String used for defining if the temporal data will be displayed cumulatively up to a point in time, a single instant in time, or within a time range.

Possible values: “instant”, “time-window”, “cumulative-from-start”, “cumulative-from-end”. Default: “time-window”

See https://bit.ly/3dFSPa2 for more info.

time_slider¶: If set to True, will display a time slider in the widget that will allow you to visualize temporal data for an applicable layer added to the map. Default: False.

toggle_window_view(title='ArcGIS Map', tab_mode=None)¶

In a JupyterLab environment, calling this function will separate the drawn map widget to a new window next to the open notebook, allowing you to move the widget it, split it, put it in a new tab, etc. If the widget is already seperated in a new window, calling this function will restore the widget to the notebook where it originated from. See the JupyterLab guide pages for more information.

Note that this functionality can also be achieved by pressing the icon in the widget UI.

Argument	Description
title	What text will display as the widget tab. Default: “ArcGIS Map”.
tab_mode	The ‘tab mode’ that this window will open in. Will use this MapView instance’s tab_mode property if not specified. Possible values: “auto”, “split-top”, “split-left”, “split-right”, “split-bottom”, “tab-before”, “tab-after”

unsync_navigation(mapview=None)¶

Unsynchronizes connections made to other MapView instances made via my_mapview.sync_navigation(other_mapview).

Argument	Description
mapview	(Optional) Either a single MapView instance, or a list of MapView instances to unsynchronize. If not specified, will unsynchronize all synced MapView instances

update(mode=None, item_properties=None, thumbnail=None, metadata=None)¶

Updates the WebMap/Web Scene item that was used to create the MapWidget object. In addition, you can update other item properties, thumbnail and metadata.

Note

If you started out a MapView object from an existing webmap/webscene item, use this method to update the webmap/webscene item in your with your changes. If you started out with a fresh MapView object (without a webmap/webscene item), calling this method will raise a RuntimeError exception. If you want to save the map widget into a new item, call the save() method instead. For item_properties, pass in arguments for only the properties you want to be updated. All other properties will be untouched. For example, if you want to update only the item’s description, then only provide the description argument in item_properties.

Note

Saving as a WebScene item only works in a Jupyter environment: the map must be visually displayed in the notebook before calling this method.

Argument	Description
item_properties	Optional dictionary. See table below for the keys and values.
mode	Optional string. Whether to save this map instance as a 2D WebMap, or a 3D WebScene. Possible strings: “2D”, “webmap”, “3D”, or “webscene”.
thumbnail	Optional string. Either a path or URL to a thumbnail image.
metadata	Optional string. Either a path or URL to the metadata.

Key:Value Dictionary Options for Argument item_properties

Key	Value
typeKeywords	Optional string. Provide a lists all sub-types, see URL 1 below for valid values.
description	Optional string. Description of the item.
title	Optional string. Name label of the item.
tags	Optional string. Tags listed as comma-separated values, or a list of strings. Used for searches on items.
snippet	Optional string. Provide a short summary (limit to max 250 characters) of the what the item is.
accessInformation	Optional string. Information on the source of the content.
licenseInfo	Optional string. Any license information or restrictions regarding the content.
culture	Optional string. Locale, country and language information.
access	Optional string. Valid values are private, shared, org, or public.
commentsEnabled	Optional boolean. Default is true, controls whether comments are allowed (true) or not allowed (false).

URL 1: http://resources.arcgis.com/en/help/arcgis-rest-api/index.html# //02r3000000ms000000 :return:

A boolean indicating success (True) or failure (False).

USAGE EXAMPLE: Interactively add a new layer and change the basemap of an existing web map.
italy_streets_item = gis.content.search("Italy streets", "Web Map")[0]
map1 = MapView(item = italy_streets_item)
map1.add_layer(Italy_streets2)
map1.basemap = 'dark-gray-vector'
map1.update(thumbnail = './new_webmap.png')

property zoom¶: What level of zoom you want to apply: the higher the number, the more zoomed in you are.

zoom_to_layer(item, options={})¶

Snaps the map to the extent of provided item or items.

Argument	Description
item	The item at which you want to zoom your map to. This can be a single or a list of Items, layers, DataFrame, FeatureSet, FeatureCollection.
options	Optional set of arguments.