Use URL parameters to create and modify maps

A map authored with Map Viewer or Map Viewer Classic contains a basemap; data layers; an extent; a legend; and navigation tools such as zoom, pan, place finders, and bookmarks. Many maps also contain interactive elements such as a basemap gallery, measure tools, pop-ups, and buttons for playing data over time.

In addition to creating maps with Map Viewer or Map Viewer Classic, you can create and modify maps directly with URL parameters.

For example, you can construct a map with URL parameters that shows biomes and ecoregions.

https://www.arcgis.com/apps/mapviewer/index.html?basemapUrl=https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer&url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/Resolve_Ecoregions/FeatureServer

View this example in Map Viewer

For example, you can use a Map Viewer URL in the following circumstances:

• If you don't need to include a lot of reference or operational layers and you don't need to apply specific styles to the map's content, use a URL to open Map Viewer. For example, if your website allows users to look up an address or view a single layer related to your site, you can include a link in the website that opens Map Viewer with the specified basemap and the single layer required.
• You need to link to a saved web map from a website or email. You can use a URL that opens the specific web map.

What to include in the URL

The URL always begins with https://www.arcgis.com/apps/mapviewer/index.html? in Map Viewer and https://www.arcgis.com/home/webmap/viewer.html? in Map Viewer Classic and includes one or more of the query parameters listed below. To include more than one parameter, use an ampersand (&) to separate the parameters. You'll find examples of using multiple parameters throughout this page.

See the following example:

https://www.arcgis.com/apps/mapviewer/index.html?center=20,45&level=8

View this example in Map Viewer

Note:

If any of the resources in the URL parameter are provided as HTTP, you must replace HTTP with HTTPS in the URL and make all resources accessible using HTTPS only.

Encode the query parameters

All query parameters must be encoded. URL encoding ensures that valid characters are sent to ArcGIS Online. Encoding replaces invalid characters with % followed by their hex equivalent.

For example, here is an unencoded URL parameter:

basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/Ocean/World_Ocean_Base/MapServer

Here is the same parameter encoded:

basemapUrl=https%3A%2F%2Fservices.arcgisonline.com%2FArcGIS%2Frest%2Fservices%2FOcean%2FWorld_Ocean_Base%2FMapServer

Parameters within parameters must also be encoded, for example:

urls=https%3A%2F%2Fmaps.ngdc.noaa.gov%2Frest%2Fservices%2Fweb_mercator%2Ftrackline_gravity%2FMapServer%2Chttps%3A%2F%2Fmaps.ngdc.noaa.gov%2Frest%2Fservices%2Fweb_mercator%2Fhazards%2FMapServer%3Flayers%3Dshow%3A5%2C6

The internet has many free sites and tools for generating encoded URLs—for example, https://www.urlencoder.io/. For readability, the rest of the examples in this topic are not encoded. Click the View this example in Map Viewer link after the example to see the encoded URL in a web browser.

Open a saved map

To open a saved map created with Map Viewer or Map Viewer Classic, use webmap= and the unique ID of the map.

In this example, a web map with an ID of 75a3ce8990674a5ebd5b9ab66bdab893 will open in Map Viewer:

https://www.arcgis.com/apps/mapviewer/index.html?webmap=75a3ce8990674a5ebd5b9ab66bdab893

View this example in Map Viewer

In this example, a web map with an ID of 29990ur6423j1180p53f9t30019491 will open in Map Viewer with the extent set to -117.996342,33.841078,-117.993692,33.844375:

https://www.arcgis.com/apps/mapviewer/index.html?webmap=29990ur6423j1180p53f9t30019491&extent=-117.996342,33.841078,-117.993692,33.844375

Define the basemap

To define the basemap, set basemapUrl= to the layer. If a basemap is not defined, the default basemap, World Topographic basemap, is used.

In this example, Map Viewer opens with OpenStreetMap used as the basemap:

https://www.arcgis.com/apps/mapviewer/index.html?basemapUrl=https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer&layers=9e2f2b544c954fda9cd13b7f3e6eebce

View this example in Map Viewer

