Class: LocatorE-mail This Topic Printable Version Give Us Feedback

Description

Represents a geocode service resource exposed by the ArcGIS Server REST API. It is used to generate candidates for an address. It also used to find an address for a given location.

Class hierarchy

esri.tasks.Locator

Constructor

Constructor Description
esri.tasks.Locator(url) Creates a new Locator object.

Properties

Property Type Description
url String URL to the ArcGIS Server REST resource that represents a locator service. To obtain the URL, use Services Directory.

Methods

Method Return Value Description
addressToLocations(address, outFields?, callback?, errback?) dojo.Deferred Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address argument. On completion, the onAddressToLocationsComplete event is fired and the optional callback function is invoked.
locationToAddress(location, distance, callback?, errback?) dojo.Deferred Locates an address based on a given point.

Events

Event Description
onAddressToLocationsComplete(addressCandidates) Fires when Locator.addressToLocation() has completed. The result is an array of AddressCandidate. This is the same signature returned if the optional callback is specified.
onError(error) Fires when an error occurs when executing the task.
onLocationToAddressComplete(addressCandidate) Fires when Locator.locationToAddress() has completed. The result is an AddressCandidate. This is the same signature returned if the optional callback is specified.
Constructor Detail

esri.tasks.Locator(url)

Creates a new Locator object.
Parameters:
<String> url Required URL to the ArcGIS Server REST resource that represents a locator service. An example is http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Locators/ESRI_Geocode_USA/GeocodeServer. For more information on constructing a URL, see The Services Directory and the REST API.
Properties Detail

<String> url

URL to the ArcGIS Server REST resource that represents a locator service. To obtain the URL, use Services Directory.
Methods Detail

addressToLocations(address, outFields?, callback?, errback?)

Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address argument. On completion, the onAddressToLocationsComplete event is fired and the optional callback function is invoked.

The return object of dojo.Deferred was added at v1.4.
Return value: dojo.Deferred
Input Parameters:
<Object> address Required The address argument is data object that contains properties representing the various address fields accepted by the corresponding geocode service. These fields are listed in the addressFields property of the associated geocode service resource. For example, if the addressFields of a geocode service resource includes fields with the following names: Street, City, State and Zone, then the address argument is of the form: 
{
  Street: "<street>",
  City: "<city>",
  State: "<state>",
  Zone: "<zone>"
}
Services Directory can be used to find out the required and optional address fields.
<String[]> outFields Optional The list of fields included in the returned result set. This list is a comma delimited list of field names. If you specify the shape field in the list of return fields, it is ignored. For non-intersection addresses you can specify the candidate fields as defined in the geocode service. For intersection addresses you can specify the intersection candidate fields.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onAddressToLocationsComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Code snippets:
function locate() {
  var address = {
    street: "380 New York",
    city: "Redlands",
    state: "CA",
    zip: "92373"
  };
  locator.addressToLocations(address);
}

See also:
onAddressToLocationsComplete   onError  

locationToAddress(location, distance, callback?, errback?)

Locates an address based on a given point.

The return object of dojo.Deferred was added at v1.4.
Return value: dojo.Deferred
Input Parameters:
<Point> location Required The point at which to search for the closest address. The location should be in the same spatial reference as that of the geocode service.
<Number> distance Required The distance 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.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onLocationToAddressComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
See also:
onLocationToAddressComplete   onError  

Events Detail

onAddressToLocationsComplete(addressCandidates)

Fires when Locator.addressToLocation() has completed. The result is an array of AddressCandidate. This is the same signature returned if the optional callback is specified.
Arguments:
<AddressCandidate[]> addressCandidates Contains an array of candidates that match the given address as well as their scores.
See also:
addressToLocations  

onError(error)

Fires when an error occurs when executing the task. (As of v1.3)
Arguments:
<Error> error ArcGIS Server error message returned in a JavaScript error object.
See also:
addressToLocations   locationToAddress  

onLocationToAddressComplete(addressCandidate)

Fires when Locator.locationToAddress() has completed. The result is an AddressCandidate. This is the same signature returned if the optional callback is specified.
Arguments:
<AddressCandidate> addressCandidate Contains a candidate that best matches the input criteria as well as its score.
See also:
locationToAddress