Skip To Content

Add layers with code

In this topic

This topic describes the types of layers you can add to a map, shows you how to add the layers, and outlines which delegates are called when a layer loads into the map.

Conceptually, a map consists of series of layers. A map is displayed within a AGSMapView component that can be added to the user interface of an application. Thus, the map view acts like an empty canvas onto which one or more map layers are drawn. Layers display in bottom to top order so that subsequent layers render on top of previous layers. Each map layer references data stored in a map service, tiled service and so on, rather than actually storing the geographic data. This API can support a wide range of layer types: tiled layers, dynamic layers, feature layers, graphic layers and many others including image layers, WMS layers, and Bing map layers.

A configuration of layers and services can also be authored and saved in ArcGIS Online in a web map that is accessed via its unique ItemId. Explore more about web maps here.

Add layers to the map

To add a layer to a map view, do the following:

  1. Instantiate the layer. If the layer relies on a web service, provide the URL of the service. If the web service is secured, provide the necessary credentials to access the service.
    NSURL* url = [NSURL URLWithString: @""];
    AGSTiledMapServiceLayer* layer = [AGSTiledMapServiceLayer tiledMapServiceLayerWithURL: url];
  2. Add the layer to the map view using the addMapLayer:withName: method. By default, the layer is added on top of any existing layers. Layers are drawn in a bottom-up order. This means that a layer can potentially obscure the contents of other layers beneath it. If you want to insert the layer at a specific position, you can use the insertMapLayer:withName:atIndex: method where an index of 0 inserts the new layer at the bottom. Provide a unique name while adding or inserting a layer. The map uses this to keep track of the layer in case you want to retrieve it later.
    [mapView addMapLayer:layer withName:@"Streets"];

Once the layer successfully loads, its content appears on the map.

Verify the layer was loaded

Layers connect to web services in the background. They do not block the thread on which they were added to a map. Hence, you should not assume that a layer successfully loads as soon as the addMapLayer:withName: or insertMapLayer:withName:atIndex: methods complete. Depending on the network connection, it could take a while for the layer to make a connection with the web service and retrieve the information it needs.

A layer informs its delegate when it successfully loads or if an error is encountered. To be notified of either of these events adopt the AGSLayerDelegate protocol.

@interface MyViewController : UIViewController <AGSLayerDelegate> 

The delegate must also implement one or more methods defined in the protocol that pertains to the operation being performed. For example, the delegate must implement the layerDidLoad: method to be notified when a layer successfully loads. Similary, to be notified when an error is encountered while adding a layer, implement the layer:didFailtToLoadwithError: method.

@implementation MyViewController
  - (void) layerDidLoad: (AGSLayer*) layer{
  	NSLog(@"Layer added successfully");   

  - (void) layer : (AGSLayer*) layer didFailToLoadwithError:(NSError*) error {
     NSLog(@"Error: %@",error);

  //Inspect the error and then either ...
  //A. Remove the layer if it's not essential
  if (layer !== self.mapView.baseLayer)
    [self.mapView removeMapLayerWithName:@"the layer name"];

  //B. Or, try resubmitting the layer, with different URL or credentials perhaps
  AGSTiledMapServiceLayer* tiledLyr = (AGSTiledMapServiceLayer*)layer;
  [tiledLyr resubmitWithURL:url credential:cred];


Finally, an instance of the class must then be set as the layer’s delegate. This establishes a relationship between the layer and class, and delegate methods implemented on the class will invoke when appropriate.

layer.delegate = self;

Once the layer is successfully added, its content appears on the map, then you can safely access the layer's properties.

Access layer properties

As mentioned previously, when a layer relies on a web service, it connects to the service in the background. The service usually provides, among other things, default values for the layer's properties. For example, AGSTiledMapServiceLayer connects to an ArcGIS Server map service to get information about the extent, tiling scheme, and so on. Layer properties are initialized only after a response is recieved from the service. Depending on factors such as the service response time, network connection quality, and so on, it may take a while before a layer's properties are fully initialized.

When a layer successfully loads, it informs its delegate as described above. Also, its loaded property will be enabled. This indicates that all properties on the layer have been fully initialized.

Map's spatial reference

The first layer you add to a map is considered to be the basemap layer. It dictates the initial extent of the map and also the overall spatial reference of the map. Any tiled layers you subsequently add to a map must also be in this spatial reference; otherwise, their content will not display. Dynamic layers, on the other hand, can be in any spatial reference because they automatically re-project their content, when necessary, into the map's spatial reference. View this topic for more information on a map's spatial reference.


The map remains blank if the basemap layer fails to load because the map does not get assigned a spatial reference and cannot combine map content from other layers into a common frame. You must handle this scenario appropriately. If the basemap layer is central to the map, reload the layer, then inform the user if it fails again. However, if the basemap layer is not critical, remove it from the map, in which case, the next layer becomes the basemap layer.