Display attributes of a feature

With the Identify task, you can search the layers in a map for features that intersect an input geometry. Once the matching features return, you can display their geometries and attributes in your application. To use an Identify task, 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 results
  • Handle errors

The following sections describe these steps in more detail.

Create the Identify task

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

NSURL* url = [NSURL URLWithString: @"http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Demographics/ESRI_Census_USA/MapServer/5";
AGSIdentifyTask* identifyTask = [[AGSIdentifyTask alloc] initWithURL: url];

When you create the task, ensure you take ownership of it. Otherwise, it might get deallocated before it has a chance to execute. If you instantiate the task as shown above, you automatically have ownership. However, if you instantiate the task using a convenience constructor, for instance identifyTaskWithURL:, take ownership by sending it a strong message, or by assigning it to a property that retains it.

When you are finished using the task, relinquish ownership so that its memory can be reclaimed. Do this by setting the corresponding property to nil.

- (void)dealloc {   
  self.identifyTask = nil;       

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

Once the Identify task has been created, set the tasks’s delegate property to self (this is discussed later).

identifyTask.delegate = self;

Create input parameters for the Identify task

Before executing your task, set the Identify parameters. These parameters are stored in an AGSIdentifyParameters object.

AGSIdentifyParameters* identifyParams = [[AGSIdentifyParameters alloc] init];

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

  • Size—The size of the map currently being viewed, in pixels.
  • returnGeometry—If set to Yes, the result set includes the geometry associated with each result. The default is No.
  • tolerance—The distance in screen pixels from the specified geometry within which the identify is 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—The geometry used to select features to identify.
  • layerIds—An array of layer IDs that the Identify operation is performed on. These can be obtained from the map service documentation or the layerInfo property of an AGSDynamicMapServiceLayer.
  • mapEnvelope—The extent or bounding box of the currently viewed map view.
  • spatialReference—The spatial reference of the map view.
  • dpi—Ignore the dpi property for now.

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

//the layer you want is layer ‘5’ (from the map service doc)
identifyParams.layerIds = [NSArray arrayWithObjects:[NSNumber numberWithInt:5], nil];
identifyParams.tolerance = 3;
identifyParams.geometry = mapPoint;
identifyParams.size = self.mapView.bounds.size;
identifyParams.mapEnvelope = self.mapView.envelope;
identifyParams.returnGeometry = YES;
identifyParams.layerOption = AGSIdentifyParametersLayerOptionAll;
identifyParams.spatialReference = self.mapView.spatialReference;

Execute the task

Executing the task is easy. Once you have created the task, and have created and set up your AGSIdentifyParameters object, call the executeWithParameters method on your Identify task.

//execute task...
[self.identifyTask executeWithParameters:identifyParams];

The task automatically displays the network activity indicator that indicates it is waiting for results for the operation.

Retreive results

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

- (void)identifyTask:(AGSIdentifyTask *) identifyTask operation: (NSOperation *) op didExecuteWithIdentifyResults:(NSArray *) results {

- (void)identifyTask:(AGSIdentifyTask *) identifyTask	
 operation: (NSOperation *) op 
 didFailWithError:(NSError *) error {

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

In addition to implementing the methods above, set the delegate property of the Identify task to self as mentioned in the “How to create an Identify task” section. This ensures that your AGSIdentifyTaskDelegate methods get 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. Note that the AGSGraphic object does not have an associated symbol. It is up to you to set the symbol property if you are going to draw the graphic.

The following is an example of the identifyTask:didExecuteWithIdentifyResults method. The method turns off the network activity indicator; it clears the previous results from your graphics layer; it loops through the result array, getting all of 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 to draw on the map.

- (void)identifyTask:(AGSIdentifyTask *) identifyTask didExecuteWithIdentifyResults:(NSArray *) results
    //clear previous results
    [self.gLayer removeAllGraphics];

    //add new results
    AGSSymbol* symbol = [AGSSimpleFillSymbol simpleFillSymbol];
    symbol.color = [NSColor colorWithRed:0 green:0 blue:1 alpha:0.5];
    for (AGSIdentifyResult* result in results) {
        result.feature.symbol = symbol;
        [self.gLayer addGraphic:result.feature];
    //call dataChanged on the graphics layer to redraw the graphics
    [self.gLayer dataChanged];

The AGSGraphic object represented by the feature property of 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.

Handle execution errors

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

- (void)identifyTask:(AGSIdentifyTask *) identifyTask didFailWithError:(NSError *) error
 ... Handle the error