Skip To Content

Search for coordinates

In this topic

The process of transforming geographical coordinates on the map to an address or place name is known as reverse geocoding. To perform reverse geocoding, the API provides a specific class called LocatorTask that enables reverse geocoding against an ArcGIS locator. The ArcGIS Runtime SDK for .NET provides two LocatorTask classes. The LocalLocatorTask requires a locally available locator (*.loc file ) file on your machine, while the OnlineLocatorTask relies on the access to a remote ArcGIS Online Geocoding Service to perform these functions. When using a LocalLocatorTask, reverse geocoding can be computed locally even when it has no network connectivity. Using remote services requires a network connection but is an opportunity for incorporating additional functionality such as real time updates. To learn more about the ArcGIS Online Geocoding Service see the ArcGIS Online Geocoding Service Help.

Initialize a LocatorTask

Whether you are performing online or offline geocoding, you start by initializing a LocatorTask object. Once you've initialized the appropriate online or offline LocatorTaskclass, the programming pattern is exactly the same.

Online

To initialize an OnlineLocatorTask, declare an OnlineLocatorTask object, instantiate it with the new keyword, and pass the uniform resource identifier (URI) to a REST endpoint that represents an ArcGIS Online Geocoding Service to the constructor. If the service is secured, you also need to handle authenticating with the service using the appropriate mechanism. See the Security topic for more information.

The following code sample shows how to create an OnlineLocatorTask for the World Street Map basemap layer using an ArcGIS Online Geocoding Service:

// create a new online locator task for the World Street Map layer
var locator = new Esri.ArcGISRuntime.Tasks.Geocoding.OnlineLocatorTask(new Uri("http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer"));

Offline

To initialize an offline LocatorTask, declare a LocalLocatorTask object, instantiate it with the new keyword, and pass the path to the locator (*.loc file) to the constructor.

The following code example shows how to create a LocalLocatorTask using a locally available locator (*.loc file):

// create a new local locator task using a locally available locator.
var locator = new Esri.ArcGISRuntime.Tasks.Geocoding.LocalLocatorTask("path to .loc file");

Input parameters

Use the LocatorTask to perform the reverse geocode on the geographic point by calling its ReverseGeocodeAsync method. At the minimum, you need to provide the geographic location as a point in map coordinates, a search distance in meters from that location within which a matching address should be searched, and a cancellation token with which to cancel the operation if required. An optional parameter you can provide is the spatial reference in which the address candidate is to be returned.

Map location

To capture the input point geometry from a user, you can use a number of methods. For capturing the input point geometry for input straight into the ReverseGeocodeAsync method, you can use the MapView.MapViewTapped event. The MapView control exposes touch and mouse events such as the MapView.MapViewTapped event. You can add a MapViewTapped handler to the MapView control.

The following code example shows how to capture the input point geometry using the MapView.MapViewTapped event to pass into the ReverseGeocodeAsync method:

private async void mapView_MapViewTapped(object sender, Esri.ArcGISRuntime.Controls.MapViewInputEventArgs e)
{
    graphicsLayer.Graphics.Add(new Graphic(e.Location));
    OnlineLocatorTask locator = new OnlineLocatorTask(new Uri("http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer"));
    var addressInfo = await locator.ReverseGeocodeAsync(e.Location, 50, SpatialReferences.Wgs84, CancellationToken.None);
}
Note:

Because the call to ReverseGeocodeAsync is asynchronous, you must use the await keyword. This means that the MapViewTapped event handler must also be marked with the async keyword, as shown in the previous example.

For more complex operations where you want the input point geometry at a specific time in your code, you can use mapView.Editor.RequestPointAsync. The MapView control has an associated Editor that is accessible from the Editor property. In addition to helping you configure editing functionality, the Editor class provides methods for obtaining geometry from the user. You can use the mapView.Editor.RequestPointAsync method on the Editor to get a point to reverse geocode from the user. RequestPointAsync returns the user's map click as a MapPoint object. Because the call to RequestPointAsync is asynchronous, you must use the await keyword. This means that the function that contains the call must also be marked with the async keyword.

The following code example shows how to capture the input point geometry and pass to the ReverseGeocodeAsync method using the mapView.Editor.RequestPointAsync method:

var mapPoint = await mapView.Editor.RequestPointAsync();
var locator = new Esri.ArcGISRuntime.Tasks.Geocoding.OnlineLocatorTask(new Uri("http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer"));
var addressInfo = await locator.ReverseGeocodeAsync(mapPoint, 50, SpatialReferences.Wgs84, CancellationToken.None);

Search distance

You need to provide a search distance in meters from that location within which a matching address should be searched. If the search distance is not provided or an invalid value is provided, a default value of 0 is used.

Retrieve and display results

The ReverseGeocodeAsync method returns a LocatorReverseGocodeResult object. The following code example shows how to perform reverse geocoding by calling the ReverseGeocodeAsync method:

Esri.ArcGISRuntime.Tasks.Geocoding.LocatorReverseGeocodeResult result = await locator.ReverseGeocodeAsync(e.Location, 50, CancellationToken.None);

From this result object, you can obtain details for the found address from the LocatorReverseGocodeResult.AddressFields property, and display the address to the user. You may want to show address information in a map overlay element. These elements are commonly used to display custom labels for locations on the map, commonly referred to as MapTips. To learn more about map overlays, see Display map overlays.

The following code example shows how to display the reverse geocoding address and address location in a basic map overlay element:

//Build the estimated reverse geocoding address string by reading values in the LocatorReverseGeocodeResultAddressFields property, which is a dictionary of strings.
var address = addressInfo.AddressFields["Address"] + ", " +
              addressInfo.AddressFields["City"] + ", " +
              addressInfo.AddressFields["Region"] + " " +
              addressInfo.AddressFields["Postal"];

//Create a textblock containing the address and add to the map overlay
                var tb = new TextBlock();
                tb.FontWeight = FontWeights.Bold;
                SolidColorBrush myBrush = new SolidColorBrush(Windows.UI.Colors.Black);
                tb.Foreground = myBrush;
                tb.Text = address;
                mapView.Overlays.Add(tb);  
//To position the map overlay element at the address location, call MapView.SetMapOverlayAnchor and pass in textblock and a map point for the address location.
                MapView.SetViewOverlayAnchor(tb, e.Location);

Using a map overlay element to display reverse geocoding address results

See the Add geocoding to your app tutorial to learn how to use the OnlineLocatorTask to perform geocoding and reverse geocoding operations using an ArcGIS Online Geocoding Service.

Related topics