Using a place name or street address as input, your user can find locations of interest and interact with them on the map. The process of matching locations on the map to an address is referred to as geocoding.
Address geocoding (or geocoding) is the process of using information contained in an address to interpolate a corresponding location on the map. An address may define a precise street location, such as 380 New York Street, Redlands CA 92373. It may provide only a general location, such as a city name or postal code, or it may be a familiar place name or landmark, such as Ayers Rock.
Using a reference data source, referred to as a locator, ArcGIS finds map locations by matching an input address with feature attributes. The number and accuracy of the geocoded results (often called matches or candidates) may vary depending on the specificity and quality of the input address provided. For example, the address New York is likely to return a match for the state of New York, the city of New York, and perhaps several streets or points of interest that share that name. Geocoded locations are always points. If a match is made with a polygon (a state or postal code, for example), the match location represents the center of that area.
Additional geocoding inputs can improve the relevance of results by restricting the search to a given area or finding matches that are near a reference location. This allows you to find results for a specified country, map extent, or near the user's current or anticipated location. A general search such as restaurant is unlikely to return useful candidates unless it is restricted to a specific area.
When several candidates are returned for an address, they are sorted by the quality of the match. This means it is generally safe to assume that the first candidate in the results represents the best match. Sometimes, however, you may want to examine a set of top candidates to determine the most appropriate match. Address candidates can contain the level at which they were matched (house, street, postal code, and so on) and the interpolated address created by the locator. Both of these may help you determine the best match or perhaps find problems in the original address input. If geocoding used a reference location, a distance attribute can help you find the closest candidate.
The score attribute, an integer value ranging from 0 to 100, provides an estimate of relative match accuracy within a single locator. If you are using a composite locator (such as the ArcGIS World Geocoding Service), these values will represent the score within a locator for a specific level, but not an overall evaluation of the match. A score of 100 for a postal code match is not necessarily a more precise result, for example, than a score of 90 at the house level.
Addresses are fundamental for geocoding and have some specific characteristics. An address is composed of one or more address elements: individual components 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 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 variety of formats. However, while all of these addresses differ to some degree, some things remain consistent. Each address consists of one or more address elements presented in a particular address format recognized by those in the region.
When geocoding, you can pass in individual components of an address or provide all information as a single string to be parsed. Defining each component of an address gives you more control but may require that you either parse the components before passing them to the locator or provide additional UI controls for your user to enter each piece of information.
When geocoding, the type of information expected in an input address is determined by the address style configured by the locator you're using. Some of the common address component field names for the ArcGIS World Geocoding Service (https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer) are listed below as examples of the types of input that may be expected. See Multiple input field geocoding for details.
- Address—House number and street
- Neighborhood—Subdivision of a city (not used for United States addresses)
- City—City or municipality
- Subregion—Administrative region, such as a county or province (not used for United States or Mexico addresses)
- Region—Largest administrative boundary associated with the address (state name in the United States)
- Postal—Postal code
- CountryCode—Name or ISO code of the country
The fundamental logic for geocoding is built into the locator and does not come from your ArcGIS Runtime SDK code. The locator (created using ArcGIS Desktop) is the major component in the geocoding process and contains all the data necessary to perform address matching. If you'd like a ready-to-use and regularly updated locator (and network dataset) for your area of interest, you can license StreetMap Premium data (in MMPK format). For details, see Add StreetMap Premium data.
A locator is created based on a specific address locator style, which dictates what type of address input is expected and how matching will be carried out. The following table lists some of the common address styles, the type of matching that it enables, and an example of input address values:
|Address style||Description||Input address examples|
US Address - City State
Finds a city in the United States using reference data that stores city and state names
US Address - Dual Ranges
Interpolates an address location using a streets reference dataset that includes number ranges for both sides of the street
30 E. State St, Redlands CA 92373
1060 W. Addison St, Chicago IL 60613
General - Gazetteer
Finds place names or landmarks worldwide using reference data with a place name attribute
General - Single Field
Locates features using a specific field in the reference dataset
This is not a complete list of the available address styles. For a more complete description, see Commonly used address locator styles in the ArcGIS Desktop help.
Once created, an address locator contains a set of geocoding properties (preferences), a snapshot of the address attributes in the reference dataset, 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.
A locator can be stored locally (as a *.loc file) or can be published as a locator service using ArcGIS Server. To perform geocoding, you need to access either an online locator or one available locally on the device. Using ArcGIS Runtime SDK, you can connect to a variety of online locators 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. These services allow you to begin geocoding with online data right away without having to create and configure an address locator yourself. Locators can be created and configured with local data using ArcGIS Desktop as the authoring environment. See Creating ArcGIS Runtime content for detailed information.
Without the *.locb file, ArcGIS Runtime SDK is not able to use the locator in an offline environment.
Geocoding results for a particular address are referred to as candidates. Depending on how specific and complete the input address is, you may get several candidates from a geocode operation. Geocoding results are ordered by quality of the match, so the first candidate is generally the best. Additional candidate information can be obtained by specifying supplemental output fields to include in the results. The following table describes a few of the available fields you can include from the world geocoding service. This is only a representative list of fields. For a complete list, see Output fields in the ArcGIS REST API documentation.
The fields provided may vary between locators. See the Get locator info section of this topic for information about querying a locator for its available result attributes.
Value between 0 and 100 that describes the relative quality of the match within a single locator.
Complete address returned for the geocode request. The format is based on address standards for the country within which the address is located.
The match level for a geocode request. For example, a candidate that matches only to a postal code will have a value of Postal. Supported match levels vary in different countries. See Output fields for a description of possible values for this field.
The side of the street on which the address was matched (relative to the direction of digitization of the reference line feature). Possible values are L (left), R (right), or an empty string (undefined).
The distance (meters) from the candidate to a specified location. The reference location needs to be specified as a parameter before executing the task.
A number indicating the importance of each candidate relative to others in the results. Rank is generally used to help distinguish ambiguous place names using population as the criterion. A search for Las Vegas, for example, may return Las Vegas, NV as the top ranked match (1) and Las Vegas, NM as a lower rank based on the relative population of those cities. If a reference location and distance parameters have been set for a find operation, distance from the reference location will be used to rank candidates.
Use a locator task
Geocoding is implemented using the LocatorTask class with an online or local locator. To implement this task in your code, follow these general steps:
- Create a LocatorTask using an online or local resource (locator service or file).
- Specify geocoding preferences using the GeocodeParameters object. This is optional but allows you to request additional attributes in the results, to restrict the search by area, set the maximum number of results, and so on.
- Execute the task, passing in any required parameters (such as address values and geocode parameters).
- Process the results (display a list of candidates for the user to choose from, display the best match as a graphic on the map, and so on).
For example, create an online locator by passing the URL of the ArcGIS Online World Geocoding service to the LocatorTask constructor; alternatively, create an offline locator by passing the full file path of the locator file.
// 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, [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
Note:The World Geocoding Service from ArcGIS Online includes a for_storage parameter. Storing the results of a geocode or reverse geocode operation using this service (by setting the for_storage parameter to true) requires an ArcGIS Online paid subscription and uses credits from the subscriber's account. Additionally, the user performing a paid operation must be assigned a user role that includes the geocoding privilege. For more information, see Free vs. paid operations in the REST documentation for this geocode service and Levels, roles, and privileges in ArcGIS Online Help.
Get locator info
Before executing a geocode operation, you may need information about a particular locator to work with it effectively. You may need to know which input fields are used to locate an address, which attributes are available with the results, or the spatial reference in which the candidate locations will be returned by default. You can use LocatorInfo to get the following information about a locator:
- Name—A string that identifies the locator
- Description—A brief description
- Result attributes—A list of field names that are available for results
- Search attributes—A list of input fields used for multiline geocoding
- Spatial reference—The spatial reference used by the locator (and the default coordinate system for results)
- Support for intersections—A true or false value that indicates whether geocoding of street intersections is supported
- Support for points of interest—A true or false value that indicates whether searching points of interest (POI) is supported
- Support for suggestions—A true or false value that indicates whether the locator supports offering suggestions for addresses
- Version—The version of the locator
The following example shows how you can examine the LocatorInfo of the LocatorTask to list the names of the attributes available on geocode results:
// Get LocatorInfo from a loaded LocatorTask
LocatorInfo locatorInfo = m_locatorTask->locatorInfo();
// Loop through all the attributes available
for (const auto resultAttribute : locatorInfo.resultAttributes())
// Add the field's display name to a list box
When geocoding an address or point of interest, you can optionally provide preferences to control certain aspects of the geocoding operation. The following list describes some of the properties you can control:
- Country—The full name or code for the country to which geocoding should be restricted
- Maximum results—A limit for the maximum number of address candidates to return
- Output language—The language (culture) in which result attributes will be returned
- Output spatial reference—The spatial reference in which geographic locations for address candidates will be returned
- Result attributes—A list of field names to include in the results (available fields can be queried from the locator)
- Search area—A geographic shape that defines an area to geocode within
A similar (more limited) set of preferences is available when getting a set of address suggestions, as described in the following section.
Get address suggestions
You can use a locator task to find suggestions for a partial address entry. As your user types an address, for example, a list of suggestions based on the first few characters of the address string can be displayed. Check LocatorInfo.supportsSuggestions to see if a particular locator can provide address suggestions.
A search for address suggestions can optionally be restricted to a specified country or area on the map. To define a country, use the full name or ISO 3166-1 (two or three character) code. See Geocode coverage in the REST API documentation for a list of countries and corresponding codes. You can also indicate a preferred location (point) for the search, and set the maximum number of suggestions to return.
Restricting your search or geocode operations to a specified country or location (as well as the number of results) can improve performance.
The following example sets the searchText of the LocatorTask's SuggestListModelto get address suggestions based on user input. Each time the searchText changes, more suggestions are asynchronously retrieved. A SuggestParameters object is used to restrict the search for suggestions to address that are located within the current map extent. The SuggestListModel can be used in a view, such as a ListView, for displaying the suggested results.
// get suggestions if the locator supports them
// get the current map extent
Envelope currentExtent = currentMapArea; // e.g. mapView->currentViewpoint(ViewpointType::BoundingGeometry).targetGeometry();
// restrict the search to the current map extent and return no more than 10 suggestions
// set the parameters on the SuggestListModel
// set the searchText to get suggestions for the text provided by the user
// setting this will kick off an async task to obtain suggestions
The address suggestion results do not contain location information, only the full address text. To get a location, you must take the additional step of geocoding the suggestion as described in the following section.
Geocode an address
Use a LocatorTask to find geocode candidates from an address, point of interest, or address suggestion. An input address can be defined as a single string, such as 380 New York Street, Redlands CA 92373 or you can define the individual components of the address (such as number and street, city, region, postal code, and so on).
You can use LocatorInfo to get the input address field names for a locator.
If you define the address as a single string, it will be parsed into the appropriate address components by the locator.
// set up signal handler for when the geocode completes
connect(m_locatorTask, &LocatorTask::geocodeCompleted, this, [this](QUuid, QList<GeocodeResult> geocodeResults)
// loop through results
for (const auto result : geocodeResults)
// create graphics from each result
// geocode with a single text string
m_locatorTask->geocode("380 New York Street, Redlands CA 92373");
You can also geocode using a result from an address suggestion. The following example geocodes a suggested address as created in the Get address suggestions section of this topic.
// get the suggest result from the list model
SuggestResult suggestResult = m_locatorTask->suggestions()->suggestResults().at(index);
// geocode with the suggest result
The following example matches a Japanese address with the ArcGIS World Geocoding Service. The geocode parameters restrict the address search to Japan.
// create the parameters GeocodeParameters geocodeParams; geocodeParams.setCountryCode("Japan"); // Geocode an address in Japan - Prime Ministers Office QString address = "東京都千代田区永田町２‐２‐２"; m_locatorTask->geocodeWithParameters(address, geocodeParams);
See Geocode coverage in the REST API documentation for a list of supported countries and corresponding codes.
Find points of interest
You can also geocode points of interest using a place name, such as Eiffel Tower or even more general terms, such as bank or bus stop. The geocode parameters allow you to restrict your search to a specified extent or to prefer candidates that are closer to a specified location, which can be useful if searching for facilities near the user's current position. You can provide the user with information about the locations, such as addresses, phone numbers, and URLs for candidates, as well as the distance from a reference location.
Not all locators support geocoding a point of interest. The result information for candidates will also vary with the locator. Use LocatorInfo to see if geocoding points of interest is supported and which attributes are available for the result candidates, as described in a preceding section. The Distance attribute will only contain (non-zero) values if a preferred search location (point) is provided in the geocode parameters.
Geocoding a point of interest involves the same process as using an address described in the previous section. Instead of passing a single-line address value as input, you can provide a place name. The following are examples:
- Point of interest by name
- Wrigley Field
- mount everest
- Point of interest by category
- coffee in Salt Lake City
- Administrative place name, such as a city/county/state/province/country name—Seattle, Washington
- Postal code—92591 USA
You can use geocode parameters to refine or restrict search results when geocoding place names just as you do with addresses.
The following example searches for five ice cream shops near a specified location (the center of the map extent) and specifies that name, phone number, address, and distance are returned in the results. The results could then be displayed as graphics that have the same attributes as the geocode results (which could then be displayed in a callout for example).
// Get the center of the current map extent
Point mapCenter(pt); // e.g. mapView->currentViewpoint(ViewpointType::CenterAndScale).targetGeometry();
// Retrieve the 5 closest matches to the map center
geocodeParams.setCategories(QStringList() << "Ice Cream Shop");
// Ensure the results return the Address, Phone and Distance
QStringList resultAttributeNames = geocodeParams.resultAttributeNames();
// Geocode the closest ice cream shops using the specified geocoding parameters