Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Locator

require(["esri/tasks/locator"], function(Locator) { /* code goes here */ });

Description

(Added at v1.0)
Represents a geocode service resource exposed by the ArcGIS Server REST API. It is used to generate candidates for an address. It is also used to find an address for a given location. At ArcGIS Server 10.1 and higher it can be used to generate result locations for a set of addresses (batch geocoding).

Set the URL to the ArcGIS Server REST resource that represents a Locator service, for example: http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer. View the Overview of the World Geocoding Service help for more details on the World Geocoder.

Samples

Search for samples that use this class.

Constructors

NameSummary
new Locator(url)Creates a new Locator object.

Properties

NameTypeSummary
countryCodeStringThe country to limit results to for example "US" for United States or "SE" for Sweden.
outSpatialReferenceSpatialReferenceThe spatial reference of the output geometries.
urlStringURL to the ArcGIS Server REST resource that represents a locator service.

Methods

NameReturn typeSummary
addressToLocations(params, callback?, errback?)DeferredSends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter.
addressesToLocations(params, callback, errback)DeferredFind address candidates for multiple input addresses.
locationToAddress(location, distance, callback?, errback?)DeferredLocates an address based on a given point.
setOutSpatialReference(spatialReference)NoneSets the well-known ID of the spatial reference of the output geometries.
suggestLocations(params)DeferredGet character by character auto complete suggestions.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
address-to-locations-complete
{
  addresses: <AddressCandidate[]>
}
Fires when Locator.addressToLocation method has completed.
addresses-to-locations-complete
{
  addresses: <AddressCandidate[]>
}
Fires when Locator.addressesToLocations method has completed.
error
{
  error: <Error>
}
Fires when an error occurs when executing the task.
location-to-address-complete
{
  address: <AddressCandidate>
}
Fires when Locator.locationToAddress method has completed.
suggest-locations-complete
{
  suggestions: <Object[]>
}
Fires when the suggestLocations method has completed.
Constructor Details

new 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.
Sample:
require([
  "esri/tasks/locator", ... 
], function(Locator, ... ) {
  var locator = new Locator("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Locators/ESRI_Geocode_USA/GeocodeServer");
  ...
});
Property Details

<String> countryCode

The country to limit results to for example "US" for United States or "SE" for Sweden. Only applies to the World Geocode Service. See Geocode coverage (World Geocoding Service) for more information. (Added at v3.11)

<SpatialReference> outSpatialReference

The spatial reference of the output geometries. If not specified, the output geometries are in the spatial reference of the input geometries when performing a reverse geocode and in the default spatial reference returned by the service if finding locations by address.

If processSpatialReference is specified and outSpatialReference is not specified, the output geometries are in the spatial reference of the process spatial reference.

See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<String> url

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

addressToLocations(params, callback?, errback?)

Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter. On completion, the address-to-locations-complete event is fired.

At version 2.6 the method signature was updated to accept a params object. The old signature addressToLocations(address,outFields?,callback?,errback?) will still work.
Return type: Deferred
Parameters:
<Object> params Required Specify at least the address and optionally other properties. The searchExtent parameter requires a locator published with ArcGIS Server 10.1 or greater. See the object specifications table below for the structure of the params object.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the address-to-locations-complete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Object Specifications:
<params>
<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>"
}
Locators published using ArcGIS 10 or later support a single line address field which can be specified using the following syntax where field_name is the name of the single line address field. You can find this name by viewing the help or services directory for your locator services. Common values are SingleLine and SingleLineFieldName:
var address = {
  "field_name": "380 New York St, Redlands, CA 92373"
};
The Services Directory can be used to find out the required and optional address fields and the correct names for the input name fields. If you are using the World Geocoding Service visit the ArcGIS Online Geocoding Service help for more details on the World Geocoder.
<String[]> categories Optional Limit result to one or more categories, for example "Populated Place" or "Scandinavian Food". Only applies to the World Geocode Service. See Category filtering (World Geocoding Service) for more information.
<String> countryCode Optional Limit result to a specific country, for example "US" for United States or "SE" for Sweden. Only applies to the World Geocode Service. See Geocode coverage (World Geocoding Service) for more information.
<Number> distance Optional Used in combination with "location" option to weight returned results within this distance (meters).
<Boolean> forStorage Optional Allows the results of single geocode transactions to be persisted.
<Point> location Optional Used in combination with "distance" option to weight returned results for a specified area. (point)
<String> magicKey Optional A suggestLocations result ID (magicKey). Used to query for a specific results information.
<Number> maxLocations Optional Maximum results to return from the query.
<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.
<Extent> searchExtent Optional Defines the extent within which the geocode server will search. Requires ArcGIS Server version 10.1 or greater.
Sample:
var address = {"Single Line Input": "100 main street"};
var params = {address: address, searchExtent: map.extent};		
locator.outSpatialReference= map.spatialReference;
locator.addressToLocations(params);

