Use URL parameters

In ArcGIS Instant Apps, you can add URL parameters to your app’s URL when sharing and configure a custom parameter. You can use URL parameters to include instructions upon opening the app’s link. For example, you can zoom an app to a specific location or scale level, zoom to a feature with a pop-up, and more.

Parameters structure

Parameters are added to the end of the URL and are formatted as a key-value pair connected with an equal sign (=). To append parameters, you must use ampersands (&) to connect them to your URL.

Instant Apps URLs with parameters use the following structure:

https://<domain>/apps/instant/<Template>/index.html?<AppID>&<param1=value>&<param2=value>&<param3=value>&...

Note:

The lesser-than and greater-than symbols (<>) are used throughout this topic as brackets. Do not add the symbols to your URL.

<Template> is the Instant Apps template of your app.

<AppID> is the unique ID of the web app. Instant Apps templates (like the Basic template used below) take the ID of the application to open as a URL parameter:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146

To append multiple parameters, separate them with ampersands (&):

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&locale=en&center=-157.7118,20.7413&level=7

In this example, the locale, center, and level parameters were all appended.

General parameters

The subsections below describe parameters that may be available in your app.

Note:

Not every Instant Apps template supports the following parameters. Make sure to test your app to ensure that the parameter is supported.

Specify a location

Define a location that your app will center on upon opening the URL. Set center with geographic coordinates (x,y) with center=<x>,<y>.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&center=-157.7118,20.7413

The app opens to the coordinates (-157.7118, 20.7413).

Specify a scale level

Define a specific scale level with the level parameter. Append level=<zoom level value>.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&level=2

The app opens to a lower level of zoom than the app's default.

Specify an extent

Use two geographic coordinates (x,y) to define the extent of the map. Use extent=<MinX>,<MinY>,<MaxX>,<MaxY>. The first coordinates (MinX,MinY) must define the southwest corner of the desired map extent. The second coordinates (MaxX,MaxY) must define the northeast corner of the desired map extent.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&extent=-73.28,42.08,-68.46,42.04

The app opens to the desired map extent.

Find the location of a feature

Find a location or feature upon opening the app using the find parameter. The map zooms to the closest match and a callout marker appears. Use find=<search string>.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&find=michigan

The app zooms to the U.S. state Michigan as the best search result returned.

Add a marker with a pop-up

Upon opening the URL, zoom on a marker with a custom pop-up with the marker parameter. The parameter uses the following properties. To skip a property, use double commas (,,).

Note:

The entire parameter must be encoded. URL encoding replaces characters with the percent sign (%) followed by their hexadecimal (hex) equivalent. For more information, and to encode your strings, see URLEncoder.io.

The marker properties must be structured in the following order:

marker=<x>,<y>,<WKID>,<title>,<symbol URL>,<label>

• <x>,<y>—The geographic coordinates for the marker.
• <WKID>—Spatial reference of the coordinates to be added to the map. If you do not include a WKID, GCS coordinates are used.
• <title>—Pop-up title. If you do not include a title, the pop-up will be empty.
• <symbol URL>—Symbol for the point. If you do not include a symbol, a black circle marker symbol is used.
• <label>—Text to include in the pop-up description.

The parameter will zoom to the marker. Click the marker to open the pop-up.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&marker=-166.50,24.77,,Papah%C4%81naumoku%C4%81kea%20Marine%20National%20Monument,,One%20of%20the%20world%27s%20largest%20protected%20areas.%20This%20monument%20is%20home%20to%20native%20cultural%20significance%20and%20protects%20critical%20endemic%20species.

The URL will create a marker and pop-up at the designated coordinates. The pop-up is titled Papahānaumokuākea Marine National Monument with text.

Switch the app language

Configure your URL to open the app to a specific language. Use the locale parameter and a two-letter ISO 639-1 language code. Instant Apps supports all the same languages that ArcGIS Online supports. Append locale=<language code>.

The following is an example:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&locale=vi

The app’s user interface is now set to the language Vietnamese upon opening.

Generate parameters with Share

You can create a URL to your app with generated parameters using the Share functionality. The URL you generate can preserve the current map view and open pop-ups.

Note:

Some templates do not support the Share tool. Refer to the app tools matrix (PDF) to see which templates support Share.

The following parameters can be automatically generated with the Share function:

• locale=<language code>
• center=<x>,<y>
• level=<LOD>
• selectedFeature=<feature>

The selectedFeature parameter opens the pop-up of a feature.

To use the Share function to create a URL with generated parameters, complete the following steps:

1. In the side panel, disable Express mode, and when the confirmation prompt appears, click Continue.
2. In the side panel, click Interactivity to open the pane.
3. Click Share to open the Share menu.
4. Enable the Sharing option. This enables the Share tool in your app.
5. In the web map, configure the map’s view that you want the URL to open to.

   Additionally, you can select a feature if you want the URL to open to a selected feature and its pop-up.

6. Click the Share tool.
7. Click Copy Link to copy your app’s URL to your clipboard.

   This URL will include appended parameters that will open your app to the view and the selected feature’s pop-up (if configured). Additionally, this URL is always encoded.

Create a custom URL parameter

You can create a custom URL parameter in your Instant Apps app that zooms to a feature and displays the pop-up when the app opens. Custom URL parameters can be combined with other URL parameters, and are supported in 3D Viewer, Basic, Interactive Legend, Reporter, and Sidebar. Basic and Sidebar also support custom URL parameters that apply to multiple layers.

To create a custom URL parameter, complete the following steps:

1. In the side panel, disable Express mode, and when the confirmation prompt appears, click Continue.
2. Click Search settings and search for URL parameter name.

   The URL parameter settings appear.

3. In the URL parameter name section, enter the name of your custom parameter.

   This will be the custom parameter to append to your app’s URL.

4. In the URL parameter search layer, select the feature layer from the app you want your custom parameter to search.
5. Next to the feature layer you selected, click Field to open the fields drop-down menu.

   Select the field within your search layer you want your custom parameter to search.

6. Click Done.
7. Click Publish to deploy your custom parameter configurations.

Your custom URL parameter has been configured. You can append the custom parameter with your feature’s identifying value to the app’s URL using the structure of <assigned name>=<field value>. This will zoom and display the pop-up of a designated feature when the app opens.

For example, if the custom parameter was named “site” and it should search site names, append site=<site name> to the end of the URL of your web app to have the app zoom to that specified feature. In this example app of NOAA marine protected areas, the following parameter will zoom to the Monterey Bay National Marine Sanctuary site and open the feature’s pop-up: site=Monterey Bay National Marine Sanctuary.

The following URL demonstrates this:

https://example.maps.arcgis.com/apps/instant/basic/index.html?appid=6c133f9d56d64723aee1da68e704c146&site=Monterey%20Bay%20National%20Marine%20Sanctuary