require(["esri/tasks/Locator"], function(Locator) { /* code goes here */ });
Class: esri/tasks/Locator
Inheritance: Locator Task Accessor
Since: ArcGIS API for JavaScript 4.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 generate batch results for a set of addresses.

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.

See also:

Constructors

new Locator(properties)

Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
String[]

Limit the results to one or more categories.

more details
more detailsLocator
String

Limits the results to only search in the country provided.

more details
more detailsLocator
String

The name of the class.

more details
more detailsAccessor
SpatialReference

The spatial reference of the output geometries.

more details
more detailsLocator
Object

The options to be used for data requests.

more details
more detailsTask
String

URL to the ArcGIS Server REST resource that represents a locator service.

more details
more detailsLocator

Property Details

categoriesString[]

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.

countryCodeString

Limits the results to only search in the country provided. For example US for United States or SE for Sweden. Only applies to the World Geocode Service. See the World Geocoding Service documentation for more information.

declaredClassStringreadonly inherited

The name of the class. The declared class name is formatted as esri.folder.className.

outSpatialReferenceSpatialReference

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.

requestOptionsObject inherited

The options to be used for data requests. These options can also be controlled through the requestOptions method parameter.

URL to the ArcGIS Server REST resource that represents a locator service.

Method Overview

NameReturn TypeSummaryClass
Promise<AddressCandidate[]>

Find address candidates for multiple input addresses.

more details
more detailsLocator
Promise<AddressCandidate[]>

Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter.

more details
more detailsLocator
Promise<AddressCandidate>

Locates an address based on a given point.

more details
more detailsLocator
Promise<SuggestionResult>

Get character by character auto complete suggestions.

more details
more detailsLocator

Method Details

addressesToLocations(params, requestOptions){Promise<AddressCandidate[]>}

Find address candidates for multiple input addresses. This method requires an ArcGIS Server 10.1 or greater geocode service.

Parameters:
params Object

See specifications below.

Specification:
addresses Object[]

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"
}
countryCode String

Limits the results to only search in the country provided. For example US for United States or SE for Sweden. Only applies to the World Geocode Service. See the World Geocoding Service documentation for more information.

categories String[]

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.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
TypeDescription
Promise< AddressCandidate[]>When resolved, the result is an array of AddressCandidates[]. Each element of the array is a candidate that matches the input address.

addressToLocations(params, requestOptions){Promise<AddressCandidate[]>}

Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter.

Parameters:
params Object

Specify at least the address and optionally other properties. See the object specifications table below.

Specification:
address Object

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: "1234 W Main St",
  City: "Small Town",
  State: "WA",
  Zone: "99027"
}

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.

categories String[]

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.

countryCode String

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.

distance Number

Used in combination with location option to weight returned results within this distance (meters).

forStorage Boolean

Allows the results of single geocode transactions to be persisted.

location Point

Used in combination with distance option to weight returned results for a specified area.

magicKey String

A suggestLocations result ID (magicKey). Used to query for a specific results information.

maxLocations Number

Maximum results to return from the query.

outFields String[]

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.

searchExtent Extent

Defines the extent within which the geocode server will search. Requires ArcGIS Server version 10.1 or greater.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
TypeDescription
Promise< AddressCandidate[]>When resolved, returns an array of AddressCandidates[]. Each element of the array is a candidate that matches the input address.

locationToAddress(location, distance, requestOptions){Promise<AddressCandidate>}

Locates an address based on a given point.

Parameters:
location Point

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.

distance Number
optional

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.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
TypeDescription
Promise< AddressCandidate>When resolved successfully, the result is an AddressCandidate.

suggestLocations(params, requestOptions){Promise<SuggestionResult>}

Get character by character auto complete suggestions.

Parameters:
params Object

An object that defines suggest parameters. See specifications below.

Specification:
categories String[]

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 values.

distance Number

Used with the location property. The distance property specifies the radial distance from the location.

location Point

Defines a normalized location point that is used with the distance parameter to sort geocoding candidates based upon their proximity to the given location.

text String

The input text entered by a user which is used by the suggest operation to generate a list of possible matches.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
TypeDescription
Promise< SuggestionResult>Resolves to an array of SuggestionResult objects.

Type Definitions

SuggestionResult

Describes the object representing the result of the suggestLocations() method.

Properties:
isCollection Boolean

Indicates if the result is a Collection.

magicKey String

ID used in combination with the text property to uniquely identify a suggestion.

text String

The string name of the suggested location to geocode.

API Reference search results

NameTypeModule

There were no match results from your search criteria.