Skip To Content

Search for coordinates

In this topic

The Locator task allows you to perform geocoding and reverse geocoding operations. With the Locator task, you can either find the geographic location of an address or the address of a geographic location. The Locator task allows you to perform these operations on online services, or with locator files on the local file system.


Geocoding is the process of transforming a description of a location - such as an address or place name - to a geographic location on a Map. Conversely, reverse geocoding finds the nearest address to a geographic location on a Map. Addresses are fundamental for both geocoding and reverse geocoding and have some specific characteristics, or address elements. An address element is an individual component of the address, such as house number, street name, street type, and postal code. Address elements help in the geocoding search, pinpointing an address to a particular location. Addresses come in various different styles and formats, including street address, a place name, or a location that is identified by a code. A common address format used in the United States consists of the following series of address elements: house number, prefix direction, prefix type, street name; street type, suffix direction; and zone information such as city, state , and ZIP Code. Globally, addresses are represented in a range of different formats. While all of these addresses formats differ to some degree, some things remain consistent. Each address consists of one more address elements, presented in a particular address format recognized in a region.

The locator file is the major component in the geocoding process and contains all the data necessary to perform address matching. A locator is created based on a specific address locator style. Once created, an address locator contains the geocoding properties and parameters that are set, a snapshot of the address attributes in the reference data, and the queries for performing a geocoding search. The address locator also contains a set of address parsing and matching rules that directs the geocoding engine to perform address standardization and matching.

Geocoding services are hosts to locators. To perform geocoding and reverse geocoding successfully, you can use an existing geocoding service hosted by Esri or create and configure your own, possibly on the device your application runs on. You can access a variety of online geocoding services published and hosted by Esri including address locators for Europe and North America, a street locator for the United States, and a world places locator. You can connect directly to these geocoding services through ArcGIS Runtime SDK for Qt. These allow you to begin geocoding with online data right away without the need to create and configure an address locator yourself. Locators can be created and configured for use with local data using ArcGIS for Desktop as the authoring environment.

Creating a Locator

Reference data

To successfully create a locator you will need to build reference data. Reference data refers to a feature class containing the address attributes you want to search. Reference data that contains suitable address attributes for geocoding can be obtained from government agencies, such as U.S. Bureau of Census which distributes U.S. nationwide TIGER/Line files, state, county, or city offices; or commercial data vendors or providers. The reference data you choose will be determined to an large degree by the type of locator you want to create, also known as the locator style.

Locator style

The locator style specifies the type of addresses that can be geocoded, the field mapping for the reference data, and what output information of a match would be returned. It also contains information of how an address is parsed, searching methods for possible matches, and default values for the geocoding options.

There are a number of different address locator styles. Choosing the right one depends on knowing what type of reference data you have and in what format your addresses will be. For example, you can use the US Address - Dual Ranges address locator style for street centerline data containing left and right address ranges, directionals, street names, street types, and left and right ZIP Codes. Alternatively, if you want to geocode U.S. ZIP Code data, you can use the US Address 5-Digit ZIP address locator style for creating a ZIP Code address locator based on a ZIP Code point reference feature class.

Build the Locator using ArcGIS for Desktop

There are two ways in which you can use Desktop to make your locators available for offline use. You can use ArcMap to author and package your .loc locator file and provision the package to your device. Your code will access that file through an absolute or relative path and use it to geocode. Another way to package a locator is to use ArcCatalog or the Creating an address locator geoprocessing tool. After you execute this tool in ArcMap or ArcCatalog, you can share that geoprocessing result as a .gcpk file. This file can then be provisioned to your device and accessed through your geocoding application code from a local service. This second approach is not the preferred approach, as it is a legacy implementation model. For step-by-step instructions on building locators, refer to the topic Creating an address locator in the ArcGIS for DesktopHelp.

Choosing a geocoding option

As mentioned earlier, you can use existing online geocoding services directly with the ServiceLocator task to perform geocoding and reverse geocoding. Or, you can use a ServiceLocator task with the runtime local server and the LocalGeocodeService class. A third option is to use the LocalLocator task to directly read a locator store on the local file system. Each of these geocoding options has its own characteristics that you should consider when choosing one for your application. Let's examine these options.

Using the ServiceLocator task with an online geocoding service

You can leverage an online geocoding service. Your application does not need to manage the service, reducing the processing load on your device. You don't need to store locator files or geocoding package files on your device, reducing file storage space requirements. You must be able to connect to the online geocoding service to use it.

To use the Locator with online data you will be required to pass the URL of an online service or layer. To find the URL, you can use the ArcGIS Services Directory. An example is below:

