locator

AMD: require(["esri/rest/locator"], (locator) => { /* code goes here */ });
ESM: import * as locator from "@arcgis/core/rest/locator.js";
Object: esri/rest/locator
Since: ArcGIS Maps SDK for JavaScript 4.19

A convenience module for importing locator functions when developing with TypeScript. For example, rather than importing functions one at a time like this:

import { addressToLocations } from "esri/rest/locator/addressToLocations";
import { locationToAddress } from "esri/rest/locator/locationToAddress";

You can use this module to import them on a single line:

import { addressToLocations, locationToAddress } from "esri/rest/locator";

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: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer.

Method Overview

Name Return Type Summary Object

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

locator

Find address candidates for multiple input addresses.

locator

Locates an address based on a given point.

locator

Get character by character auto complete suggestions.

locator

Method Details

addressToLocations

Method
addressToLocations(url, 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
url String

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

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:

let 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[]
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.

countryCode String
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.

forStorage Boolean
optional

Allows the results of single geocode transactions to be persisted.

location Point
optional

Used to weight returned results for a specified area.

locationType String
optional

Define the type of location, either "street" or "rooftop", of the point returned from the World Geocoding Service.

magicKey String
optional

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

maxLocations Number
optional

Maximum results to return from the query.

outFields String[]
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.

outSpatialReference SpatialReference
optional

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.

searchExtent Extent
optional

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.

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

addressesToLocations

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

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

Parameters
url String

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

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":"77 Main St, Plymouth, NH 03264"
}
countryCode String
optional

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[]
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.

locationType String
optional

Define the type of location, either "street" or "rooftop", of the point returned from the World Geocoding Service.

outSpatialReference SpatialReference
optional

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.

requestOptions Object
optional

Additional options to be used for the data request.

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

locationToAddress

Method
locationToAddress(url, params, requestOptions){Promise<AddressCandidate>}

Locates an address based on a given point.

Parameters
url String

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

params Object

Specify at least the location and optionally the locationType.

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

locationType String
optional

Define the type of location, either "street" or "rooftop", of the point returned from the World Geocoding Service.

outSpatialReference SpatialReference
optional

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.

requestOptions Object
optional

Additional options to be used for the data request.

Returns
Type Description
Promise<AddressCandidate> When resolved successfully, the result is an AddressCandidate.

suggestLocations

Method
suggestLocations(url, params, requestOptions){Promise<SuggestionResult[]>}

Get character by character auto complete suggestions.

Parameters
url String

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

params Object

An object that defines suggest parameters. See specifications below.

Specification
categories String[]
optional

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.

location Point

Defines a normalized location point that is used 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.

Returns
Type Description
Promise<SuggestionResult[]> Resolves to an array of SuggestionResult objects.

Type Definitions

SuggestionResult

Type Definition
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.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.