require(["esri/rest/locator"], (locator) => { /* code goes here */ });
import * as locator from "@arcgis/core/rest/locator.js";
esri/rest/locator
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
.
- See also
Method Overview
Name | Return Type | Summary | Object |
---|---|---|---|
Promise<AddressCandidate[]> | Sends a request to the ArcGIS REST geocode resource to find candidates for a single address specified in the address parameter. | locator | |
Promise<AddressCandidate[]> | Find address candidates for multiple input addresses. | locator | |
Promise<AddressCandidate> | Locates an address based on a given point. | locator | |
Promise<SuggestionResult[]> | Get character by character auto complete suggestions. | locator |
Method Details
-
addressToLocations
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.
Parametersurl StringURL to the ArcGIS Server REST resource that represents a locator service.
params ObjectSpecify at least the
address
and optionally other properties. See the object specifications table below.Specificationaddress ObjectThe 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.
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 StringoptionalLimit 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 BooleanoptionalAllows the results of single geocode transactions to be persisted.
location PointoptionalUsed to weight returned results for a specified area.
locationType StringoptionalDefine the type of location, either
"street"
or"rooftop"
, of the point returned from the World Geocoding Service.magicKey StringoptionalA
suggestLocations
result ID (magicKey). Used to query for a specific results information.maxLocations NumberoptionalMaximum 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.
outSpatialReference SpatialReferenceoptionalThe 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 ExtentoptionalDefines the extent within which the geocode server will search. Requires ArcGIS Server version 10.1 or greater.
requestOptions ObjectoptionalAdditional options to be used for the data request.
ReturnsType Description Promise<AddressCandidate[]> When resolved, returns an array of AddressCandidates. Each element of the array is a candidate that matches the input address.
-
addressesToLocations
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.
Parametersurl StringURL to the ArcGIS Server REST resource that represents a locator service.
params ObjectSee specifications below.
SpecificationThe 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 StringoptionalLimits the results to only search in the country provided. For example
US
for United States orSE
for Sweden. Only applies to the World Geocode Service. See the World Geocoding Service documentation for more information.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 StringoptionalDefine the type of location, either
"street"
or"rooftop"
, of the point returned from the World Geocoding Service.outSpatialReference SpatialReferenceoptionalThe 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 ObjectoptionalAdditional options to be used for the data request.
ReturnsType 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
locationToAddress(url, params, requestOptions){Promise<AddressCandidate>}
-
Locates an address based on a given point.
Parametersurl StringURL to the ArcGIS Server REST resource that represents a locator service.
params ObjectSpecify at least the
location
and optionally thelocationType
.Specificationlocation PointThe 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 StringoptionalDefine the type of location, either
"street"
or"rooftop"
, of the point returned from the World Geocoding Service.outSpatialReference SpatialReferenceoptionalThe 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 ObjectoptionalAdditional options to be used for the data request.
ReturnsType Description Promise<AddressCandidate> When resolved successfully, the result is an AddressCandidate.
-
suggestLocations
suggestLocations(url, params, requestOptions){Promise<SuggestionResult[]>}
-
Get character by character auto complete suggestions.
Parametersurl StringURL to the ArcGIS Server REST resource that represents a locator service.
params ObjectAn object that defines suggest parameters. See specifications below.
Specificationoptional 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 PointDefines a normalized location point that is used to sort geocoding candidates based upon their proximity to the given location.
text StringThe input text entered by a user which is used by the suggest operation to generate a list of possible matches.
requestOptions ObjectoptionalAdditional options to be used for the data request.
ReturnsType Description Promise<SuggestionResult[]> Resolves to an array of SuggestionResult objects.
Type Definitions
-
Describes the object representing the result of the suggestLocations() method.