Skip To Content

Identify task

In this topic

With the Identify task, you can search the layers in a map service for features that intersect an input geometry. Once the matching features are returned, you can display their geometries and attributes in your application. To use an Identify task, you need to do the following:

  • Create the task.
  • Set the Identify task delegate (to receive results).
  • Create the parameters that define the task.
  • Execute the task, usually in response to a user event.
  • Retrieve the results.
  • Handle any errors.

The following sections describe these steps in detail.

Creating the Identify task

To instantiate an AGSIdentifyTask, you need to provide a URL to a map service REST web service endpoint. This URL is usually of the form http://<server:port>/<instance>/services/<service>/MapServer. If the web service is secured, you also need to provide the credentials that can be used to access the service.

let url = NSURL(string: "")


When you create the task, 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 task if you're using manual retain-release, or create a strong reference to it if you're using ARC. See Apple's Memory Management Programming Guide for more information on how to manage object memory.

Once the Identify task has been created, you must set the tasks’s delegate property to self. This is explained in the Retrieving results section of this topic.
identifyTask.delegate = self

Creating the input parameters for the Identify task

Prior to executing the task, you need to set the Identify parameters. These parameters are stored in an AGSIdentifyParameters object.

let identifyParams = AGSIdentifyParameters()

There are a number of properties of the AGSIdentifyParameters object that you need to set. These include the layer IDs of the layers in the map service you want to identify, whether to return the geometries of any found features, the spatial reference of the map, and so on. The list of properties and a brief description of each is as follows:

  • Size—Size, in pixels, of the map currently being viewed.
  • returnGeometry—If Yes, the result set includes the geometry associated with each result. The default is No.
  • tolerance—Distance in screen pixels from the specified geometry within which the identify should be performed.
  • layerOption—Specifies which layers to use. This is of type AGSIdentifyParametersLayerOption and can have the following values:
    • AGSIdentifyParametersLayerOptionAll (use all layers)
    • AGSIdentifyParametersLayerOptionTop (use only the top layer)
    • AGSIdentifyParametersLayerOptionVisible (use only the visible layers)
  • geometry—Geometry used to select features to identify.
  • layerIds—Array of layer IDs on which the Identify operation will be performed. These can either be obtained from the map service documentation or the layerInfo property of an AGSDynamicMapServiceLayer.
  • mapEnvelope—Extent or bounding box of the map view currently being viewed.
  • spatialReference—Spatial reference of the map view.
  • dpi—This property can be ignored at this time.

The following is an example of setting up the AGSIdentifyParameters object:

//the layer we want is layer ‘5’ (from the map service doc)
identifyParams.layerIds = [5]
identifyParams.tolerance = 3
identifyParams.geometry = mapPoint
identifyParams.size = self.mapView.bounds.size
identifyParams.mapEnvelope = self.mapView.visibleAreaEnvelope
identifyParams.returnGeometry = true
identifyParams.layerOption = .All
identifyParams.spatialReference = self.mapView.spatialReference

Executing the task

Executing the task is actually quite simple. Once you have the task created and have created and set up your AGSIdentifyParameters object, you simply need to call the executeWithParameters method on your Identify task.


The task will automatically display the network activity indicator to indicate that it is waiting for results of the operation.

Retrieving the results

To get the results from the Identify task, your view controller needs to implement the AGSIdentifyTaskDelegate protocol. AGSIdentifyTaskDelegate has the following two methods:

func identifyTask(identifyTask: AGSIdentifyTask!, operation op: NSOperation!, didExecuteWithIdentifyResults results: [AnyObject]!) {

func identifyTask(identifyTask: AGSIdentifyTask!, operation op: NSOperation!, didFailWithError error: NSError!) {

identifyTask:didExecuteWithIdentifyResults is called if your task executed successfully. identifyTask:didFailWithError is called if there were problems executing the task.

In addition to implementing the methods above, the delegate property of the Identify task must be set to self as mentioned in the Creating the Identify task section. This ensures that your AGSIdentifyTaskDelegate methods is called.

The results parameter in identifyTask:didExecuteWithIdentifyResults is an array of AGSIdentifyResult objects. The AGSIdentifyResults class has properties for the display field name of the result, the layer ID, the layer name, and the feature. The feature is actually an AGSGraphic object containing the geometry of the result.


The AGSGraphic object does not have an associated symbol. You're responsible for setting the symbol property if you're going to draw the graphic.

The following is an example of the identifyTask:didExecuteWithIdentifyResults method. First, it turns off the network activity indicator. Then it clears the previous results from the graphics layer. Then it loops through the result array, getting all the graphics from the array (via the AGSIdentifyResult feature property) and assigning symbols to each graphic. The graphics are then added to the existing graphics layer in order to draw them on the map.

func identifyTask(identifyTask: AGSIdentifyTask!, operation op: NSOperation!, didExecuteWithIdentifyResults results: [AnyObject]!) {
 //clear previous results
 //add new results
 let symbol = AGSSimpleFillSymbol()

 symbol.color = UIColor(red: 0, green:0, blue:1, alpha:0.5)
 for result in results as [AGSIdentifyResult] {
  result.feature.symbol = symbol

The AGSGraphic object represented by the feature property of the AGSIdentifyResult also contains the attributes associated with the identified feature. These attributes are stored in an NSDictionary object inside the attributes property of the graphic.

Handling execution errors

Sometimes, for various reasons, the task execution does not complete successfully. In these situations, the identifyTask:didFailWithError method is called. This method passes both the Identify task object along with an NSError object containing the reason for the failure. The following is a typical identifyTask:didFailWithError implementation:

func identifyTask(identifyTask: AGSIdentifyTask!, operation op: NSOperation!, didFailWithError error: NSError!) {
 let alert = UIAlertView(title: "Identify Error", message: error.localizedDescription, delegate: nil, cancelButtonTitle: "Ok")

This method displays a UIAlertView with the error information contained in the NSError object.

See also