ArcGIS Runtime SDK for Qt C++ API: EsriRuntimeQt::Locator Class Reference
ArcGIS Runtime SDK for Qt C++ API  10.2.6
EsriRuntimeQt::Locator Class Reference

#include <Locator.h>

Inheritance diagram for EsriRuntimeQt::Locator:
EsriRuntimeQt::Object EsriRuntimeQt::LocalLocator EsriRuntimeQt::ServiceLocator

Public Member Functions

 Locator (QObject *parent=nullptr)
 
virtual ~Locator ()
 
virtual LocatorServiceInfo locatorServiceInfo () const
 
void geocode (const QMap< QString, QString > &addressFields, const QStringList &outFields, const SpatialReference &outSR=SpatialReference())
 
virtual QList< LocatorGeocodeResult * > geocodeAndWait (const QMap< QString, QString > &addressFields, const QStringList &outFields, const SpatialReference &outSR=SpatialReference()) const
 
void batchGeocode (const QList< QMap< QString, QString > > &addresses, const SpatialReference &outSR=SpatialReference())
 
virtual BatchGeocodeResultbatchGeocodeAndWait (const QList< QMap< QString, QString > > &addresses, const SpatialReference &outSR=SpatialReference()) const
 
void find (const LocatorFindParameters &findParams)
 
virtual QList< LocatorGeocodeResult * > findAndWait (const LocatorFindParameters &findParams) const
 
void reverseGeocode (const Point &point, const double &distance, const SpatialReference &outSR=SpatialReference())
 
virtual LocatorReverseGeocodeResultreverseGeocodeAndWait (const Point &point, const double &distance, const SpatialReference &outSR=SpatialReference()) const
 
- Public Member Functions inherited from EsriRuntimeQt::Object
 Object (QObject *parent=nullptr)
 
 ~Object ()
 

Signals

void batchGeocodeComplete (EsriRuntimeQt::BatchGeocodeResult *result)
 
void batchGeocodeError (const EsriRuntimeQt::ServiceError &error)
 
void findComplete (const QList< EsriRuntimeQt::LocatorGeocodeResult * > &result)
 
void findError (const EsriRuntimeQt::ServiceError &error)
 
void geocodeComplete (const QList< EsriRuntimeQt::LocatorGeocodeResult * > &results)
 
void geocodeError (const QString &message, const EsriRuntimeQt::ServiceError &error)
 
void geocodeError (const EsriRuntimeQt::ServiceError &error)
 
void reverseGeocodeComplete (EsriRuntimeQt::LocatorReverseGeocodeResult *result)
 
void reverseGeocodeError (const EsriRuntimeQt::ServiceError &error)
 

Detailed Description

Base class for creating and using online and offline geocoders.

Geocoding means finding a geographic location that matches a given address. Reverse geocoding is the opposite, which means finding the address at a given location.

You can perform four types of geocoding operations with a Locator object. Each operation has a synchronous and asynchronous variant. The asynchronous methods are:

  • geocode()– Performs geocoding using one address, expressed as a QMap of address fields and values.
  • batchGeocode()– Similar to geocode(), except it geocodes multiple addresses in one operation.
  • find()– Performs geocoding using a LocatorFindParameters object. This operation can find locations using place names or points of interest in addition to addresses.
  • reverseGeocode()– Performs reverse geocoding, finding the address at a location.

The names of the synchronous variants of these methods end with AndWait, such as geocodeAndWait(). The asynchronous methods are appropriate for most situations. You receive the results from the asynchronous methods in a slot connected to a corresponding signal. Because your application does not wait for the response, it can remain responsive to user input during the operation. For situations where the latency time between your application and service is small and when the processing time should be small, it can be appropriate to use a synchronous operation. This is not a typical situation when communicating with services.

Geocoding can be done in two ways:

  • Using a geocoding service, a local service running in the local server or a online service provided by an ArcGIS server.
  • Using a local file-based locator without a service.

Geocoding with a service

Geocoding services may be offline or online. Both use a ServiceLocator to pass requests to either type of geocoding service.

Service geocoding can be performed using a ServiceLocator created with a URL of a geocoding service, and user credentials if required. After creating the ServiceLocator, call the methods for the operation you want to perform.

For offline geocoding with the local server, create and start a LocalGeocodeService. After the service starts, create an ServiceLocator instance using the URL of the local geocode service. Obtain the URL with LocalGeocodeService::urlGeocodeService().

The geocodeError(const EsriRuntimeQt::ServiceError&) signal emits if there is a service error when performing a geocode operation.

Geocoding with locator files

Local geocoding is performed without a service using a LocalLocator. The LocalLocator directly reads locator files stored on your device. Construct a LocalLocator by providing the path to the locator files. When creating the LocalLocator you can provide a LocatorSettings containing options for managing memory consumption and performance for geocoding.

Definition at line 103 of file Locator.h.

Constructor & Destructor Documentation

