Use URL parameters

Apps created with Web AppBuilder can be modified directly with URL parameters. The URL always begins with <your portal url>/apps/webappviewer/index.html? and includes one or more of the parameters listed below. To include more than one parameter, use an ampersand (&) to separate the parameters. The following is an example:

http://<your portal url>/apps/webappviewer/index.html?id=6815e148ff1c4aee8dc7159816380a4d&webmap=9cf053ea602345ddae060010c470e615

Tip:

Now there is an easier way to construct URL parameters. Add the Share widget in the app and click Link Options. Link preview displays the parameters you selected, and a shortcut link including the URL parameters is automatically generated for you. Be aware that the Search widget must be enabled in the app to use the find parameter.

Note:

Currently, 3D apps do not support URL parameters.

Encode the query parameters

All query parameters must be encoded. Encoding replaces invalid characters with % followed by their hex equivalent.

For example, the following is an unencoded URL parameter:

http://<your portal url>/apps/webappviewer/index.html?find=380 new york street, redlands, ca

Here is the same parameter encoded:

http://<your portal url>/apps/webappviewer/index.html?find=380%20new%20york%20street,%20redlands,%20ca

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.

Open a saved app

To open a saved app created with Web AppBuilder, use id= and the unique ID of the app, as shown in the following example:

http://<your portal url>/apps/webappviewer/index.html?id=6815e148ff1c4aee8dc7159816380a4d

Define the web map

To define the web map, use webmap= and the unique ID of the web map, as shown in the following example:

http://<your portal url>/apps/webappviewer/index.html?webmap=9cf053ea602345ddae060010c470e615

Center the map

To center the map at a particular location, set center= using geographic coordinates (x,y) or projected coordinates (x,y,WKID).

Caution:

You can use commas or semicolons as separators. Use semicolons if your numbers use colons as their decimals.

The following is a geographic coordinates example:

http://<your portal url>/apps/webappviewer/index.html?center=34,-50

The following is a projected coordinates example:

http://<your portal url>/apps/webappviewer/index.html?center=500000,5500000,102100

Define the scale level

To define the scale level of the map, use the center= and level= parameters. The level parameter accepts the level ID of the cache scale as listed in the REST endpoint of the map service. The following is an example:

http://<your portal url>/apps/webappviewer/index.html?center=20,45&level=4

Define the scale

To define the scale of the map, use the center= and scale= parameters. The scale parameter accepts the cache scale as listed in the REST endpoint of the map service. The following is an example:

http://<your portal url>/apps/webappviewer/index.html?center=20,45&scale=4622324

Define the extent

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

The following is a geographic coordinates example:

http://<your portal url>/apps/webappviewer/index.html?extent=-117.20,34.055,-117.19,34.06

The following is a projected coordinates example:

http://<your portal url>/apps/webappviewer/index.html?extent=-13079253.954115,3959110.38566837,-12918205.318785,4086639.70193162,102113

The following is a Well-Known Text String example:

http://<your portal url>/apps/webappviewer/index.html?extent=1008562.1255,1847133.031,1060087.7901,1877230.7859,wkt=PROJCS["NAD_1983_HARN_StatePlane_Illinois_East_FIPS_1201",GEOGCS["GCS_North_American_1983_HARN",DATUM["D_North_American_1983_HARN",SPHEROID["GRS_1980",6378137.0,298.257222101]]

Set layers' visibility

To set the layers' visibility for the map, you can use showLayers= to specify visible layers, or use hideLayers= to turn layers off. The showLayers= and hideLayers= parameters accept a single layer ID or multiple layer IDs. For multiple layers, use a semicolon to separate the list of IDs (&showLayers=<layerID>;<layerID>;<layerID>).

The following is an example: http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&showLayers=Census_8491;Census_8492;Census_8493.

Layer names are also acceptable. However, using the layer ID is more reliable because the layer name can be changed. You can retrieve the layer ID from the content of the web map item: http://<your portal url>/sharing/rest/content/items/<webmapItemID>/data/?f=pjson.

When you use the showLayers= or hideLayers= parameters to set the visibility for a sublayer, it only affects the visibility of layers at the same level. For example, if your map contains two group layers (A and B) with three sublayers each (A1, A2, A3 and B1, B2, B3), and you use the showLayers= parameter to show sublayer B2, both group layers A and B will still be turned on in the map, but the sublayers B1 and B3 will be turned off.

Tip:

When the value for the showLayers= or hideLayers= parameter is empty, no layers or all layers will be visible, respectively.

