Skip To Content

Use URL parameters to modify maps

A map authored with Map Viewer 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.

As an alternative to creating maps with Map Viewer, you can create and modify maps directly with URL parameters.

For example, here's how you could construct a map with URL parameters that shows shoals off the coast of Maryland.

https://www.arcgis.com/home/webmap/viewer.html?basemapUrl=http%3A%2F%2Fservices.arcgisonline.com%2FArcGIS%2Frest%2Fservices%2FOcean_Basemap%2FMapServer&url=http%3A%2F%2Fservices.arcgis.com%2FWQ9KVmV6xGGMnCiQ%2Farcgis%2Frest%2Fservices%2FOnshore_Windfarms%2FFeatureServer&extent=-24.3161%2C45.2274%2C18.0911%2C63.5381

View this example in Map Viewer

What to include in the URL

The URL always begins with https://www.arcgis.com/home/webmap/viewer.html? and includes one or more of the query parameters listed below. To include more than one parameter, use an ampersand (&) to separate the parameters.

For example:

https://www.arcgis.com/home/webmap/viewer.html?center=20,45&level=4

View this example in Map Viewer

Note:

If any of the resources in the URL parameter are provided as HTTP, the URL for the map should be HTTP as well. For added security, you should use an HTTPS URL if possible.

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_Basemap/MapServer

Here is the same parameter encoded:

basemapUrl=http%3A%2F%2Fservices.arcgisonline.com%2FArcGIS%2Frest%2Fservices%2FOcean_Basemap%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%2Chttp%3A%2F%2Fmaps.ngdc.noaa.gov%2Frest%2Fservices%2Fweb_mercator%2Fhazards%2FMapServer%3Flayers%3Dshow%3A5%2C6

The web has many free sites and tools for generating encoded URLs. For example, Albion Research Ltd. has a URLEncode and URLDecode Page. For readability, the rest of the examples in this topic are not encoded. Click View this example in Map Viewer after the example to see the encoded URL in a web browser.

Open saved map

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

For example:

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

View this example in Map Viewer.

Define basemap

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

For example:

https://www.arcgis.com/home/webmap/viewer.html?basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/World_Physical_Map/MapServer

View this example in Map Viewer

Include 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.

For example:

https://www.arcgis.com/home/webmap/viewer.html?
basemapUrl=https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer
&basemapReferenceUrl=http://services.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer

View this example in Map Viewer

Define operational layers

To define the operational layers that overlay the basemap, use webmap=, layers=, url=, or urls=. If the layer is an item in the website, use layers= so you get all the layer configurations. 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>).

For example:

https://www.arcgis.com/home/webmap/viewer.html?layers=a79a3e4dc55343b08543b1b6133bfb90,a068913914cd4fecb302b9207a532d1a

View this example in Map Viewer

The url= parameter accepts a single layer URL.

For example:

https://www.arcgis.com/home/webmap/viewer.html?
     url=https://services.arcgisonline.com/ArcGIS/rest/services/Demographics/USA_Population_Density/MapServer

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.

For example:

https://www.arcgis.com/home/webmap/viewer.html?urls=https://maps.ngdc.noaa.gov/rest/services/web_mercator/trackline_gravity/MapServer,https://maps.ngdc.noaa.gov/rest/services/web_mercator/hazards/MapServer?layers=show:5,6,12&extent=5,45,10,50

View this example in Map Viewer

Center map

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 colons as their decimals.

Geographic coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?center=20,45

View this example in Map Viewer

Projected coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?center=500000,5500000,102100

View this example in Map Viewer

Define scale level

To define the scale level of Map Viewer, use the center and level= parameters. The level parameter accepts the level ID of the cache scale as listed in the REST service endpoint. The cache scale level can be determined using the information on the map service's REST endpoint. The resolution is inversely related to the scale.

Scale is automatically set when you use the webmap or find parameter; level is ignored. If you use the webmap parameter, the map is automatically zoomed to the full extent of the map. If you use the find parameter, the map is automatically zoomed to the best extent of the found location.

Geographic coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?center=20,45&level=4

View this example in Map Viewer

Projected coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?center=500000,5500000,102100&level=4

View this example in Map Viewer

Define extent

To define the extent of the map, use extent= to define the extent of the map. 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 colons as their decimals.

Geographic coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?extent=-117.20,34.055,-117.19,34.06

View this example in Map Viewer

Projected coordinates example:

https://www.arcgis.com/home/webmap/viewer.html?extent=-13079253.954115,3959110.38566837,-12918205.318785,4086639.70193162,102113

View this example in Map Viewer

Set layer visibility

To set the visibility of layers in the map, use layers=show:.

For example:

https://www.arcgis.com/home/webmap/viewer.html?url=https://sampleserver3.arcgisonline.com/ArcGIS/rest/services/BloomfieldHillsMichigan/Parcels/MapServer?layers=show:1,2

View this example in Map Viewer

Find location or feature to open map

To find a location or feature that is used to open 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)).

For example:

https://www.arcgis.com/home/webmap/viewer.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, you can include the webmap= parameter with the unique ID of the map.

Add point

To add a point to the map, use marker=<x>,<y>. The point is added to a new map notes layer at the specified x,y location. You can also include the following optional properties:

  • <wkid>—Spatial reference of the x,y coordinates 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.

Considerations

  • <x>,<y> are required.
  • Be sure to 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 colons as their decimals.
  • Use empty values. Do not use spaces. For example, if you want to specify a label and none of the 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.

Example

The following example uses semicolon separators:

https://www.arcgis.com/home/webmap/viewer.html?marker=-79.234826;38.147884;;Race start and finish;;Grindstone 100 Ultra Marathon&level=7

View this example in Map Viewer

Hide Details pane

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

For example:

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

View this example in Map Viewer