EsriRuntimeQt::Locator::Locator ( QObject *  parent = nullptr)
explicit

Default constructor. Constructs an empty Locator.

Parameters
[in]parentThe parent object (optional).
virtual EsriRuntimeQt::Locator::~Locator ( )
virtual

Destructor.

Member Function Documentation

void EsriRuntimeQt::Locator::batchGeocode ( const QList< QMap< QString, QString > > &  addresses,
const SpatialReference outSR = SpatialReference() 
)

Asynchronously finds location candidates for multiple addresses.

This method is similar to batchGeocodeAndWait() except that this method performs geocoding asynchronously.

The batchGeocodeComplete(EsriRuntimeQt::BatchGeocodeResult*) signal emits when the geocode operation completes, containing the results of the batch geocoding operation.

Parameters
[in]addressesThe list of addresses to find matches for; each address is a QMap of address fields.
[in]outSRThe spatial reference of the location candidates (optional).
Note
Use deleteLater() to delete the BatchGeocodeResult object returned in the batchGeocodeComplete signal.
virtual BatchGeocodeResult* EsriRuntimeQt::Locator::batchGeocodeAndWait ( const QList< QMap< QString, QString > > &  addresses,
const SpatialReference outSR = SpatialReference() 
) const
virtual

Synchronously finds location candidates for multiple addresses.

Results can be matched to input using the ResultID attribute in the results. This attribute matches the index for the address. For example, if three addresses are supplied, the matches have result IDs of 0, 1, and 2. If the supplied addresses have an "OBJECTID" attribute, the result IDs reference that attribute.

Parameters
[in]addressesThe list of addresses to find matches for. Each address is a QMap of address fields and their corresponding values.
[in]outSRThe spatial reference of the location candidates (optional).
Returns
The result of the batch geocoding operation.
Note
Delete BatchGeocodeResult object returned when it is no longer needed.

Reimplemented in EsriRuntimeQt::LocalLocator, and EsriRuntimeQt::ServiceLocator.

void EsriRuntimeQt::Locator::batchGeocodeComplete ( EsriRuntimeQt::BatchGeocodeResult result)
signal

Signal emits when the asynchronous batchGeocode() operation completes, returning a batch geocode results.

Parameters
[out]resultThe batch geocode results from the geocoding operation.
void EsriRuntimeQt::Locator::batchGeocodeError ( const EsriRuntimeQt::ServiceError error)
signal

Signal emits when an error occurs from the batch geocode operation.

Parameters
[out]errorThe information about the error.
void EsriRuntimeQt::Locator::find ( const LocatorFindParameters findParams)

Asynchronously finds location candidates for a given address, place name, or point of interest.

This method is similar to findAndWait(), except this method finds a location asynchronously.

The findComplete(const QList<EsriRuntimeQt::LocatorGeocodeResult*>&) signal emits when the Find operation completes.

Note
Currently, the method only applies to the world geocoding service hosted on ArcGIS Online. You may obtain an exception accessing another geocoding service that is not supported for this operation.
Parameters
[in]findParamsThe find parameters.
Note
Use deleteLater() to delete each of the LocatorGeocodeResult object returned in the findComplete signal.
virtual QList<LocatorGeocodeResult*> EsriRuntimeQt::Locator::findAndWait ( const LocatorFindParameters findParams) const
virtual

Synchronously finds location candidates for a given address, place name or point of interest.

The Find operation for a geocoding service is used for single field geocoding, that is, where the entire address is provided as a single text string. Complete addresses are not required. The Find operation supports finding the following types of location text strings:

  • Street addresses: 380 New York St, Redlands, CA 92373
  • Administrative place names, such as city, county, state, province or country name: Seattle, Washington
  • Postal codes: 92591 USA
  • Points of interest (POI) or businesses: LAX or banks in Paris

Provide the parameters for the operation in a LocatorFindParameters instance.

Note
Currently the method only applies to the world geocoding service hosted on ArcGIS Online. You may obtain an exception accessing another geocoding service that is not supported for this operation.
Parameters
[in]findParamsThe find parameters.
Returns
The geocode results in a QList.
Note
Delete each of the LocatorGeocodeResult objects returned when it is no longer needed.

Reimplemented in EsriRuntimeQt::LocalLocator, and EsriRuntimeQt::ServiceLocator.

void EsriRuntimeQt::Locator::findComplete ( const QList< EsriRuntimeQt::LocatorGeocodeResult * > &  result)
signal

Signal emits when the asynchronous find() operation completes, returning a list of geocoding results.

Parameters
[out]resultThe results from the geocoding operation.
void EsriRuntimeQt::Locator::findError ( const EsriRuntimeQt::ServiceError error)
signal

Signal emits when there is an error from the find operation.

Parameters
[out]errorThe information about the error.
void EsriRuntimeQt::Locator::geocode ( const QMap< QString, QString > &  addressFields,
const QStringList &  outFields,
const SpatialReference outSR = SpatialReference() 
)

Asynchronously finds location candidates for an address.

