Web maps

A web map basically describes the contents that display on a map. At its core, a web map contains information about the layers that need to display on a map, their order, visibility, and rendering details. A web map can also contain additional information such as bookmarks, notes, slides, tasks, widgets, and so on.

Learn more about the web map format.

You can create and share web maps interactively on ArcGIS.com using applications like ArcGIS Explorer Online or the built-in ArcGIS.com Viewer. You can then view these web maps using a variety of web and mobile clients, including your custom applications built using this API.

Learn more about working with web maps.

The API only supports a subset of information in the web map, such as layer information, pop-up definitions, and bookmarks. All other information in the web map is ignored. The layer information is used to construct and add layers to a map view. The pop-up definitions are used to display and edit feature details using AGSPopupsContainerViewController. The bookmarks are made available as AGSEnvelope objects, which can be used to zoom the map into specific areas.


If you're interested in accessing the information stored in the web map, you can get the raw JSON data of the web map from the json property on the AGSWebMap AGSWebMap object.

To view the contents of a web map, you need to:

  1. Load the web map
  2. Set the delegate
  3. Open into a map view

Load the web map

To load a web map, instantiate an AGSWebMap object.

If the web map is hosted on ArcGIS.com and publicly accessible, provide the ID of the web map when instantiating AGSWebMap. You can find this ID in the URL of the web map.

Web map
Web map on ArcGIS.com

However, if the web map is private or shared only with a few people, provide valid credentials to access the web map. Here is an example:

let credential = AGSCredential(user: "<user>", password: "<password>")
credential.authType = .Token
let webmap = AGSWebMap(itemId: "e229d715f7ca4fa980308549fb288165", credential: credential

If the web map is hosted outside ArcGIS.com, for example, on your enterprise ArcGIS Portal, provide the URL of the sharing endpoint where the web map's data can be accessed. Here is an example:

let endpoint = NSURL(string: "http://<my_arcgis_portal>/sharing")
let webmap = AGSWebMap(itemId: "e229d715f7ca4fa980308549fb288165", sharingEndPoint: endpoint, credential: credential)

When you create the AGSWebMap object, ensure you take ownership of it. Otherwise, its memory might get deallocated before it has a chance to execute. If you instantiate the web map using alloc as shown above, you automatically have ownership. However, if you instantiate the web map using a convenience constructor, for instance webMapWithItemId:credential:, explicitly take ownership by assigning it to a property that retains it.

When you finish using the web map, relinquish ownership so that its memory can be reclaimed. Do this by setting the corresponding property to nil.


Refer to Apple's Advanced Memory Management Programming Guide for more information on how to manage object memory.

Set the delgate

The web map informs its delegate when operations complete successfully or if errors are encountered.

When loading a web map, the delegate is informed if the web map's data is retrieved successfully or not.

When opening a web map into a map view, the delegate is informed when each layer in the web map loads successfully. If any layer fails to load, the delegate can skip to the next layer or can try again to load the current layer with different credentials. If the web map contains a Bing Maps layer, the delegate is asked to provide a valid Bing Maps App ID to use with that layer.

To respond to such events, set one of your classes as the web map's delegate. Do this by making your class (typically the view controller that uses the web map) adopt the AGSWebMapDelegate protocol.

class ViewController: UIViewController, AGSWebMapDelegate {

An instance of your class must then be set as the web map's delegate. This allows the web map to invoke methods on your class in response to operations the web map performs.

webmap.delegate = self

Finally, your class should implement one or more methods defined in the AGSWebMapDelegate protocol that pertains to the event you want to handle. Here is an example:

func webMapDidLoad(webMap: AGSWebMap!) {
 //webmap data was retrieved successfully

func webMap(webMap: AGSWebMap!, didFailToLoadWithError error: NSError!) {
 //webmap data was not retrieved
 //alert the user
 println("Error while loading webmap: \(error.localizedDescription)")
func didOpenWebMap(webMap: AGSWebMap!, intoMapView mapView: AGSMapView!) {
 //web map finished opening
func webMap(webMap: AGSWebMap!, didLoadLayer layer: AGSLayer!) {
 //layer in web map loaded properly
func webMap(webMap: AGSWebMap!, didFailToLoadLayer layerInfo: AGSWebMapLayerInfo!, baseLayer: Bool, federated: Bool, withError error: NSError!) {
 //you can skip loading this layer
 //or you can try loading it with proper credential if the error was security related
func bingAppIdForWebMap(webMap: AGSWebMap!) -> String! {
 return "<your_bing_app_id>"

Open into map view

After setting the delegate, and to view the contents of a web map, open the web map into a map view.



The map resets to an unloaded state before opening the web map. This means that all previous layers in the map are removed, and the extent and spatial reference information for the map is cleared.