Skip To Content ArcGIS for Developers Sign In Dashboard

LocatorTask QML Type

A task for Geocoding and Reverse Geocoding that supports both online and offline capabilities. More...

Import Statement: import Esri.ArcGISRuntime 100.6
Since: Esri.ArcGISRuntime 100.0
Inherits:

Object

Properties

Signals

Methods

Detailed Description

Geocoding takes an address or place name, and converts it into real-world coordinates. For example, "380 New York St, Redlands, CA", "Yosemite National Park", or "Utility Pole 527" all represent a location on the Earth, but must first be geocoded to convert their written description or address to a set of real-world coordinates that can be placed on a map. Reverse Geocoding is similar to Geocoding, only instead of finding the coordinates associated with a particular address or place name, it finds the closest address or place name from given map coordinates. For example, a user could click on a map of New York City, and get the address of the coordinates from that click.

An Address Locator is required to geocode with a LocatorTask. If working in an online connected scenario, the locator can be published to ArcGIS Server, as an online geocoding service. Esri also provides ready-to-use services, such as the World Geocoding Service, which requires authentication with an ArcGIS organizational account. If working in a disconnected scenario, the locator can be exported as a Runtime-enabled address locator from either ArcMap or ArcGIS Pro. If you are using ArcMap, run the Create Runtime Content geoprocessing tool, and reference a map document that contains the address locator you want to export. This will output a folder containing several files, including a *.loc, *.lox, *.loc.xml, and *.locb. Create the locator task by passing a URL to the location of the *.loc file. If you are using ArcGIS Pro, run the Create Mobile Map Package geoprocessing tool, and select the map and locator that you wish to export. This will output a mobile map package (*.mmpk), which will contain the LocatorTask.

A LocatorTask is executed asynchronously. A successful execution returns a list of GeocodeResult with details about the matched records. The LocatorTask also supports Suggestions, which allow the developer to show auto-generated suggestions from the locator, based on what the user has typed in a search box.

This QML type supports the following default properties. A default property may be declared inside another declared object without being assigned explicitly to a property.

TypeDefault Property
Credentialcredential
RequestConfigurationrequestConfiguration (since Esri.ArcGISRuntime 100.1)

See also Cancelable, Loadable, RemoteResource, and MobileMapPackage.

Property Documentation

[default] credential : Credential

The credential to be used for a secured online geocoding service.


error : Error

Returns the error object (read-only).

See also Loadable and Error.


geocodeResults : list<GeocodeResult>

Returns a list of results from a geocoding operation (read-only).

These results contain geometry and attributes returned from the service, and could either be displayed in a GraphicsOverlay, or stored for future use.

Obtain the results once the geocodeStatusChanged signal emits, and the geocodeStatus is complete.


geocodeStatus : Enums.TaskStatus

Returns the status of the geocode asynchronous operation (read-only).

Check this status when the geocodeStatusChanged signal emits, to determine if the geocode is complete, in progress, or has errored.

See also Enums.TaskStatus.


loadError : Error

Returns the load error (read-only).

Note: load errors are also reported on the error property and emit the errorChanged signal.

See also Loadable.


loadStatus : Enums.LoadStatus

Returns the load status (read-only).

See also Loadable and Enums.LoadStatus.


locatorInfo : LocatorInfo

Returns information about the locator used in this task (read-only).


[default] requestConfiguration : RequestConfiguration

The configuration parameters used for network requests sent by this task.

This QML property was introduced in Esri.ArcGISRuntime 100.1.


suggestions : SuggestListModel

Returns the SuggestListModel for this LocatorTask (read-only).

Use LocatorTask::locatorInfo to determine if suggestions are supported by the locator. If so, suggestions can be used to provide a nice user experience where potential results are shown to the user while typing. If suggestions are supported by the LocatorTask, suggestions can be automatically generated by setting SuggestListModel::searchText. This list model can then be applied to a view to show suggested addresses or place names. See the SuggestListModel API documentation for further details.


url : url

The URL to a local address locator or an online geocoding service.


Signal Documentation

credentialChanged()

Emitted when the credential property of this LocatorTask changes.


geocodeStatusChanged()

Emitted when the geocodeStatus property of this LocatorTask changes.


