ArcGIS Online

Use URL parameters in Map Viewer

URL parameters can be used to pass along additional information or instructions to Map Viewer, controlling the maps that are opened, their zoom level, layer visibility, and more.

URL parameters follow a question mark (?) and are made of a key-value pair connected with an equal sign (=). For example, Map Viewer takes the ID of the web map to open as a URL parameter.

URL parameter syntax

To include multiple parameters, separate them with ampersands (&).

Map Viewer URL parameters


URL encoding

URL encoding replaces characters with the percent sign (%) followed by their hex (hexadecimal) equivalent. In modern browsers, URL encoding is automatically added as needed when entering a URL in the browser address bar. When using embedded maps, encoding may be necessary.

For example, the following is an example that uses find to locate Redlands California. The space in the location is automatically replaced by %20 in the browser address bar:
webmap=8152694dd9594393a1db4d62d2020fe3&find=redlands california

The full URL encoding is as follows:

For more information, and to encode your URL strings, see



The following examples show using URL parameters to open and modify maps.

Open an existing map as configured

The map is referenced by its ID, in this case 8152694dd9594393a1db4d62d2020fe3.

Open an existing map and specify a scale level

Scale is specified using &level=<LOD>

Specify a location and scale level

The map is centered using &center=<x>,<y>.,39.954757&level=14

Specify an extent

&Extent uses two x,y coordinates to define the bounding box.,34.055,-117.19,34.06

Find the location of a feature to open the map

Use &find= followed by any search string. Falls

Find location via URL parameters

Find an address to open the map new york street, redlands, ca

Add a marker with a pop-up

&Marker uses the following properties. To skip a property use double semicolons (;;). The marker properties must be in this order:  &marker=<x>,<y>,<WKID>,<title>,<symbol URL>,<text>. Click the marker to view the pop-up.;36.578494;;Mount Whitney;;Mount Whitney is the highest mountain in the contiguous United States with an elevation of 14,505 feet (4,421 m).

Add a marker with a pop-up and specify a zoom level

Add &level to the URL above. Click the marker to view the pop-up.;36.578494;;Mount Whitney;;Mount Whitney is the highest mountain in the contiguous United States with an elevation of 14,505 feet (4,421 m).&level=14

URL parameters to create pop-up

Open a map and add layers

This example opens a map and adds Recent Earthquakes and VIIRS Thermal Hotspots from ArcGIS Living Atlas. Use the &layers parameter to add the layers using their IDs, separated by a comma.

Layers added via URL parameters

Open Map Viewer and define the basemap

Set basemapUrl to the basemap layer you want to use. Note the capitalization of U in the parameter. This examples opens with the OpenStreetMap (OSM) vector basemap layer. Add the &level parameter to zoom in.

Open Map Viewer, define the basemap, and add a layer

This example opens the OSM vector basemap layer and adds Recent Earthquakes (from ArcGIS Living Atlas) using the item ID with the &layers parameter.

Open Map Viewer, add a basemap and reference layer

Use basemapReferenceUrl to set the reference layer to be used. This must be used along with basemapUrl. The example below adds the World Boundaries and Places reference layer to the Vintage Shaded Relief basemap layer, both from ArcGIS Living Atlas.

Basemap and reference via URL parameters

Set sublayer visibility

To set the visibility of sublayers for a layer that opened in the map, use layers=show. In this example using Bureau of Labor Statistics Unemployment from the Living Atlas, only the 3rd sublayer is visible. Note that sublayer numbering begins with zero (0) as shown in the REST endpoint.

Layers in REST endpoint

Sublayer visibility using URL parameters

Add two layers and set sublayer visibility

This example adds two layers and sets the visibility of sublayers for the second layer. The layers are separated by commas, note that the additional URL parameters for sublayer visibility apply to the second layer, plus the addition of an overall extent parameter which controls the map.,


More information

For more information, see:


About the author

Corporate technology evangelist and advocate at Esri, focusing on ways to broaden access to geographic information and helping customers succeed with the ArcGIS system. On a good day I'm making a map, on a great day I'm on one. Email or connect on LinkedIn (


Next Article

Simple steps to add SAR satellite data to your ArcGIS Pro map

Read this article