Map legend

A legend conveys the meaning of symbols used on the map. It associates a symbol with the real-world entity it represents. Each item in the legend usually consists of a symbol with a label containing explanatory text.


Retrieve legend information

You can retrieve legend information for the following layer types:

  • ArcGIS dynamic map service layer
  • ArcGIS tiled map service layer
  • ArcGIS feature layer
  • ArcGIS graphics layer

ArcGIS dynamic and tiled map service layers

You can retrieve legend images and labels by invoking the retrieveLegendInfo method on the layer's AGSMapServiceInfo object. AGSMapServiceInfo's delegate is informed when the legend information is retrieved successfully, or if an error is encountered. When successful, legendImages and legendLabels properties of individual AGSMapServiceLayerInfo objects populate.

@interface LegendFetcher : NSObject <AGSMapServiceInfoDelegate> {
   -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operation:(NSOperation *)op didFailToRetrieveLegendInfoWithError:(NSError *)error ;
   -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operationDidRetrieveLegendInfo:(NSOperation *)op ;

@implementation LegendFetcher {

 -(void) retrieveLegend {   
   AGSMapServiceInfo* msi = ...;
   //set the delegate
   msi.delegate = self;
   //retrieve legend 
   [msi retrieveLegendInfo];
 //delegate method called when error is encountered
 -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operation:(NSOperation *)op didFailToRetrieveLegendInfoWithError:(NSError *)error { 
   NSLog(@"Error : %@",error);

 //delegate method called when legend is retrieved successfully
 -(void) mapServiceInfo:(AGSMapServiceInfo *)mapServiceInfo operationDidRetrieveLegendInfo:(NSOperation *)op { 
   //loop through all sub-layers
   NSArray* layerInfos = mapServiceInfo.layerInfos;
   for(int i=0;i<[layerInfos count];i++){
     //access legend information of each sub-layer
     AGSMapServiceLayerInfo* layerInfo = [layerInfos objectAtIndex:i];
     NSArray* legendLabels = layerInfo.legendLabels;
     NSArray* legendImages = layerInfo.legendImages;

Legend information for ArcGIS dynamic and tiled map service layers is only available if the layers are using a service from ArcGIS Server version 10, service pack 1 or greater. This is because the REST API for services before version 10, SP1 did not provide legend information.

ArcGIS feature and graphics layers

For an ArcGIS feature layer, you would typically display a legend item for each feature type or feature template available in the layer. For a graphics layer, you would display a legend item for each type of symbol used by the layer. Renderers are usually a good starting point for determining how many legend items to display because a renderer associates different symbols with graphics based on logical groupings.

To create legend items for ArcGIS feature and graphics layers, retrieve images of symbols used in the layers. Both AGSRenderer and AGSSymbol provide convenience methods that return images for symbols.

AGSRenderer* renderer = ...;
AGSGraphic* graphic = ...;

//Getting legend image from a renderer
NSImage* image = [renderer swatchForGraphic:graphic size:CGSizeMake(20,30)]; 

//Getting legend image from a symbol
AGSSymbol* symbol = ...;
NSImage* image = [symbol swatchForGeometryType:AGSGeometryTypePoint size:CGSizeMake(20,30)];

Once you have the images, associate them with appropriate labels in the legend.

Display the legend

Once you have the image and label information for each legend item, display the legend using NSTableView or a custom view.