In this example, Map Viewer opens with the World physical map used as the basemap and an operational layer with item ID 9e2f2b544c954fda9cd13b7f3e6eebce present in the map:

https://www.arcgis.com/apps/mapviewer/index.html?basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/World_Physical_Map/MapServer&layers=9e2f2b544c954fda9cd13b7f3e6eebce

Include a reference layer

To include a reference layer with the basemap, set basemapReferenceUrl= to the layer. The basemapReferenceUrl= parameter must be used in addition to the basemapUrl parameter.

In this example, Map Viewer opens with the World Imagery basemap layer and the reference layer set to the World Boundaries and Places layer:

https://www.arcgis.com/apps/mapviewer/index.html?basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer&basemapReferenceUrl=https://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer

In this example, Map Viewer opens with the world imagery map image layer present and the basemap set to the World boundary and places layer:

https://myportal.domain.com/apps/mapviewer/index.html?basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer&basemapReferenceUrl=https://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer

View this example in Map Viewer

Define the operational layers

To define the operational layers that overlay the basemap, use webmap=, layers=, layerIds=, url=, or urls=. If the layer is an item in the website, use layers= so you get all the layer configurations. To add individual sublayers from a feature layer that contains multiple sublayers, use layerIds=. If the layer isn't in the website, use url= or urls=.

The layers= parameter accepts a single item ID or multiple item IDs. For multiple layers, use a comma-separated list of IDs (&layers=<itemID>,<itemID>,<itemID>).

See the following example:

https://www.arcgis.com/apps/mapviewer/index.html?webmap=8152694dd9594393a1db4d62d2020fe3&layers=9e2f2b544c954fda9cd13b7f3e6eebce,dece90af1a0242dcbf0ca36d30276aa3

View this example in Map Viewer

The layerIds= parameter accepts a single layer ID or multiple layer IDs. If a feature layer contains multiple sublayers, use the layerIds= parameter to add individual sublayers. For multiple sublayers, use a comma-separated list of IDs (&layerIds=0,1,2).

See the following example:

https://www.arcgis.com/apps/mapviewer/index.html?layers=025063719c32408dbd4fb608faa28d2a&layerIds=0,2

View this example in Map Viewer

The url= parameter accepts a single layer URL.

See the following example:

https://www.arcgis.com/apps/mapviewer/index.html?url=https://services9.arcgis.com/RHVPKKiFTONKtxq3/arcgis/rest/services/USGS_Seismic_Data_v1/FeatureServer

View this example in Map Viewer

Use urls= to include more than one layer. Separate layers with a comma. The map extent is based on the last layer in the list or the slowest one to load. To zoom to a specific extent, include the extent= parameter.

See the following example:

https://www.arcgis.com/apps/mapviewer/index.html?urls=https://services9.arcgis.com/RHVPKKiFTONKtxq3/arcgis/rest/services/NOAA_METAR_current_wind_speed_direction_v1/FeatureServer,https://services9.arcgis.com/RHVPKKiFTONKtxq3/arcgis/rest/services/NOAA_storm_reports_v1/FeatureServer?layers=show:4&extent=-108,40,-85,31

View this example in Map Viewer

Define the scale level and center the map

Scale is automatically set for a map in Map Viewer Classic when you use the webmap or find parameter. If you use the webmap parameter, the map is automatically zoomed to the full extent of the map, unless other URL parameters such as level and center or extent are used to override the web map scale. If you use the find parameter, the map is automatically zoomed to the best extent of the found location.

To define a specific scale level, use the center and level parameters. The level parameter accepts the level ID of the cache scale as listed in the REST service endpoint of the tiled basemap. The resolution is inversely related to the scale. The level parameter is only supported for tiled basemaps, not for basemaps created from dynamic map services and other nontiled data.

To center the map at a particular location, set center using geographic coordinates (x,y) or projected coordinates (x,y,WKID). You can use commas or semicolons as separators. Use semicolons if your numbers use commas as their decimals.

Note:

The level and center parameters must be used together. The level parameter is ignored if it's used on its own.

See the following geographic coordinates example:

