Skip To Content ArcGIS for Developers Sign In Dashboard

LocatorTask Class

class Esri::ArcGISRuntime::LocatorTask

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

Header: #include <LocatorTask>
Since: Esri::ArcGISRuntime 100.0
Inherits: Esri::ArcGISRuntime::Object, Esri::ArcGISRuntime::Loadable, and Esri::ArcGISRuntime::RemoteResource

This class was introduced in Esri::ArcGISRuntime 100.0.

Public Functions

LocatorTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)
LocatorTask(const QUrl &url, QObject *parent = nullptr)
virtual ~LocatorTask() override
Esri::ArcGISRuntime::TaskWatcher geocode(const QString &searchText)
Esri::ArcGISRuntime::TaskWatcher geocodeWithParameters(const QString &searchText, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
Esri::ArcGISRuntime::TaskWatcher geocodeWithSearchValues(const QMap<QString, QString> &searchValues)
Esri::ArcGISRuntime::TaskWatcher geocodeWithSearchValuesAndParameters(const QMap<QString, QString> &searchValues, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
Esri::ArcGISRuntime::TaskWatcher geocodeWithSuggestResult(const Esri::ArcGISRuntime::SuggestResult &suggestResult)
Esri::ArcGISRuntime::TaskWatcher geocodeWithSuggestResultAndParameters(const Esri::ArcGISRuntime::SuggestResult &suggestResult, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
Esri::ArcGISRuntime::LocatorInfo locatorInfo() const
Esri::ArcGISRuntime::TaskWatcher reverseGeocode(const Esri::ArcGISRuntime::Point &location)
Esri::ArcGISRuntime::TaskWatcher reverseGeocodeWithParameters(const Esri::ArcGISRuntime::Point &location, const Esri::ArcGISRuntime::ReverseGeocodeParameters &parameters)
Esri::ArcGISRuntime::SuggestListModel *suggestions() const

Reimplemented Public Functions

virtual void cancelLoad() override
virtual Esri::ArcGISRuntime::Credential *credential() const override
virtual void load() override
virtual Esri::ArcGISRuntime::Error loadError() const override
virtual Esri::ArcGISRuntime::LoadStatus loadStatus() const override
virtual Esri::ArcGISRuntime::RequestConfiguration requestConfiguration() const override
virtual void retryLoad() override
virtual void setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration) override
virtual QUrl url() const override

Signals

void doneLoading(Esri::ArcGISRuntime::Error loadError)
void geocodeCompleted(QUuid taskId, const QList<Esri::ArcGISRuntime::GeocodeResult> &geocodeResults)
void loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

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.

// create the locator task
m_locatorTask = new LocatorTask(QUrl("http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer"), this);

// connect to the loadStatusChanged signal
connect(m_locatorTask, &LocatorTask::loadStatusChanged, this, [](LoadStatus loadStatus)
{
  if (loadStatus == LoadStatus::Loaded)
  {
    qDebug() << "Locator is ready to use";
  }
  else if (loadStatus == LoadStatus::FailedToLoad)
  {
    qDebug() << "Locator failed to load";
  }
});

// load the locator task
m_locatorTask->load();

See also Loadable and MobileMapPackage.

Member Function Documentation

LocatorTask::LocatorTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)

Constructor that takes a url to a secured online geocode service and a credential, with an optional parent.

LocatorTask::LocatorTask(const QUrl &url, QObject *parent = nullptr)

Constructor that takes a url to a local locator or online geocode service, with an optional parent.

[signal] void LocatorTask::doneLoading(Esri::ArcGISRuntime::Error loadError)

Signal emitted when this object is done loading.

  • loadError - The Error object.

Note: If there is a load error it will also be emitted on the errorOccurred signal.

See also Loadable and Object.

[signal] void LocatorTask::geocodeCompleted(QUuid taskId, const QList<Esri::ArcGISRuntime::GeocodeResult> &geocodeResults)

Signal emitted after any of the geocode asynchronous methods complete.

  • taskId - The task ID of the asynchronous task.
  • geocodeResults - The generated list of geocode results.

[signal] void LocatorTask::loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

Signal emitted when the load status changes for this object.

See also Loadable.

[override virtual] LocatorTask::~LocatorTask()

Destructor.

[override virtual] void LocatorTask::cancelLoad()

Reimplements: Loadable::cancelLoad().

See Loadable.

[override virtual] Esri::ArcGISRuntime::Credential *LocatorTask::credential() const

Reimplements: RemoteResource::credential() const.

Returns the security credential used to access the geocoding service.

Note: Only applicable if using an online service that is secured.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocode(const QString &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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocodeWithParameters(const QString &searchText, const Esri::ArcGISRuntime::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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocodeWithSearchValues(const QMap<QString, QString> &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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocodeWithSearchValuesAndParameters(const QMap<QString, QString> &searchValues, const Esri::ArcGISRuntime::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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocodeWithSuggestResult(const Esri::ArcGISRuntime::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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::geocodeWithSuggestResultAndParameters(const Esri::ArcGISRuntime::SuggestResult &suggestResult, const Esri::ArcGISRuntime::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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

[override virtual] void LocatorTask::load()

Reimplements: Loadable::load().

See Loadable.

[override virtual] Esri::ArcGISRuntime::Error LocatorTask::loadError() const

Reimplements: Loadable::loadError() const.

See Loadable.

[override virtual] Esri::ArcGISRuntime::LoadStatus LocatorTask::loadStatus() const

Reimplements: Loadable::loadStatus() const.

See Loadable.

Esri::ArcGISRuntime::LocatorInfo LocatorTask::locatorInfo() const

Returns information about the locator used in this task.

[override virtual] Esri::ArcGISRuntime::RequestConfiguration LocatorTask::requestConfiguration() const

Reimplements: RemoteResource::requestConfiguration() const.

Returns the RequestConfiguration in use by this task.

This function was introduced in Esri::ArcGISRuntime 100.1.

See also setRequestConfiguration().

[override virtual] void LocatorTask::retryLoad()

Reimplements: Loadable::retryLoad().

See Loadable.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::reverseGeocode(const Esri::ArcGISRuntime::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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

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.

Esri::ArcGISRuntime::TaskWatcher LocatorTask::reverseGeocodeWithParameters(const Esri::ArcGISRuntime::Point &location, const Esri::ArcGISRuntime::ReverseGeocodeParameters &parameters)

Reverse Geocodes an address with the given location and parameters.

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 geocodeCompleted signal emits when the operation is complete, giving access to the list of GeocodeResult.

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.

[override virtual] void LocatorTask::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration)

Reimplements: RemoteResource::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration).

Sets configuration parameters used for network requests sent by this task to requestConfiguration.

This function was introduced in Esri::ArcGISRuntime 100.1.

See also requestConfiguration().

Esri::ArcGISRuntime::SuggestListModel *LocatorTask::suggestions() const

Returns the SuggestListModel for this LocatorTask.

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. If suggestions are supported by the LocatorTask, suggestions can be automatically generated by calling SuggestListModel::setSearchText. 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.

[override virtual] QUrl LocatorTask::url() const

Reimplements: RemoteResource::url() const.

Returns the URL specified on the constructor.


Feedback on this topic?