Search for places

The locator allows you to geocode addresses and reverse-geocode locations using ArcGIS Server geocode services. Geocoding an address involves finding a matching location on the Earth’s surface for that address. Reverse-geocoding is the exact opposite. It involves finding corresponding addresses for a given location on a map.

Geocode services are based on address locators. Address locators may reside in an ArcGIS geodatabase or as *.loc files on disk. They rely on GIS datasets and other reference data to find addresses and locations. Each address locator uses an address style for parsing addresses and standardizing them into well-structured address components. Use ArcMap or ArcCatalog to create new address locators and publish them as geocode services using ArcMap or ArcCatalog, or ArcGIS Server’s Manager web application.

ArcGIS Server geocode services are accessible on the web as SOAP and REST web services. The REST web service supports two operations: Find Address Candidates (geocode), and Reverse Geocode. While publishing a geocode service, the administrator may decide to enable/disable either of these two operations. Verify that the service you intend to use provides the functionality you want.

To successfully use the locator, you must know:

  • URL of the geocode service’s REST web service endpoint
  • Format of inputs expected by the service and the returned results

You can use the ArcGIS Server Services Directory to find out details about the service you want to use. You can easily find out what operations are supported.

Locator operations

If you're familiar with the REST API, you can invoke operations on the service directly from a browser using the services sirectory.

Create the locator

To instantiate an AGSLocator, provide a URL to a geocode service REST endpoint. This URL is usually formatted as http://<server:port>/<instance>/services/<service>/GeocodeServer. If the web service is secured, provide the credentials that can be used to access the service. This topic uses the ESRI_Geocode_USA service from a sample server on ArcGIS Online.

NSURL* url = [NSURL URLWithString: @"";
AGSLocator* locator = [[AGSLocator 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 using alloc as shown above, you automatically have ownership. However, if you instantiate the task using a convenience constructor, for instance locatorWithURL:, take ownership by assigning it to a property that retains it.

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


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

Geocode an address

To find matching locations for an address, provide an NSDictionary object containing the address in a format expected by the service. The format is listed in the Address Fields section in the services directory. Only required fields must be specified. Other fields may be omitted.

Address Fields section

For the service in this topic, specify Address, City, State, and Zip.

NSDictionary *address = [NSDictionary dictionaryWithObjectsAndKeys: @"380 New York St", @"Address", @"Redlands", @"City", @"CA", @"State", @"92373", @"Zip",  nil];

If you want to geocode an intersection of two streets instead of a business or home, use a permitted connector to specify the streets. This connector is listed in the Locator Properties section in the services directory. The service in this topic allows using the symbols &, |, or @ as connectors.

NSDictionary *address = [NSDictionary dictionaryWithObjectsAndKeys: @"New York St & State St", @"Address", @"Redlands", @"City", @"CA", @"State", @"92373", @"Zip",  nil];

Specify which fields should return when a matching location is found. The available fields are listed in the Candidate Fields section in the services directory. If the address you’re geocoding is an intersection, use the Intersection Candidate Fields section instead.

Candidate Fields
Intersection Candidate Fields

Services from ArcGIS Server 10 or above allow you to use the * wildcard to get all fields. For older servers, explicitly specify each field.

NSArray *outFields = [NSArray arrayWithObjects: @"Shape", @"Score", @"Match_addr", @"Side ", @"HouseNum", @"StreetName", @"StreetType", @"City","State", @"Zip", nil];

You can also optionally specify the output spatial reference. This is the spatial reference in which the matching location or locations should be returned to you. By default, the location or locations returned to you have the same spatial reference as that of the service. By explicitly specifying a different spatial reference, the geocode service can reproject the location or locations so that you can easily display them on your map. This is useful, for example, when the geocode service uses a spatial reference that is different from the spatial reference of your map.

AGSSpatialReference* outSR = [AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil];
[locator locationsForAddress:address returnFields:outfields outSpatialReference:outSR];

Reverse geocoding a location

To find address candidates for a location, provide a point representing the location. If the point does not have a spatial reference, the geocode service assumes it is in the spatial reference of the service. Also, provide a maximum search distance (in meters) within which to search for address candidates from the given location. You can optionally specify an output spatial reference in which the address candidates should return.

AGSPoint* point = [AGSPoint pointWithX: -117.195681386 y: 34.057517097 spatialReference:[AGSSpatialReference spatialReferenceWithWKID:4326 WKT:nil]];
[locator addressForLocation:point maxSearchDistance:100];

Get results and handle errors

The locator informs its delegate when operations complete successfully or when errors are encountered. To get results from the locator and to properly handle errors, set one of your classes as the locator’s delegate. Do this by making your class (typically the view controller that uses the locator) adopt the AGSLocatorDelegate protocol.

@interface MyViewController : NSViewController <AGSLocatorDelegate> {  

An instance of your class must also be set as the locator’s delegate. This allows the locator to invoke methods on your class in response to operations it performs.

locator.delegate = self;

Finally, your class must implement one or more methods defined in the protocol that pertains to the operation being performed. For geocoding operations, the delegate should implement the locator:operation:didFindLocationsForAddress: method to be informed when the operation finishes successfully. Results of the operation are passed to the delegate method as an array of AGSAddressCandidate objects.

- (void) locator:(AGSLocator*) locator operation:(NSOperation*) op didFindLocationsForAddress:(NSArray*) candidates {
   for (AGSAddressCandidate* candidate in candidates) {
     NSLog(@"Candidate : %@",candidate);  

To be informed of a failure, the delegate should implement the locator:operation:didFailLocationsForAddress: method. The reason for failure is passed to the method as an NSError object.

- (void) locator:(AGSLocator*) locator operation:(NSOperation*) op didFailLocationsForAddress:(NSError*) error { 
   NSLog(@"Error: %@",error); 
Related topics