10.2.5: AGSLocator Class Reference
10.2.5
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Pages
AGSLocator Class Reference

Description

An instance of this class allows you to geocode addresses and reverse-geocode locations using a remote geocoding service. Geocoding involves finding matching locations for a given address. Reverse-geocoding is the opposite and involves finding corresponding addresses for a given location.

The geocoding service could be hosted in the cloud on ArcGIS Online or on-premise with ArcGIS Server ( For example, http://tasks.arcgisonline.com/ArcGIS/rest/services/Locators/ESRI_Places_World/GeocodeServer )

The default locator created using locator (AGSLocator) uses the World Geocode Service on ArcGIS Online. The service covers 100+ countries and is capable of finding locations based on street addresses, points of interest, postal codes, x/y coordinates, place names, and more.

See also
Conceptual Doc: Using a Locator
Sample: Geocoding
Sample: Geocoding Offline
Since
1.0
Inheritance diagram for AGSLocator:
AGSTask <AGSSecuredResource>

Instance Methods

(NSOperation *) - addressForLocation:maxSearchDistance:
 
(NSOperation *) - addressForLocation:maxSearchDistance:outSpatialReference:
 
(void) - cancelResumableTaskJobWithResumeID:
 
(NSOperation *) - fetchLocatorInfo
 
(NSOperation *) - findWithParameters:
 
(id) - initWithName:error:
 
(id) - initWithName:settings:error:
 
(id) - initWithPath:error:
 
(id) - initWithPath:settings:error:
 
(id) - initWithURL:
 
(id) - initWithURL:credential:
 
(NSOperation *) - locationsForAddress:returnFields:
 
(NSOperation *) - locationsForAddress:returnFields:outSpatialReference:
 
(NSOperation *) - locationsForAddressWithParameters:
 

Class Methods

(NSDictionary *) + activeResumeIDs
 
(void) + checkStatusForAllResumableTaskJobsWithCompletion:
 
(BOOL) + isActiveResumeID:
 
(id) + locator
 
(id) + locatorWithName:error:
 
(id) + locatorWithName:settings:error:
 
(id) + locatorWithPath:error:
 
(id) + locatorWithPath:settings:error:
 
(id) + locatorWithURL:
 
(id) + locatorWithURL:credential:
 

Properties

AGSCredentialcredential
 
AGSCredentialCachecredentialCache
 
id< AGSLocatorDelegatedelegate
 
NSURLRequestCachePolicy requestCachePolicy
 
NSTimeInterval timeoutInterval
 
NSURL * URL
 

Method Documentation

+ (NSDictionary*) activeResumeIDs

Returns a dictionary of all active resumable jobs. The key will be the jobType and the value will be an array of resumeIDs.

Since
10.2.2

Provided by category AGSTask(AsyncServerJobs).

- (NSOperation *) addressForLocation: (AGSPoint *)  location
maxSearchDistance: (double)  distance 

Executes a reverse-geocoding operation to find address candidates for a given location. The delegate will be notified when the operation completes or if an error is encountered..

It relies on the Reverse Geocode operation of the REST resource.

Parameters
locationLocation to search for address candidates. If the AGSPoint does not have a spatial reference, it is assumed to be in the same spatial reference as that of the geocode service.
distanceDistance in meters from the given location within which a matching address should be searched. If this parameter is not provided or an invalid value is provided, a default value of 0 meters is used.
Returns
NSOperation for current request.
Since
1.0
See also
- locator:operation:didFindAddressForLocation: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailAddressForLocation: (AGSLocatorDelegate-p) , method on delegate for failure
- (NSOperation *) addressForLocation: (AGSPoint *)  location
maxSearchDistance: (double)  distance
outSpatialReference: (AGSSpatialReference *)  sr 

Executes a reverse-geocoding operation to find address candidates for a given location. The delegate will be notified when the operation completes or if an error is encountered.

It relies on the Reverse Geocode operation of the REST resource.

Parameters
locationLocation to search for address candidates. If the AGSPoint does not have a spatial reference, it is assumed to be in the same spatial reference as that of the geocode service.
distanceDistance in meters from the given location within which a matching address should be searched. If this parameter is not provided or an invalid value is provided, a default value of 0 meters is used.
srSpatial reference of output geometries.
Returns
NSOperation for current request.
Availability:
This feature is only available with services from ArcGIS Server 10.0 or above
Since
1.0
See also
- locator:operation:didFindAddressForLocation: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailAddressForLocation: (AGSLocatorDelegate-p) , method on delegate for failure
- (void) cancelResumableTaskJobWithResumeID: (NSString *)  resumeID

Cancels the job with the associated resumeID.

Parameters
resumeIDThe resume ID of the job to be canceled.
Since
10.2.2

Provided by category AGSTask(AsyncServerJobs).

+ (void) checkStatusForAllResumableTaskJobsWithCompletion: (void(^)(UIBackgroundFetchResult result))  completion

Provides a way to check the status of all pending async server jobs while the app is in the background. If any job is complete, it will also initiate the download in the background.

This method should be called in the -[UIApplicationDelegate application:performFetchWithCompletionHandler:] delegate method.

Note
Only applicable to iOS 7 or later. You will need to enable the "background fetch" capability at your application level in order to take advantage of this method while your app has been suspended.
See also
- setBackgroundURLSessionCompletionHandler:forIdentifier: (AGSURLSessionManager) to handle downloads in background
Since
10.2.2
See also
Sample: Download Tile Cache
Sample: Offline Feature Editing

Provided by category AGSTask(AsyncServerJobs).

- (NSOperation *) fetchLocatorInfo

Executes an operation to retrieve service info. The delegate will be notified when the operation completes or if an error is encountered..

Returns
NSOperation for current request.
See also
- locator:operation:didFetchLocatorInfo: (AGSLocatorDelegate-p) , method on delegate for success
AGSLocatorDelegate::locator:operation:didFailFetchLocatorInfo: , method on delegate for failure
Since
10.2
- (NSOperation*) findWithParameters: (AGSLocatorFindParameters *)  findParams

Executes a geocoding operation to find location candidates for various types of inputs -

  • address (380 New York St Redlands CA)
  • point of interest (Disneyland, bank in paris, los angeles starbucks, mount everest)
  • administrative place name (Seattle Washington)
  • postal code (90201 USA)
  • X/Y coordinates (-117.155579,32.703761)

The delegate will be notified when the operation completes or if an error is encountered.

Note
This feature is only available with the default locator created using locator
Parameters
findParamsParameters for performing the operation
Since
10.1.1
See also
- locator:operation:didFind: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailToFindWithError: (AGSLocatorDelegate-p) , method on delegate for failure
- (id) initWithName: (NSString *)  name
error: (NSError **)  error 

Initialize locator with default settings. This may be not optimal from performance/memory use balance.

Parameters
nameName of the locator (excluding the .loc extension) within the application bundle or shared documents directory.
errorNSError if locator cannot be opened then error is returned.
Since
10.2
Note
Requires a standard license for deployment.
- (id) initWithName: (NSString *)  name
settings: (AGSLocatorSettings *)  settings
error: (NSError **)  error 

Initialize locator.

Parameters
nameName of the locator (excluding the .loc extension) within the application bundle or shared documents directory.
settingsAGSLocatorSettings object containing parameters related to performance and memory consumption balance.
errorNSError if locator cannot be opened then error is returned.
Since
10.2
Note
Requires a standard license for deployment.
- (id) initWithPath: (NSString *)  path
error: (NSError **)  error 

Initialize Locator with default settings. This may be not optimal from performance/memory use balance.

Parameters
pathAbsolute path to a locator file (including the .loc extension) on the device
errorNSError if locator cannot be opened then error is returned.
Returns
A new, autoreleased, locator object.
Since
10.2
Note
Requires a standard license for deployment.
- (id) initWithPath: (NSString *)  path
settings: (AGSLocatorSettings *)  settings
error: (NSError **)  error 

Initializes Locator.

Parameters
pathAbsolute path to a locator file (including the .loc extension) on the device
settingsAGSLocatorSettings object containing parameters related to performance and memory consumption balance.
errorNSError if locator cannot be opened then error is returned.
Returns
initialized locator.
Since
10.2
Note
Requires a standard license for deployment.
- (id) initWithURL: (NSURL *)  url

Initialize the task.

Parameters
urlURL to a task resource in the ArcGIS Server REST Services Directory.
Returns
A new task object.
Since
1.0
- (id) initWithURL: (NSURL *)  url
credential: (AGSCredential *)  cred 

Initialize the task with a URL and credential to a secured resource.

Parameters
urlURL to a task resource in the ArcGIS Server REST Services Directory.
credAGSCredential used to access secure resource.
Returns
A new task object.
Since
1.0

Implemented in AGSExportTileCacheTask.

+ (BOOL) isActiveResumeID: (NSString *)  resumeID

Returns YES if the job with the specified resumeID is still valid.

Since
10.2.2

Provided by category AGSTask(AsyncServerJobs).

- (NSOperation *) locationsForAddress: (NSDictionary *)  address
returnFields: (NSArray *)  outFields 

Executes a geocoding operation to find location candidates for a given address. The delegate will be notified when the operation completes or if an error is encountered.

It relies on the Find Address Candidates operation of the REST resource.

Parameters
addressA dictionary with key-value pairs of address field name and value. The address fields for a geocode service resource are listed in the Address Fields section of the Services Directory.
outFieldsA list of candidate fields you want to be included in the returned results. If the address represents an intersection, you need to specify fields from the Intersection Candidate Fields section of the Services Directory. If the address does not represent an intersection, you need to specify fields from the Candidate Fields section. For geocode services of ArcGIS Server 10 or above, you can specify "*" to get all the fields.
Returns
NSOperation for current operation.
Since
1.0
See also
- locator:operation:didFindLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for failure
- (NSOperation *) locationsForAddress: (NSDictionary *)  address
returnFields: (NSArray *)  outFields
outSpatialReference: (AGSSpatialReference *)  sr 

Executes a geocoding operation to find location candidates for a given address. The delegate will be notified when the operation completes or if an error is encountered.

It relies on the Find Address Candidates operation of the REST resource.

Parameters
addressDictionary with key-value pairs of address field name and value. The address fields for a geocode service resource are listed in the Address Fields section of the Services Directory.
outFieldsList of candidate fields you want to be included in the returned results. If the address represents an intersection, you need to specify fields from the Intersection Candidate Fields section of the Services Directory. If the address does not represent an intersection, you need to specify fields from the Candidate Fields section. For geocode services of ArcGIS Server 10 or above, you can specify "*" to get all the fields.
srSpatial reference of output geometries.
Returns
NSOperation for current operation.
Availability:
This feature is only available with services from ArcGIS Server 10.0 or above
Since
1.0
See also
- locator:operation:didFindLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for failure
- (NSOperation *) locationsForAddressWithParameters: (AGSLocationsForAddressParameters *)  params

Executes a geocoding operation to find location candidates for a given address. The delegate will be notified when the operation completes or if an error is encountered.

This method is functionally equivalent to locationsForAddress:returnFields: locationsForAddress:returnFields:outSpatialReference: , but its parameters provide a few more options for narrowing down the results.

Parameters
paramsParameters for performing the operation
Since
10.1.1
See also
- locator:operation:didFindLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for success
- locator:operation:didFailLocationsForAddress: (AGSLocatorDelegate-p) , method on delegate for failure
+ (id) locator

Initializes a default locator that uses the World Geocode Service on ArcGIS Online. The service covers 100+ countries and is capable of finding locations based on street addresses, points of interest, postal codes, x/y coordinates, place names, and more.

Since
10.1.1
See also
- findWithParameters:
+ (id) locatorWithName: (NSString *)  name
error: (NSError **)  error 

Initialize autoreleased Locator with default settings. This may be not optimal from performance/memory use balance.

Parameters
nameName of the locator (excluding the .loc extension) within the application bundle or shared documents directory.
errorNSError if locator cannot be opened then error is returned.
Returns
A new, autoreleased, locator object.
Since
10.2
Note
Requires a standard license for deployment.
+ (id) locatorWithName: (NSString *)  name
settings: (AGSLocatorSettings *)  settings
error: (NSError **)  error 

Initialize autoreleased Locator.

Parameters
nameName of the locator (excluding the .loc extension) within the application bundle or shared documents directory.
settingsParameters related to performance and memory consumption balance.
errorNSError if locator cannot be opened then error is returned.
Returns
A new, autoreleased, locator object.
Since
10.2
Note
Requires a standard license for deployment.
+ (id) locatorWithPath: (NSString *)  path
error: (NSError **)  error 

Initialize autoreleased Locator with default settings. This may be not optimal from performance/memory use balance.

Parameters
pathAbsolute path to a locator file (including the .loc extension) on the device
errorNSError if locator cannot be opened then error is returned.
Returns
A new, autoreleased, locator object.
Since
10.2
Note
Requires a standard license for deployment.
+ (id) locatorWithPath: (NSString *)  path
settings: (AGSLocatorSettings *)  settings
error: (NSError **)  error 

Initialize autoreleased Locator.

Parameters
pathAbsolute path to a locator file (including the .loc extension) on the device
settingsParameters related to performance and memory consumption balance.
errorNSError if locator cannot be opened then error is returned.
Returns
A new, autoreleased, locator object.
Since
10.2
Note
Requires a standard license for deployment.
+ (id) locatorWithURL: (NSURL *)  url

Initialize autoreleased Locator.

Parameters
urlURL to a geocode service.
Returns
A new, autoreleased, locator object
Since
1.0
+ (id) locatorWithURL: (NSURL *)  url
credential: (AGSCredential *)  cred 

Initialize autoreleased Locator.

Parameters
urlURL to a geocode service.
credAGSCredential to access a secure locator.
Returns
A new, autoreleased, locator object.
Since
1.0

Property Documentation

- (AGSCredential*) credential
readwritenonatomiccopyinherited

The credential to be used to access secured resources.

Since
1.0
- (AGSCredentialCache*) credentialCache
readwritenonatomicstronginherited

The credential cache to be used for this resource.

Since
10.1.1
- (id<AGSLocatorDelegate>) delegate
readwritenonatomicweak

Delegate to be notified when the locator completes successfully or encounters an error.

Since
1.0
- (NSURLRequestCachePolicy) requestCachePolicy
readwritenonatomicassigninherited

The cache policy that should be used for making the web request. Default value is NSURLRequestUseProtocolCachePolicy

Since
10.1.1
- (NSTimeInterval) timeoutInterval
readwritenonatomicassigninherited

The timeout interval (in seconds) for this request. Default value is 60.

Since
10.1.1
- (NSURL*) URL
readnonatomiccopyinherited

URL to a task resource in the ArcGIS Server REST Services Directory.

Since
1.0