LocatorTask Class

  • LocatorTask
  • class Esri::ArcGISRuntime::LocatorTask

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

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

    Public Functions

    LocatorTask(const QUrl &url, QObject *parent = nullptr)
    LocatorTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)
    virtual ~LocatorTask() override
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeAsync(const QString &searchText)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeWithParametersAsync(const QString &searchText, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeWithSearchValuesAndParametersAsync(const QMap<QString, QString> &searchValues, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeWithSearchValuesAsync(const QMap<QString, QString> &searchValues)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeWithSuggestResultAndParametersAsync(const Esri::ArcGISRuntime::SuggestResult &suggestResult, const Esri::ArcGISRuntime::GeocodeParameters &parameters)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> geocodeWithSuggestResultAsync(const Esri::ArcGISRuntime::SuggestResult &suggestResult)
    Esri::ArcGISRuntime::LocatorInfo locatorInfo() const
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> reverseGeocodeAsync(const Esri::ArcGISRuntime::Point &location)
    QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> reverseGeocodeWithParametersAsync(const Esri::ArcGISRuntime::Point &location, const Esri::ArcGISRuntime::ReverseGeocodeParameters &parameters)
    QFuture<QList<Esri::ArcGISRuntime::SuggestResult>> suggestAsync(const QString &searchText)
    QFuture<QList<Esri::ArcGISRuntime::SuggestResult>> suggestAsync(const QString &searchText, const Esri::ArcGISRuntime::SuggestParameters &parameters)
    Esri::ArcGISRuntime::SuggestListModel *suggestions() const

    Reimplemented Public Functions

    virtual QString apiKey() const override
    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 setApiKey(const QString &apiKey) override
    virtual void setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration) override
    virtual QUrl url() const override

    Signals

    void doneLoading(const Esri::ArcGISRuntime::Error &loadError)
    void geocodeCompleted(const 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
    LocatorTask* locatorTask = new LocatorTask(QUrl("http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer"), this);
    
    // connect to the loadStatusChanged signal
    connect(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
    locatorTask->load();

    See also Loadable and MobileMapPackage.

    Member Function Documentation

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

    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.

    [override virtual] LocatorTask::~LocatorTask()

    Destructor.

    [override virtual, since Esri::ArcGISRuntime 100.10] QString LocatorTask::apiKey() const

    Reimplements: ApiKeyResource::apiKey() const.

    Returns the API key. See ApiKeyResource.

    This function was introduced in Esri::ArcGISRuntime 100.10.

    See also setApiKey().

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

    [signal] void LocatorTask::doneLoading(const 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.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeAsync(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).

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [signal] void LocatorTask::geocodeCompleted(const 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.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeWithParametersAsync(const QString &searchText, const Esri::ArcGISRuntime::GeocodeParameters &parameters)

    Geocodes address with parameters and returns candidates.

    • searchText - Address inputs.
    • parameters - Geocode method parameters.

    Executes a geocoding operation to find location candidates for a given address.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeWithSearchValuesAndParametersAsync(const QMap<QString, QString> &searchValues, const Esri::ArcGISRuntime::GeocodeParameters &parameters)

    Geocodes multiline address with parameters and returns candidates.

    • searchValues - Multiline address inputs.
    • parameters - Geocode method parameters.

    Executes a geocoding operation to find location candidates for a given multiline address.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeWithSearchValuesAsync(const QMap<QString, QString> &searchValues)

    Geocodes multiline address and returns candidates.

    • searchValues - Multiline address inputs.

    Executes a geocoding operation to find location candidates for a given multiline address.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeWithSuggestResultAndParametersAsync(const Esri::ArcGISRuntime::SuggestResult &suggestResult, const Esri::ArcGISRuntime::GeocodeParameters &parameters)

    Geocodes suggest with parameters and returns candidates.

    • suggestResult - Suggest method result.
    • parameters - Geocode parameters.

    Executes geocoding based on result of suggestion.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::geocodeWithSuggestResultAsync(const Esri::ArcGISRuntime::SuggestResult &suggestResult)

    Geocodes suggest and returns candidates.

    • suggestResult - Suggest method result.

    Executes geocoding based on result of suggestion.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

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

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

    Signal emitted when the load status changes for this object.

    See also Loadable.

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

    Returns information about the locator used in this task.

    [override virtual, since Esri::ArcGISRuntime 100.1] 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.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::reverseGeocodeAsync(const Esri::ArcGISRuntime::Point &location)

    Finds address by location point.

    • location - The location point.

    Executes a reverse-geocoding operation to find address candidates for a given location.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::GeocodeResult>> LocatorTask::reverseGeocodeWithParametersAsync(const Esri::ArcGISRuntime::Point &location, const Esri::ArcGISRuntime::ReverseGeocodeParameters &parameters)

    Finds address with parameters by location point.

    • location - The location point.
    • parameters - The reverse geocode parameters.

    Executes a reverse-geocoding operation to find address candidates for a given location.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [override virtual, since Esri::ArcGISRuntime 100.10] void LocatorTask::setApiKey(const QString &apiKey)

    Reimplements: ApiKeyResource::setApiKey(const QString &apiKey).

    Sets the API key to apiKey. See ApiKeyResource.

    This function was introduced in Esri::ArcGISRuntime 100.10.

    See also apiKey().

    [override virtual, since Esri::ArcGISRuntime 100.1] 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().

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::SuggestResult>> LocatorTask::suggestAsync(const QString &searchText)

    Suggest address and returns possible variants.

    • searchText - Part of address text.

    Geocoding suggestions provide a mechanism for implementing character-by-character auto-complete. Using a text input and optional SuggestParameters, suggested addresses can be quickly found and presented to the user. Suggestions are not limited to addresses, they can also be used for POIs (Points of Interest). To return a focused set of suggestions, set the SuggestParameters::preferredSearchLocation or the SuggestParameters::searchArea. Using the SuggestParameters::preferredSearchLocation is similar to how ArcGIS Pro limits the suggestions returned.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::SuggestResult>> LocatorTask::suggestAsync(const QString &searchText, const Esri::ArcGISRuntime::SuggestParameters &parameters)

    Suggest address with parameters and returns possible variants.

    • searchText - Part of address text.
    • parameters - Suggest method parameters.

    Geocoding suggestions provide a mechanism for implementing character-by-character auto-complete. Using a text input and optional SuggestParameters, suggested addresses can be quickly found and presented to the user. Suggestions are not limited to addresses, they can also be used for POIs (Points of Interest). To return a focused set of suggestions, set the SuggestParameters::preferredSearchLocation or the SuggestParameters::searchArea. Using the SuggestParameters::preferredSearchLocation is similar to how ArcGIS Pro limits the suggestions returned.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    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.

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