Viewing a web map

A web map basically describes the contents to be displayed in a map. At its core, a web map contains information about the layers that need to be displayed in 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 using applications such as ArcGIS Explorer Online or the built-in Viewer. You can then view web maps using a variety of web and mobile clients, including your custom applications built using the API.

Learn more about working with web maps

The API only supports a subset of information in the web map, such as the 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 object.

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

  • Load the web map
  • Set the delegate
  • Open into a map view

You can also view the code in this sample: Web map sample

Load the web map

To load a web map, you need to instantiate an AGSWebMap object.

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

Webmap on
Web Map on
However, if the web map is private or shared only with a few people, you also need to provide valid credentials to access the web map. The following is an example:
AGSCredential* credential = [[[AGSCredential alloc] initWithUser:@"<user>" password:@"<password>"] autorelease];
credential.authType = AGSAuthenticationTypeToken;
AGSWebMap* webmap = [[AGSWebMap alloc] initWithItemId:@"e229d715f7ca4fa980308549fb288165" credential:credential];

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

NSURL* endpoint = [NSURL URLWithString:@"http://<my_arcgis_portal>/sharing"];
AGSWebMap* webmap = [[AGSWebMap alloc] initWithItemId:@"e229d715f7ca4fa980308549fb288165" sharingEndPoint:endpoint credential:credential];


When you instantiate a webmap, you need to ensure its memory does not get deallocated before it has a chance to execute. To do this, you need to retain the webmap if you're using manual retain-release, or create a strong reference to it if you're using ARC. See Apple Memory Management Programming Guide for more information on how to manage object memory.

Set the delegate

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

When loading a web map, the delegate is informed whether the web map 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 is loaded successfully. If any layer fails to load, the delegate is given an opportunity to skip to the next layer, or reload 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, you must set one of your classes as the web map's delegate. You do this by making your class (typically the view controller that uses the webmap) adopt the AGSWebMapDelegate protocol.

@interface MyViewController : 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 that the web map performs.

webmap.delegate = self;

Finally, your class should implement one ore more methods defined in the AGSWebMapDelegate protocol that pertain to the event you want to handle. The following is an example:

@implementation MyViewController {

  - (void) webMapDidLoad:(AGSWebMap*) webMap {
    //webmap data was retrieved successfully
  - (void) webMap:(AGSWebMap *)webMap didFailToLoadWithError:(NSError *)error {
    //webmap data was not retrieved
    //alert the user
    NSLog(@"Error while loading webmap: %@",[error localizedDescription]);

  -(void)didOpenWebMap:(AGSWebMap*)webMap intoMapView:(AGSMapView*)mapView{
   	//web map finished opening

  -(void)webMap:(AGSWebMap*)wm didLoadLayer:(AGSLayer*)layer{
  	 //layer in web map loaded properly
  -(void)webMap:(AGSWebMap*)wm didFailToLoadLayer:(NSString*)layerTitle url:(NSURL*)url baseLayer:(BOOL)baseLayer federated:(BOOL)federated withError:(NSError*)error{
    	NSLog(@"Error while loading layer: %@",[error localizedDescription]);
     //you can skip loading this layer
     //[self.webMap continueOpenAndSkipCurrentLayer];
     //or you can try loading it with proper credentials if the error was security related
     //[self.webMap continueOpenWithCredential:credential];

  -(NSString*) bingAppIdForWebMap:{
  	return @"<your_bing_app_id>";



If your delegate methods are not being invoked when as the webmap is being opened, check to make sure that the webmap is not getting deallocated before it finishes execution. You need to retain the webmap if you're using manual retain-release, or create a strong reference to it if you're using ARC.

Open into a map view

After setting the delegate, all that is left to do to view the contents of a web map is to open the web map into a map view.

[webmap openIntoMapView:self.mapView];


The map will be reset to an unloaded state before opening the web map. This means that all previous layers in the map will be removed, and the extent and spatial reference information of the map will be cleared.