com.esri.core.tasks.ags.geocode
Class Locator

java.lang.Object
  com.esri.core.tasks.ags.geocode.Locator

public class Locator
extends Object

This class allows you to geocode and reverse-geocode addresses using a geocode service of ArcGIS Server.

Geocoding involves finding matching locations for a given address.

Reverse-geocoding involves finding corresponding addresses for a given location.

Constructor Summary

Locator(String url)
Constructor accepting the URL of a Geocode service

Locator(String url, UserCredentials credentials)
Constructor accepting the URL of a Geocode service

Method Summary

List<LocatorGeocodeResult>	addressToLocations(Map<String,String> addressFields, List<String> outFields) Executes a geocoding operation to find location candidates for a given address.
List<LocatorGeocodeResult>	addressToLocations(Map<String,String> addressFields, List<String> outFields, SpatialReference outSR) Executes a geocoding operation to find location candidates for a given address.
void	addressToLocationsAsync(Map<String,String> addressFields, List<String> outFields, CallbackListener<List<LocatorGeocodeResult>> listener)
void	addressToLocationsAsync(Map<String,String> addressFields, List<String> outFields, SpatialReference outSR, CallbackListener<List<LocatorGeocodeResult>> callback)
BatchGeocodeResult	batchAddressToLocation(List<Map<String,String>> addresses) Matches addresses to locations.
BatchGeocodeResult	batchAddressToLocation(List<Map<String,String>> addresses, SpatialReference outSR) Matches addresses to locations.
void	batchAddressToLocationAsync(List<Map<String,String>> addresses, CallbackListener<BatchGeocodeResult> callback) Matches addresses to locations asynchronously.
void	batchAddressToLocationAsync(List<Map<String,String>> addresses, SpatialReference outSR, CallbackListener<BatchGeocodeResult> callback) Matches addresses to locations asynchronously.
List<LocatorGeocodeResult>	find(LocatorFindParameters findParams) Executes a finding operation to find location candidates for a given address, POI, or a String Note: currently the method is only applied to the world geocoding service hosted on the ArcGIS online.
void	findAsync(LocatorFindParameters findParams, CallbackListener<List<LocatorGeocodeResult>> callback) Asynchronously executes a finding operation to find location candidates for a given address, POI, or a String Note: currently the method is only applied to the world geocoding service hosted on the ArcGIS online.
LocatorServiceInfo	getInfo() Returns the information of the Geocode service this instance is querying from such as address fields, candidate fields, service properties...
String	getUrl() Returns the URL of the Geocode service used by this instance of the Locator.
LocatorReverseGeocodeResult	locationToAddress(Point point, double distance) Executes a reverse-geocoding operation to find address candidates for a given location.
LocatorReverseGeocodeResult	locationToAddress(Point point, double distance, SpatialReference inSR, SpatialReference outSR) Executes a reverse-geocoding operation to find address candidates for a given location.
void	locationToAddressAsync(Point point, double distance, CallbackListener<LocatorReverseGeocodeResult> callback)
void	locationToAddressAsync(Point point, double distance, SpatialReference inSR, SpatialReference outSR, CallbackListener<LocatorReverseGeocodeResult> callback)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Locator

public Locator(String url)

Constructor accepting the URL of a Geocode service

Parameters:

url - URL to the REST endpoint of a Geocode service

Locator

public Locator(String url,
               UserCredentials credentials)
        throws EsriSecurityException

Constructor accepting the URL of a Geocode service

Parameters:

url - URL to the REST endpoint of a Geocode service

credentials - the credentials used for accessing a secure Geocode service

Throws:

EsriSecurityException

Method Detail

getUrl

public String getUrl()

Returns the URL of the Geocode service used by this instance of the Locator.

Returns:

the URL of the Geocode service used by this instance of the Locator

getInfo

public LocatorServiceInfo getInfo()
                           throws Exception

