Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/opsdashboard
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: Locator
[ AMD Module Require | Legacy Module Require ]
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
| Name | Summary |
|---|---|
| new Locator(url) | Creates a new Locator object. |
Properties
| Name | Type | Summary |
|---|---|---|
| countryCode | String | The country to limit results to for example "US" for United States or "SE" for Sweden. |
| outSpatialReference | SpatialReference | The spatial reference of the output geometries. |
| url | String | URL to the ArcGIS Server REST resource that represents a locator service. |
Methods
| Name | Return type | Summary |
|---|---|---|
| addressToLocations(params, callback?, errback?) | Deferred | Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter. |
| addressesToLocations(params, callback, errback) | Deferred | Find address candidates for multiple input addresses. |
| locationToAddress(location, distance, callback?, errback?) | Deferred | Locates an address based on a given point. |
| setOutSpatialReference(spatialReference) | None | Sets the well-known ID of the spatial reference of the output geometries. |
| suggestLocations(params) | Deferred | Get 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
| Name | Event Object | Summary |
|---|---|---|
| address-to-locations-complete | {
addresses: < | Fires when Locator.addressToLocation method has completed. |
| addresses-to-locations-complete | {
addresses: < | Fires when Locator.addressesToLocations method has completed. |
| error | {
error: < | Fires when an error occurs when executing the task. |
| location-to-address-complete | {
address: < | Fires when Locator.locationToAddress method has completed. |
| suggest-locations-complete | {
suggestions: < | Fires when the suggestLocations method has completed. |
Constructor Details
Creates a new Locator object.
Parameters:
< |
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
StringThe 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
SpatialReferenceThe 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
StringURL to the ArcGIS Server REST resource that represents a locator service. To obtain the URL, use Services Directory.
Method Details
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
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:
DeferredParameters:
< |
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. |
< |
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. |
< |
Optional | An error object is returned if an error occurs on the Server during task execution. (As of v1.3) |
Object Specifications:
<
params>< |
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. |
< |
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. |
< |
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. |
< |
Optional | Used in combination with "location" option to weight returned results within this distance (meters). |
< |
Optional | Allows the results of single geocode transactions to be persisted. |
< |
Optional | Used in combination with "distance" option to weight returned results for a specified area. (point) |
< |
Optional | A suggestLocations result ID (magicKey). Used to query for a specific results information. |
< |
Optional | Maximum results to return from the query. |
< |
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. |
< |
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);
See also: on("address-to-locations-complete"), on("error")
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:
DeferredParameters:
< |
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"
}
|
< |
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. |
< |
Required | The function to call if an error occurs on the server during task execution. |
Object Specifications:
<
params>< |
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"
} |
< |
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. |
< |
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);
See also: on("addresses-to-locations-complete")
Locates an address based on a given point.
Return type:
DeferredParameters:
< |
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. |
< |
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. |
< |
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. |
< |
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);
});
...
});
See also: on("error"), on("location-to-address-complete")
Sets the well-known ID of the spatial reference of the output geometries.
Parameters:
< |
Required | The well-known ID of a spatial reference.
{"wkid" : 4326}
|
Get character by character auto complete suggestions. See also the suggest-locations-complete event. (Added at v3.11)
Return type:
DeferredParameters:
< |
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>< |
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 |
< |
Required | Used with the location property. This property The distance property specifies the radial distance from the 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. |
< |
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 ]
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:
< |
Contains an array of candidates that match the input address. |
See also: addressToLocations()
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:
< |
Contains an array of candidates that match the input addresses. |
See also: addressesToLocations()
Fires when an error occurs when executing the task. (Added at v3.6)
Event Object Properties:
< |
ArcGIS Server error message returned in a JavaScript error object. |
See also: addressToLocations(), locationToAddress()
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:
< |
The address candidate that matches the input location. |
See also: locationToAddress()
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:
< |
An array of objects with text, magicKey and isCollection properties. Each object represents a result returned after calling the suggestLocations method. |