m_locator = new EsriRuntimeQt::ServiceLocator(
   "ESRI_Geocode_USA/GeocodeServer", this);

Using the ServiceLocator task with a local service

You can create and run a local geoprocessing service on your device. The local service reads a geocoding package file (*.gcpk) that is provisioned on your device. You don't need to connect to a remote service to use the local service.

Create a new LocalGeocodeService with the locator path and the locator name as input parameters.

m_localGeocodeService = EsriRuntimeQt::LocalGeocodeService(
  "C:/SanFranciscoLocator.gcpk", "SanFranciscoLocator");

Set the local geocode service that the ServiceLocator task will use to lookup addresses by passing the LocalGeocodeService's URL to the task's constructor.

m_locator = new EsriRuntimeQt::ServiceLocator(m_localGeocodeService.urlGeocodeService(), this);

Using the LocalLocator task with a local locator

You can create a LocalLocator to perform geocoding operations without a service. The LocalLocator reads a locator file (*.loc) that is provisioned on your device. You don't need to connect to a remote service to use the local locator. You don't need to run a local service, either.

Create a new LocalLocator by passing the locator path and optional LocatorSettings to the constructor.

m_localLocator = new EsriRuntimeQt::LocalLocator("C:/SanFranciscoLocator.loc", this);

Input Parameters

When performing geocoding operations you pass specific parameters to the Locator task so it returns what you expect from the operation. The parameters needed vary depending on the operation.

For the geocode operation, the key parameter is the address fields parameter, which is a dictionary that contains key/value pairs 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 the find operation, use LocatorFindParameters to pass the parameters. Key among the parameters is the text of the single-line address or place name. Obviously for the reverse geocoding operation, the location point is most important.

The geocode operation accepts an outFieldsparameter, a list of fields to include in the result of the operation. If you specify the geometry 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. The outSpatialReference parameter allows the user to set the output spatial reference for the returned coordinates.

Execute the Locator task asynchronously

Asynchronous execution of the Locator task is performed using the geocode method. In your application, connect the geocode operation's signals to slots you define to receive the set of LocatorGeocodeResult objects or error if one should occur. Execute the task asynchronously so your application can remain responsive during the execution of the task. This is the recommended method of execution for most task operations.

connect(m_locator, SIGNAL(geocodeComplete(QList<EsriRuntimeQt::LocatorGeocodeResult*>)), 
        this, SLOT(onGeocodeComplete(QList<EsriRuntimeQt::LocatorGeocodeResult*>)));

m_locator->geocode(addressFields, QStringList(), m_map->spatialReference());

MainApp::onGeocodeComplete(QList<EsriRuntimeQt::LocatorGeocodeResult*> results)
  //display results
  if (!results.isEmpty())


The example above specifies that a list of LocatorGeocodeResult objects containing information about the possible matches for the input address is passed to the onGeocodeComplete method (slot) when the operation completes. Each LocatorGeocodeResult contains the score, address, and location for the match, along with other information.

If results were found, process them by retrieving the attributes of the result with the highest match score. There are various output interfaces available to display the results in your application. To display the results on the Map you can create a graphic and display the graphic on the Map by adding it to a graphics layer. To add the address of the result to the graphic you can create your own Map tips and specify and attribute name of Address, which will allow the value to be bound to the Map tip.

The code snippet below gets the highest matched score from the result, creates a graphic for it, adds the graphic to the Map, then centers the Map extent on the matched location:

// get the top result to display on map
EsriRuntimeQt::LocatorGeocodeResult* highestScoreResult =;

// create and populate an attribute map
QMap<QString, QVariant> attributes;
QMapIterator<QString, QString> i(highestScoreResult->attributes());
while (i.hasNext())
  attributes.insert(i.key(), i.value());
attributes.insert("Located address", highestScoreResult.address());
attributes.insert("Locator score", QString::number(highestScoreResult.score()));
// create a graphic at this location
EsriRuntimeQt::Graphic* addressGraphic = new EsriRuntimeQt::Graphic(highestScoreResult->location(), currSymPoint, attributes, this);


// center the map at this location
EsriRuntimeQt::Envelope extent = m_map->extent();

foreach(EsriRuntimeQt::LocatorGeocodeResult* geocodeResult, results)

For obtaining reverse geocoding results on an asynchronous call, connect the reverseGeocodeStatusChanged signal to a the method that will process the results. The information for the address closest to the input point is passed on to the method . There are various ways to display the results. One way is to get references to the found address and its attributes and create a Graphic with your own Map tips to display the address.