Returns the information of the Geocode service this instance is querying from such as address fields, candidate fields, service properties...

Returns:

a LocatorServiceInfo containing the service information

Throws:

Exception

addressToLocations

public List<LocatorGeocodeResult> addressToLocations(Map<String,String> addressFields,
                                                     List<String> outFields)
                                              throws Exception

Executes a geocoding operation to find location candidates for a given address.
The output fields can be specified, passing null will return all the output fields defined for the service.

Parameters:

addressFields - a Map containing the address fields and their corresponding values

outFields - a List of output fields to be returned for each address candidate

Returns:

a List of LocatorGeocodeResults.

Throws:

Exception

addressToLocationsAsync

public void addressToLocationsAsync(Map<String,String> addressFields,
                                    List<String> outFields,
                                    CallbackListener<List<LocatorGeocodeResult>> listener)
                             throws Exception

Throws:

Exception

addressToLocations

public List<LocatorGeocodeResult> addressToLocations(Map<String,String> addressFields,
                                                     List<String> outFields,
                                                     SpatialReference outSR)
                                              throws Exception

Executes a geocoding operation to find location candidates for a given address.
The output fields can be specified, passing null will return all the output fields defined for the service.
The location candidates will be returned in the spatial reference passed in the parameters, passing -1 will return the locations in the default spatial reference defined for the service.

Parameters:

addressFields - a Map containing the address fields and their corresponding values

outFields - a List of output fields to be returned for each address candidate

outSR - a spatial reference the location candidates will be projected to.

Returns:

a List of LocatorGeocodeResults.

Throws:

Exception

addressToLocationsAsync

public void addressToLocationsAsync(Map<String,String> addressFields,
                                    List<String> outFields,
                                    SpatialReference outSR,
                                    CallbackListener<List<LocatorGeocodeResult>> callback)
                             throws Exception

Throws:

Exception

batchAddressToLocation

public BatchGeocodeResult batchAddressToLocation(List<Map<String,String>> addresses)
                                          throws Exception

Matches addresses to locations. Results can be matched to input using the "ResultID" attribute in the results. This attribute matches the index of the address e.g. if three addresses are supplied then the matches would have result IDs of 0, 1 and 2. If the supplied addresses have an attribute "OBJECTID" then the result ID will be referenced to that value.

Parameters:

addresses - the addresses to match

Returns:

the result

Throws:

Exception

batchAddressToLocation

public BatchGeocodeResult batchAddressToLocation(List<Map<String,String>> addresses,
                                                 SpatialReference outSR)
                                          throws Exception

Matches addresses to locations. Results can be matched to input using the "ResultID" attribute in the results. This attribute matches the index of the address e.g. if three addresses are supplied then the matches would have result IDs of 0, 1 and 2. If the supplied addresses have an attribute "OBJECTID" then the result ID will be referenced to that value.

Parameters:

addresses - the addresses to match

outSR - the output spatial reference

Returns:

the result

Throws:

Exception

batchAddressToLocationAsync

public void batchAddressToLocationAsync(List<Map<String,String>> addresses,
                                        CallbackListener<BatchGeocodeResult> callback)

Matches addresses to locations asynchronously. Results can be matched to input using the "ResultID" attribute in the results. This attribute matches the index of the address e.g. if three addresses are supplied then the matches would have result IDs of 0, 1 and 2. If the supplied addresses have an attribute "OBJECTID" then the result ID will be referenced to that value.

Parameters:

addresses - the addresses to match

callback - the call back executed when the geocode operation completes

batchAddressToLocationAsync

public void batchAddressToLocationAsync(List<Map<String,String>> addresses,
                                        SpatialReference outSR,
                                        CallbackListener<BatchGeocodeResult> callback)

Matches addresses to locations asynchronously. Results can be matched to input using the "ResultID" attribute in the results. This attribute matches the index of the address e.g. if three addresses are supplied then the matches would have result IDs of 0, 1 and 2. If the supplied addresses have an attribute "OBJECTID" then the result ID will be referenced to that value.