loadErrorChanged()

Emitted when the loadError property of this LocatorTask changes.

Note: load errors are also reported on the error property and emit the errorChanged signal.

See also Loadable and Object.


loadStatusChanged()

Emitted when the loadStatus property of this LocatorTask changes.

See also Loadable.


locatorInfoChanged()

Emitted when the locatorInfo property of this LocatorTask changes.


requestConfigurationChanged()

Emitted when the requestConfiguration property changes.

This QML signal was introduced in Esri.ArcGISRuntime 100.1.


suggestionsChanged()

Emitted when the suggestions property of this LocatorTask changes.


urlChanged()

Emitted when the url property of this LocatorTask changes.


Method Documentation

void cancelLoad()

See also Loadable.


bool cancelTask(string taskId)

See also Cancelable.


string geocode(string searchText)

Geocodes an address with the given searchText.

Use the LocatorTask::locatorInfo to determine the types of search text supported by the locator. Potential searches could be an address (380 New York St.), a point of interest (Starbucks), or an intersection (Redlands Blvd and Tennessee St).

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


string geocodeWithParameters(string searchText, GeocodeParameters parameters)

Geocodes an address with the given searchText and parameters.

Use the LocatorTask::locatorInfo to determine the types of search text supported by the locator. Potential searches could be an address (380 New York St.), a point of interest (Starbucks), or an intersection (Redlands Blvd and Tennessee St). The parameters allow you to set preferences, such as maximum number of results or search location.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


string geocodeWithSearchValues(jsobject searchValues)

Geocodes an address with the given searchValues.

Use the LocatorTask::locatorInfo to determine the types of search text supported by the locator. SearchValues are key-value pairs, where the key is an attribute name, and the value is the value you are searching for in that field. Check LocatorInfo::searchAttributes for the search attributes available in the locator.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


string geocodeWithSearchValuesAndParameters(jsobject searchValues, GeocodeParameters parameters)

Geocodes an address with the given searchValues and parameters.

Use the LocatorTask::locatorInfo to determine the types of search text supported by the locator. SearchValues are key-value pairs, where the key is an attribute name, and the value is the value you are searching for in that field. Check LocatorInfo::searchAttributes for the search attributes available in the locator. The parameters allow you to set preferences, such as maximum number of results or search location.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


string geocodeWithSuggestResult(SuggestResult suggestResult)

Geocodes an address with the given suggestResult.

Use the LocatorTask::locatorInfo to determine if suggestions are supported by the locator. If so, suggestions can be used to provide a nice user experience where potential results are shown to the user while typing. A SuggestResult can be selected by a user, and directly passed into this function to perform a geocode.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


string geocodeWithSuggestResultAndParameters(SuggestResult suggestResult, GeocodeParameters parameters)

Geocodes an address with the given suggestResult and parameters.

Use the LocatorTask::locatorInfo to determine if suggestions are supported by the locator. If so, suggestions can be used to provide a nice user experience where potential results are shown to the user while typing. A SuggestResult can be selected by a user, and directly passed into this function to perform a geocode. The parameters allow you to set preferences, such as maximum number of results or search location.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.


void load()

See also Loadable.


void retryLoad()

See also Loadable.


string reverseGeocode(Point location)

Reverse Geocodes an address with the given location.

A common use case for this function is to create a Point from a mouse click on a map or from some other source, and use this function to obtain the nearest address to the location.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.

Note: The input point can be in any spatial reference. If the provided point does not have a spatial reference set on it, the locator task will assume it is in the spatial reference of the locator.


string reverseGeocodeWithParameters(Point location, ReverseGeocodeParameters parameters)

Reverse Geocodes an address with the given location.

A common use case for this function is to create a Point from a mouse click on a map or from some other source, and use this function to obtain the nearest address to the location. The parameters allow you to set preferences, such as maximum number of results or maximum search distance.

The geocodeStatusChanged signal emits when the operation is complete. Check the geocodeStatus to make sure the operation completed successfully. The results are then available through geocodeResults.

Note: The input point can be in any spatial reference. If the provided point does not have a spatial reference set on it, the locator task will assume it is in the spatial reference of the locator.



Feedback on this topic?