addressesToLocations(params, callback, errback)

Find address candidates for multiple input addresses. This method requires an ArcGIS Server 10.1 or greater geocode service. (Added at v3.0)
Return type: Deferred
Parameters:
<Object> params Required The input addresses in the format supported by the geocoding service. If the service supports 'Single Line Input' the input addresses will be in the following format:
    {
    "OBJECTID": 0,
    "Single Line Input":"440 Arguello Blvd, 94118"
    }
  
<Function> callback Required The function to call when the method has completed. The arguments in the function are the same as the addresses-to-locations-complete event.
<Function> errback Required The function to call if an error occurs on the server during task execution.
Object Specifications:
<params>
<Object[]> addresses Optional The input addresses in the format supported by the geocode service. If the service supports 'Single Line Input' the input addresses will be in the following format:
{
  "OBJECTID": 0,
  "Single Line Input": "440 Arguello Blvd, 94118"
}
<String[]> categories Optional Limit the results to one or more categories. For example "Populated Place" or "airport". Only applicable when using the World Geocode Service. View the World Geocoding Service documentation for more information.
<String> countryCode Optional The country to limit results to for example "US" for United States or "SE" for Sweden. Only applies to the World Geocode Service. See Geocode coverage (World Geocoding Service) for more information.
Sample:
var addresses = [{
  "OBJECTID": 0,
  "STREET": "440 Arguello Blvd",
  "ZONE": "94118"
}, {
  "OBJECTID": 1,
  "STREET": "100 Arguello Blvd",
  "ZONE": "94118"
}];

locator.outSpatialReference = map.spatialReference;

var options = {
  addresses: addresses
}

locator.addressesToLocations(options);

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

Locates an address based on a given point.
Return type: Deferred
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 location-to-address-complete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Sample:
require([
  "esri/_base/connect", ... 
], function(connect, ... ) {
  connect.connect(map, "onClick", function(evt) {
    locator.locationToAddress(evt.mapPoint, 100);
  });
  ...
});

setOutSpatialReference(spatialReference)

Sets the well-known ID of the spatial reference of the output geometries.
Parameters:
<SpatialReference> spatialReference Required The well-known ID of a spatial reference.
{"wkid" : 4326} 

suggestLocations(params)

Get character by character auto complete suggestions. See also the suggest-locations-complete event. (Added at v3.11)
Return type: Deferred
Parameters:
<Object> params Required An object that defines suggest parameters. Additional information regarding working with suggest parameters can be found here. See the object specifications table below for the structure of the params object.
Object Specifications:
<params>
<String[]> categories Required A place or address type which can be used to filter suggest results. The parameter supports input of single category values or multiple comma-separated value
<Number> distance Required Used with the location property. This property The distance property specifies the radial distance from the location.
<Point> location Optional Defines a normalized location point that is used with the distance parameter to sort geocoding candidates based upon their proximity to the given location.
<String> text Required The input text entered by a user which is used by the suggest operation to generate a list of possible matches.
Sample:
 
{ text: "redlands",
  categories: ["airports"],
  location: map.extent.getCenter().normalize(),
  distance:1000
};		
locator.suggestLocations(params).then(function(suggestions){
   console.log(suggestions); //an array of suggestion objects.
});
Event Details
[ On Style Events | Connect Style Event ]

address-to-locations-complete

Fires when Locator.addressToLocation method has completed. The result is an object with an addresses property containing an array of AddressCandidate. This is the same signature returned if the optional callback is specified. Should be used in favor of onAddressToLocationsComplete (Added at v3.5)
Event Object Properties:
<AddressCandidate[]> addresses Contains an array of candidates that match the input address.

addresses-to-locations-complete

Fires when Locator.addressesToLocations method has completed. The result is an object with an addresses property containing an array of AddressCandidate. This is the same signature returned if the optional callback is specified. Should be used in favor of onAddressesToLocationsComplete (Added at v3.5)
Event Object Properties:
<AddressCandidate[]> addresses Contains an array of candidates that match the input addresses.

error

Fires when an error occurs when executing the task. (Added at v3.6)
Event Object Properties:
<Error> error ArcGIS Server error message returned in a JavaScript error object.

location-to-address-complete

Fires when Locator.locationToAddress method has completed. The result is an object with an address property with the resulting AddressCandidate. This is the same signature returned if the optional callback is specified. Should be used in favor of onLocationToAddressComplete (Added at v3.5)
Event Object Properties:
<AddressCandidate> address The address candidate that matches the input location.

suggest-locations-complete

Fires when the suggestLocations method has completed. The result is an object with a suggestions property containing an array of candidates with text, magicKey and isCollection properties.

View the World Geocoding Service documentation for more details.

(Added at v3.11)
Event Object Properties:
<Object[]> suggestions An array of objects with text, magicKey and isCollection properties. Each object represents a result returned after calling the suggestLocations method.