https://www.arcgis.com/apps/mapviewer/index.html?center=20,45&level=4

View this example in Map Viewer

See the following projected coordinates example:

https://www.arcgis.com/apps/mapviewer/index.html?center=500000,5500000,102100&level=4

View this example in Map Viewer

Define the extent

To define the extent of the map, use extent. The extent parameter accepts geographic coordinates (GCS) as MinX,MinY,MaxX,MaxY or projected coordinates (PCS) as MinX,MinY,MaxX,MaxY,WKID. You can use commas or semicolons as separators. Use semicolons if your numbers use commas as their decimals.

See the following geographic coordinates example:

https://www.arcgis.com/apps/mapviewer/index.html?extent=-117.20,34.055,-117.19,34.06

View this example in Map Viewer

See the following projected coordinates example:

https://www.arcgis.com/apps/mapviewer/index.html?extent=-13079253.954115,3959110.38566837,-12918205.318785,4086639.70193162,102113

View this example in Map Viewer

Set the layer visibility

To set the visibility of sublayers for a layer that you open in the map, use layers=show:.

In this example, sublayer 3 is visible but other sublayers are not visible:

Note:

Sublayer numbering begins with zero (0) as shown in the REST endpoint.

https://www.arcgis.com/apps/mapviewer/index.html?url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/BLS_Monthly_Unemployment_Current_14_Months/FeatureServer?layers=show:2&find=Pennsylvania

View this example in Map Viewer

Find a location or feature to open the map

To find a location or feature immediately upon opening the map, use find. The map is automatically zoomed to the closest match and a callout marker is added to the map. The find parameter accepts single-line addresses, partial addresses (such as city only or country only), place-names, longitude-latitude coordinates, and features in searchable layers (such as 1916352001 for a Parcel Identification Number (PIN)).

The following example uses a single-line address:

https://www.arcgis.com/apps/mapviewer/index.html?find=380 new york st,redlands,ca

View this example in Map Viewer

Tip:

To find a location or feature in a searchable layer, include the webmap= parameter with the unique ID of the map.

Add a point

To add a point to the map, use marker=<x>,<y>. You can also include the following optional properties:

• <wkid>—Spatial reference of the x,y coordinates to be added to the map. If you do not include a WKID, GCS coordinates are used.
• <encoded title>—Title of the point pop-up. If you do not include a title, the pop-up will be empty.
• <encoded icon URL>—Symbol for the point. If you do not include a symbol, a blue marker symbol is used.
• <encoded label>—Label next to the point symbol.

Example

The following example uses semicolon separators:

https://www.arcgis.com/apps/mapviewer/index.html?marker=-79.234826;38.147884;;Race start and finish;;Grindstone 100 Ultra Marathon

View this example in Map Viewer

Considerations

Keep the following in mind when adding a point to a map:

• In Map Viewer Classic, the point is added to a new map notes layer at the specified x,y coordinate location.
• The <x>,<y> coordinates are required to add a point.
• You must encode the title, icon, and label parameters.
• You must add properties in this order: marker=<x>,<y>,<wkid>,<encoded title>,<encoded icon URL>,<encoded label>.
• You can use commas or semicolons as separators. Use semicolons if your numbers use commas as their decimals.
• Use empty values. Do not use spaces. For example, to specify a label and no other optional properties, add the label as the sixth parameter with empty values for the others (x;y;;;;label).
• If you want the map to zoom in (in addition to centering on the point), include the level parameter.
• You can edit and save the map notes layer as a map or item.
• Organizational accounts can use the point to get directions and perform analysis.

Hide the Details pane

Note:

This functionality is currently only supported in Map Viewer Classic. It will be available in a future release of Map Viewer.

To hide the Details pane in Map Viewer Classic, use mapOnly=true.

In this example, a saved web map with ID 8505192e747d440098523e9e64419710 is opened in Map Viewer Classic, but the Details pane is hidden:

https://www.arcgis.com/home/webmap/viewer.html?webmap=8505192e747d440098523e9e64419710&mapOnly=true

View this example in Map Viewer Classic