This method is similar to geocodeAndWait(), except this method performs geocoding asynchronously.

The geocodeComplete(const QList<EsriRuntimeQt::LocatorGeocodeResult*>&) signal emits when the geocoding process has finished.

Parameters
[in]addressFieldsA QMap containing the address fields and their corresponding values.
[in]outFieldsA QStringList of output fields returned for each address candidate.
[in]outSRThe spatial reference of the location candidates (optional).
Note
Use deleteLater() on each of the LocatorGeocodeResult returned.
virtual QList<LocatorGeocodeResult*> EsriRuntimeQt::Locator::geocodeAndWait ( const QMap< QString, QString > &  addressFields,
const QStringList &  outFields,
const SpatialReference outSR = SpatialReference() 
) const
virtual

Synchronously finds location candidates for an address.

You can specify a list of output fields to return. Passing an empty list returns all the output fields defined for the service.

The returned location candidates use the spatial reference passed in the parameters. Passing an empty spatial reference causes the returned locations to use the default spatial reference defined for the service.

Parameters
[in]addressFieldsA QMap containing the address fields and their corresponding values.
[in]outFieldsA QStringList of output fields returned for each address candidate.
[in]outSRThe spatial reference of the location candidates (optional).
Returns
A QList of LocatorGeocodeResult.
Note
Delete each of the LocatorGeocodeResult objects returned in the when it is no longer needed.

Reimplemented in EsriRuntimeQt::LocalLocator, and EsriRuntimeQt::ServiceLocator.

void EsriRuntimeQt::Locator::geocodeComplete ( const QList< EsriRuntimeQt::LocatorGeocodeResult * > &  results)
signal

Signal emits when the asynchronous geocode() operation completes, returning a list of geocoding results.

Parameters
[out]resultsThe results from the geocoding operation.
void EsriRuntimeQt::Locator::geocodeError ( const QString &  message,
const EsriRuntimeQt::ServiceError error 
)
signal

Signal emits when a geocode service error occurs from the geocoding service.

Parameters
[out]messageError message string.
[out]errorThe information about the error.
Deprecated:
since 10.2.5 Use the error signal corresponding to each operation (e.g findError, geocodeError reverseGeocodeError, batchGeocodeError and locatorInfoError).
void EsriRuntimeQt::Locator::geocodeError ( const EsriRuntimeQt::ServiceError error)
signal

Signal emits when an error occurs from the geocode operation.

Parameters
[out]errorThe information about the error.
virtual LocatorServiceInfo EsriRuntimeQt::Locator::locatorServiceInfo ( ) const
virtual

Gets the information about the geocode service used by this Locator.

Returns
A LocatorServiceInfo instance containing the service information.

Reimplemented in EsriRuntimeQt::ServiceLocator, and EsriRuntimeQt::LocalLocator.

void EsriRuntimeQt::Locator::reverseGeocode ( const Point point,
const double &  distance,
const SpatialReference outSR = SpatialReference() 
)

Asynchronously finds address candidates for a given location.

This method is similar to reverseGeocodeAndWait() except that this method finds addresses asynchronously.

The reverseGeocodeComplete(const EsriRuntimeQt::LocatorReverseGeocodeResult*) signal emits once the geocode operation completes, returning the reverse-geocoding result.

Parameters
[in]pointThe location.
[in]distanceThe search distance in meters.
[in]outSRThe output spatial reference for the location of the address candidates (optional).
Note
Use deleteLater() to delete each of the LocatorReverseGeocodeResult object returned in the reverseGeocodeComplete signal.
virtual LocatorReverseGeocodeResult* EsriRuntimeQt::Locator::reverseGeocodeAndWait ( const Point point,
const double &  distance,
const SpatialReference outSR = SpatialReference() 
) const
virtual

Synchronously finds address candidates for a given location.

In the distance parameter, provide a distance in meters from the given location to search for a matching address. Use 0 if none is desired.

An output spatial reference may be specified. The default is the default spatial reference of the service.

Parameters
[in]pointThe location.
[in]distanceThe search distance in meters.
[in]outSRThe output spatial reference for the location of the address candidates.
Returns
The reverse geocoding result (optional).
Note
Delete the LocatorReverseGeocodeResult object returned when it is no longer needed.

Reimplemented in EsriRuntimeQt::LocalLocator, and EsriRuntimeQt::ServiceLocator.

void EsriRuntimeQt::Locator::reverseGeocodeComplete ( EsriRuntimeQt::LocatorReverseGeocodeResult result)
signal

Signal emits when the asynchronous reverseGeocode() operation completes, returning the reverse-geocoding result.

Parameters
[out]resultThe reverse-geocoding result.
void EsriRuntimeQt::Locator::reverseGeocodeError ( const EsriRuntimeQt::ServiceError error)
signal

Signal emits when an error occurs from the reverse geocode operation.

Parameters
[out]errorThe information about the error.

The documentation for this class was generated from the following file: