Search for places

ArcGIS Runtime SDK for .NET provides tools for searching places on the map. Using a place name or street address as input, your user can easily 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.

Geocoding overview

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"; may provide only a general location, such as a city name or postal code; or may be a familiar place name or landmark, such as "Ayers Rock".

Using a reference data source, referred to as a locator, ArcGIS is able to find 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. The address "New York", for example, 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 like "restaurant", for example, is unlikely to return useful candidates unless it is restricted to a specific area.

When several candidates are returned for an address, they will be 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 might 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, etc.) and the interpolated address created by the locator. Both of these might 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 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 ( are listed below as an example of the type of input that may be expected. See Multiple input field geocoding for more details.

  • Address—House number and street
  • Neighborhood—Subdivision of a city (not used for US addresses)
  • City—City or municipality
  • Subregion—Administrative region, such as a county or province (not used for US or Mexico addresses)
  • Region—Largest administrative boundary associated with the address (state name in the US)
  • 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 for Desktop) 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, 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 styleDescriptionInput address examples

US Address - City State

Finds a city in the United States using reference data that stores city and state names.

Bonita, CA

Punxsutawney, PA

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.

Taj Mahal


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 for 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 for 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 for Desktop as the authoring environment. See the ArcGIS help topic Creating an address locator for detailed information.


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 the Output fields topic 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.

Output fieldDescription


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 one of the LocatorTask classes: OnlineLocatorTask for geocoding with an online locator, or LocalLocatorTask for using a locally available locator. To implement one of these tasks in your code, follow these general steps:

  1. Create a new OnlineLocatorTask or LocalLocatorTask, and point it to an appropriate online or local resource.
  2. If performing a Find operation, specify input parameters using an OnlineLocatorFindParameters object, setting properties to define things such as the address to find, output spatial reference, and output fields.
  3. Asynchronously execute the task, passing in any required parameters (such as the address to match).
  4. Process the results (display a list of candidates to choose from, display the best match, and so on).


You can give the user the ability to cancel long-running tasks by providing a CancellationToken when creating the task.

In addition to the locator tasks described in this topic, ArcGIS Runtime SDK provides a variety of other Task classes. There are tasks for querying features by location or attributes, getting driving directions, printing, and more. Although individual tasks provide a range of functionality for use in your app, they all share the same essential programming pattern described above.

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 candidate fields are available with the results, or the spatial reference in which the candidate locations will be returned by default. You can use GetInfoAsync to get information about an online or local locator.

The following example shows how you can use an OnlineLocatorTask to connect to an online locator service and determine some of its properties:

// get information about an online locator
var uri = new Uri("");
var locatorTask = new Esri.ArcGISRuntime.Tasks.Geocoding.OnlineLocatorTask(uri);
var info = await locatorTask.GetInfoAsync();

// write info to controls on the page
// - description of the locator
this.DescriptionTextBlock.Text = info.ServiceDescription;

// - input address fields used by the locator
this.AddressFieldsDataGrid.ItemsSource = info.AddressFields;

// - available candidate fields (for output)
this.CandidateFieldsDataGrid.ItemsSource = info.CandidateFields;

// - spatial reference ID
this.WkidTextBlock.Text = info.SpatialReference.Wkid.ToString();

Geocode an address

To geocode an address, call the GeocodeAsync method on either an OnlineLocatorTask or a LocalLocatorTask object. You need to pass in a Dictionary<string, string> object containing address values, a List<string> with the desired output fields, and a CancellationToken. If you do not want to allow your user to cancel the request, you can pass in a new cancellation token, as shown in the following example. Optionally, you can pass in a SpatialReference object to define the desired output spatial reference for the results.

The address input is a dictionary of address values. The key for each value indicates the name of the address component for the corresponding value. To set the individual components for "380 New York Street Redlands CA 92373", for example, your code might be similar to the following:

var address = new Dictionary<string, string>();
address.Add("Address", "380 New York Street");
address.Add("City", "Redlands");
address.Add("Region", "CA");
address.Add("Postal", "92373");

You can also define the address as a single input by setting the single line address value. In that case, the address string will be parsed into the appropriate components by the locator.

var info = await locatorTask.GetInfoAsync();
var address = new Dictionary<string, string>();
address.Add(info.SingleLineAddressField.FieldName, "380 New York Street Redlands CA 92373");


The GetInfoAsync method on the locator can be used to determine the name to use for the single line address input field, as shown in the preceding example.

The following example matches an address with an online locator for Tokyo using the Japanese addressing system. All the logic required to match addresses is stored with the locator and its reference data. To modify this code to match an address in the US, you simply change the URI to a locator service that uses US reference data and the US address rules.

// create a new online locator task ("Tokyo residence level locator")
var uri = new Uri("東京都住居レベルロケータ/GeocodeServer");

var token = string.Empty;
var locator = new OnlineLocatorTask(uri, token);

// get info about the locator (will need the name of the single address input field)
var info = await locator.GetInfoAsync();
// store the name of the single address input field
var singleAddressFieldName = info.SingleLineAddressField.FieldName;

// create a dictionary to contain the address info 
var address = new Dictionary<string, string> ();
// add address components to the dictionary using the correct input field names (a single address line in this example)
address.Add(singleAddressFieldName, "東京都千代田区永田町2‐2‐2");//(Japan Prime Minister's office)

// create a list of output fields to include with the candidates
var candidateFields = new List<string> { "Score", "Addr_type", "Match_addr", "Side" };

// start the geocode task: pass in the address, out candidate fields, out spatial reference, and an empty cancellation token
var task = locator.GeocodeAsync(address, candidateFields, MyMapView.SpatialReference, new System.Threading.CancellationToken()); 

IList<LocatorGeocodeResult> results = null;
    // await the results of the task
    results = await task;

    // if at least one candidate was found, get its location (point)
    if (results.Count > 0)
        var firstMatch = results[0];
        var matchLocation = firstMatch.Location as MapPoint;
        // ... code here to display point on the map ...
catch (Exception ex)
    var msg = "Exception from geocode: " + ex.Message;

Tokyo geocoding result

Find places

The OnlineLocatorTask provides a FindAsync method that allows you to quickly search the ArcGIS World Geocoding Service ( for a place name or address. Using Find rather than Geocode allows you to restrict your search to a specified country or extent, to search for broad categories of locations (coffee shops, for example), and gives you the ability to prefer candidates that are closer to a specified location (the user's current position, for example). You can even provide the user with phone numbers and URLs for candidate locations, as well as the distance from a reference location.

The FindAsync method takes a single-line address value as input and supports finding the following types of locations:

  • Street addresses—380 New York St, Redlands, CA 92373
  • Points of interest (POI) by name and category. For example:
    • Disneyland
    • banks in Paris
    • los angeles starbucks
    • mount everest
  • Administrative place names, such as city/county/state/province/country names—Seattle, Washington
  • Postal codes—92591 USA

You can use the following properties on the LocatorFindParameters class to refine or restrict search results when using FindAsync:

  • Specify output fields to return in the geocoding response with the OutFields property.
  • Specify the spatial reference of result locations with the OutSpatialReference property.
  • Limit the number of candidates with the MaxLocations property.
  • Restrict searches to a specific country by setting the SourceCountry property.
  • Confine the search results to a specified area with the SearchExtent property.
  • Use the Location and Distance properties to prefer local candidates, which will then be ranked higher in the candidates list.

The following example searches for ice cream shops near a specified location and displays their name, phone number, and a link to their website. The closest candidates are presented to the user at the top of the list.

// create a locator to search the ArcGIS Online World geocode service
var uri = new Uri("");
var token = String.Empty;
var locator = new Esri.ArcGISRuntime.Tasks.Geocoding.OnlineLocatorTask(uri, token);

// get the locator's spatial reference
var info = await locator.GetInfoAsync();
var locatorSpatialRef = info.SpatialReference;

// create find parameters; search locations for "ice cream"
var findParams = new Esri.ArcGISRuntime.Tasks.Geocoding.OnlineLocatorFindParameters("ice cream");

// set the output spatial reference to match the map's
findParams.OutSpatialReference = MyMapView.SpatialReference;

// restrict the search to the current map extent
var searchExtent = Esri.ArcGISRuntime.Geometry.GeometryEngine.Project(MyMapView.Extent, locatorSpatialRef);
findParams.SearchExtent = (Esri.ArcGISRuntime.Geometry.Envelope) searchExtent;

// prioritize matches within 5 kilometers of the center of the current map extent
var centerOfMap = MyMapView.Extent.GetCenter();
var centerOfMapLatLong = (MapPoint)GeometryEngine.Project(centerOfMap, locatorSpatialRef);
findParams.Location = centerOfMapLatLong; // distance to candidates will be measured from here
findParams.Distance = 5000; // meters

// return a maximum of 5 candidates
findParams.MaxLocations = 5;

// return phone number, url, and distance attributes with the candidates
var candidateFields = new List<string> { "Phone", "URL", "distance" };
findParams.OutFields = candidateFields;

    // execute a find on the locator using the parameters defined above
    var task = locator.FindAsync(findParams, new System.Threading.CancellationToken());
    IList<Esri.ArcGISRuntime.Tasks.Geocoding.LocatorFindResult> results = await task;
    foreach (var candidate in results)
        // get information about each candidate
        var candidateFeature = candidate.Feature;
        var name = candidate.Name;
        var phone = candidateFeature.Attributes["Phone"].ToString();
        var url = candidateFeature.Attributes["URL"].ToString();

        // get distance in miles from the center of the map
        var distMeters = 0.0;
        double.TryParse(candidateFeature.Attributes["distance"].ToString(), out distMeters);
        var distMiles = distMeters * 0.00062137; // convert from meters to miles
        // get location (geometry) 
        var matchLocation = candidateFeature.Geometry as Esri.ArcGISRuntime.Geometry.MapPoint;

        // ... code here to display point graphics and info ...
catch (Exception ex)
    var msg = "Exception from geocode: " + ex.Message;

Results of finding locations with the search term "ice cream"
Related topics