Parameters:

addresses - the addresses to match

outSR - the output spatial reference

callback - the call back executed when the geocode operation completes

locationToAddress

public LocatorReverseGeocodeResult locationToAddress(Point point,
                                                     double distance)
                                              throws Exception

Executes a reverse-geocoding operation to find address candidates for a given location.
A distance in meters from the given location within which a matching address should be searched must be provided, 0 if non is desired.

Parameters:

point - the location to search for address candidates.

distance - the distance in meters from the given location within which a matching address should be searched.

Returns:

a LocatorReverseGeocodeResult

Throws:

Exception

locationToAddressAsync

public void locationToAddressAsync(Point point,
                                   double distance,
                                   CallbackListener<LocatorReverseGeocodeResult> callback)
                            throws Exception

Throws:

Exception

locationToAddress

public LocatorReverseGeocodeResult locationToAddress(Point point,
                                                     double distance,
                                                     SpatialReference inSR,
                                                     SpatialReference outSR)
                                              throws Exception

Executes a reverse-geocoding operation to find address candidates for a given location.
A distance in meters from the given location within which a matching address should be searched must be provided, 0 if non is desired.
The input spatial reference can be specified if the location coordinates are in a different spatial reference than the one expected by the service.
An Output spatial reference can be specified if the coordinates for the address candidates are wanted in a different spatial reference than the one defined in the service.

Parameters:

point - the location to search for address candidates.

distance - the distance in meters from the given location within which a matching address should be searched.

inSR - the input spatial reference for the location.

outSR - the output spatial reference for the location of the address candidates

Returns:

a LocatorReverseGeocodeResult

Throws:

Exception

locationToAddressAsync

public void locationToAddressAsync(Point point,
                                   double distance,
                                   SpatialReference inSR,
                                   SpatialReference outSR,
                                   CallbackListener<LocatorReverseGeocodeResult> callback)
                            throws Exception

Throws:

Exception

find

public List<LocatorGeocodeResult> find(LocatorFindParameters findParams)
                                throws Exception

Executes a finding operation to find location candidates for a given address, POI, or a String
Note: currently the method is only applied to the world geocoding service hosted on the ArcGIS online. You may obtain an exception for other geocoding service which is not supported for the operation.

The Find operation of a geocoding service is used for single field geocoding, and supports finding the following types of locations:

• Street addresses: 380 New York St, Redlands, CA 92373
• Administrative place names, such as city/county/state/province/country names: Seattle, Washington
• Postal codes: 92591 USA
• Points of interest (POI) and businesses:
Disneyland
banks in Paris

The output fields can be specified, passing null will return all the output fields defined for the service.
The location candidates will be returned in the spatial reference passed in the parameters, passing -1 will return the locations in the default spatial reference defined for the service.

Parameters:

findParams - the find parameters

Returns:

a List of LocatorGeocodeResults.

Throws:

Exception - the exception

findAsync

public void findAsync(LocatorFindParameters findParams,
                      CallbackListener<List<LocatorGeocodeResult>> callback)

Asynchronously executes a finding operation to find location candidates for a given address, POI, or a String
Note: currently the method is only applied to the world geocoding service hosted on the ArcGIS online. You may obtain an exception for other geocoding service which is not supported for the operation.

The Find operation of a geocoding service is used for single field geocoding, and supports finding the following types of locations:

• Street addresses: 380 New York St, Redlands, CA 92373
• Administrative place names, such as city/county/state/province/country names: Seattle, Washington
• Postal codes: 92591 USA
• Points of interest (POI) and businesses:
Disneyland
banks in Paris

The output fields can be specified, passing null will return all the output fields defined for the service.
The location candidates will be returned in the spatial reference passed in the parameters, passing -1 will return the locations in the default spatial reference defined for the service.

Parameters:

findParams - the find parameters

Throws:

Exception - the exception