Caution:

If you list a lot of layers or the names are lengthy when you set the showLayers= or hideLayers= parameter, the URL may be too long for the server to interpret. (Different servers can have unique length limitations for URLs.)

Find a location or feature to open the 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). The following is an example:

http://<your portal url>/apps/webappviewer/index.html?find=380 new york street, redlands, ca

Caution:

All query parameters must be encoded, and the Search widget must be enabled in the app to use this parameter.

Add a point

To add a point to the map, use marker=<x>,<y>. The point is added to the map at the specified x and y locations. 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.

The following should be considered:

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

The following is an example:

http://<your portal url>/apps/webappviewer/index.html?marker=-79.234826;38.147884;;Race start and finish;;Grindstone 100 Ultra Marathon&level=7

Query a feature

To query a feature and zoom to it, you can use one of the following options:

• query=<layer name>,<field name>,<field value>
• query=<layer name>, <where clause>
• query=<layer id>,<field name>,<field value>
• query=<layer id>, <where clause>

Tip:

Now there is a way to construct URL parameters interactively. Add the Share widget in the app and click Link Options. Choose the Query a feature and zoom to it option and select the layer, field, and field value you want to query against. Copy the URL in Link preview that contains the URL parameters you specified. Remove the Share widget from the app if it is not needed.

Caution:

All the query parameters are case sensitive and must be encoded.

The WHERE clause follows SQL standard. When the WHERE clause has, for example, the IN operation, use the semicolon instead of separating layer name or ID from the WHERE clause with commas, as shown below. The reason is because a comma is used in the WHERE clause specifically to build the list of values such as ('A11', 'A12', 'A13) or ('Charlotte', 'Chicago'). This allows the query parameter to be parsed properly to distinguish what the layer and WHERE clause are.

• query=<layer name>; <where clause>
• query=<layer id>; <where clause>

Since the layer name can be changed, it is strongly recommended that you use the layer ID in the query. You can retrieve the layer ID from the web map ID, as shown here: http://<your portal url>/sharing/rest/content/items/32a83775654249dcae6b8f2eff5d4072/data/?f=pjson

Caution:

Make sure the web map is shared publicly when you retrieve the layer ID.

For example, a layer is added to the map individually as shown below in JSON format. The layer ID is Census_8491, the field name is POP2000, and the field value is 1211537. You can perform the following queries:

id: "Census_8491",
layerType: "ArcGISFeatureLayer",
url: "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3",
visibility: true,
opacity: 1,
mode: 1,
title: "Census - states",

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491,POP2000,1211537

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491,POP2000=1211537

You can also query a string or the ObjectID fields.

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491,STATE_NAME,California

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491,STATE_NAME='California'

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491,OBJECTID,1

Often a layer is added as a group of a map service. To query a sublayer in a group, use <layer id_sublayer id> as the layer ID instead. Using the following layer as an example, the layer ID is Census_3217 and the sublayer ID index is 3. The layer ID for the sublayer should be Census_3217_3. You can perform the following queries:

id: "Census_3217",
layerType: "ArcGISMapServiceLayer",
url: "http://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer",
visibility: true,
opacity: 1,
title: "Census"

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_3217_3,POP2000,1211537

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_3217_3,POP2000=1211537

http://<your portal url>/apps/webappviewer/index.html?id=da80a448ac9246148da0811bddc18c94&query=Census_8491;STATE_NAME in ('California', '')

Switch locale

To switch the app language, use the locale URL parameter and a two-letter ISO 639-1 language code. The following language codes are supported: ar, bs, ca, cs, da, de, el, en, es, et, fi, fr, he, hr, hu, id, it, ja, ko, lt, lv, nb, nl, pl, pt-br, pt-pt, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-cn, zh-hk, and zh-tw.

To use Web AppBuilder in French, for example, append locale=fr to the URL like this:

http://<your portal url>/apps/webappviewer/index.html?locale=fr

Control when to turn on mobile layout

The app supports two styles of layout based on the screen size. One is for desktop and one is for mobile devices. When either the height or width of a screen display is less than 600 pixels, the mobile layout applies automatically. However, this can result in unexpected behavior when the app is embedded in a website, for example, when the pop-up in the website is in the mobile layout style. To control the layout style, use mobileBreakPoint=<pixel number>. For example, you can remain in desktop style until the screen size is less than 300 pixels, as shown below:

http://<your portal url>/apps/webappviewer/index.html?mobileBreakPoint=300