ArcGIS Runtime SDK for Java - Reverse geocoding

Reverse geocoding is the process of finding the nearest address or addresses to a geographical location on a map. In the ArcGIS Runtime SDK for Java you can perform reverse geocoding operations on both local and online services using a Locator instance. If you wish to find the geographic location of a known address or place then please refer to Geocoding.

Reverse geocoding

Key to reverse geocoding operations are addresses which are typically made up of components such as house number, street name, street type, and postal or zip code. Address elements help in the search, pinpointing an address near a particular location. While, globally, addresses are represented in a range of different formats, each address consists of address elements, presented in a particular address format recognized by those in the region.

The locator 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.

To perform reverse geocoding you will need to access either an online locator hosted by Esri, create and share your own online geocoding service or share your own locator package file. Please go to this location for more information on Locator packages.

Peforming reverse geocoding using a Locator

To perform reverse geocoding, make use of the Locator class, using the key steps below:

Instantiate the Locator class and provide the URL of the online or local geocoding service to the Locator constructor.
Specify the input parameters for the Locator.
Execute reverse geocoding using synchronous or asynchronous methods on the Locator.
Listen for the completion of the reverse geocoding and process the results.

Obtain the URL to the geocoding service

Firstly, obtain the URL of the online or local geocoding service that will be used to perform the geocode or reverse geocode. The URL for a local geocode service can be obtained from the LocalGeocodeService once it has been created using the path to a locator package.

Here is the code to obtain the URL of a local locator package.

LocalGeocodeService localGeocodeService = 
      new LocalGeocodeService("Path to Locator Package (.gcpk)");
 
localGeocodeService.startAsync();
localGeocodeService.addLocalServiceStartCompleteListener
     (new LocalServiceStartCompleteListener() { 
 
     @Override 
     public void localServiceStartComplete(LocalServiceStartCompleteEvent e) 
     {
      string theGeocodeServiceURL = localGeocodeService.getUrlGeocodeService(); 
     } 
});

Here is the URL to an online geocoding service.

string theGeocodeServiceURL = 
"http://tasks.arcgisonline.com/ArcGIS/rest/services/Locators/TA_Streets_US/GeocodeServer";

Instantiate the Locator

Instantiate the Locator class passing the geocode URL to the Locator constructor.

Instantiate the Locator passing in the local or online URL to the layer to be queried.

Locator locator = new Locator(theGeocodeServiceURL);

Asynchronous reverse geocoding

Reverse geocoding will take a location and provide the addresses within a given distance of that location.

Firstly, provide the geographic location as a point in map coordinates. You could convert screen coordinates to map coordinates using the toMapPoint method on the JMap class.

Next pass this location to the locationToAddressAsync method along with:

a distance in meters from the given location within which a matching address is searched.
if the location coordinates are in a different spatial reference than the one expected by the service then provide an input spatial reference.
if the coordinates for the address candidates are wanted in a different spatial reference than the one defined in the service then provide an output spatial reference.
a CallbackListener that will be fired when the results are return or an error is thrown.

The addresses that are found near the location will be returned to a list of LocalReverseGeocodeResults.

 
Point mapPoint = map.toMapPoint(screenX, screenY);
SpatialReference inputSR = map.getSpatialReference().getID();
SpatialReference outputSR = map.getSpatialReference().getID();

locator.locationToAddressAsync(mapPoint, 30, inputSR, outputSR,
                               new CallbackListener<List<LocatorReverseGeocodeResult>>() { 
 
      @Override 
      public void onError(final Throwable arg0) { 
       ... 
      } 
 
      @Override 
      public void onCallback(final List<LocatorReverseGeocodeResult> results) { 
 
						// process the results
             		
      }; 
           
});

Synchrononous reverse geocoding

Firstly, provide the geographic location as a point in map coordinates. You could convert screen coordinates to map coordinates using the toMapPoint method on the JMap class.

Next pass this location to the locationToAddress method along with:

a distance in meters from the given location within which a matching address is searched.
if the location coordinates are in a different spatial reference than the one expected by the service then provide an input spatial reference.
if the coordinates for the address candidates are wanted in a different spatial reference than the one defined in the service then provide an output spatial reference.

The addresses that are found near the location will be returned directly to a List of LocalReverseGeocodeResults.

 
Point mapPoint = map.toMapPoint(screenX, screenY);
SpatialReference inputSR = map.getSpatialReference().getID();
SpatialReference outputSR = map.getSpatialReference().getID();

LocatorReverseGeocodeResult theResults;
theResults = locator.locationToAddress(mapPoint, 30, inputSR, outputSR);

Process the reverse geocoding results

The results of the locationToAddress and locationToAddressAsync methods on the Locator task are returned in a list of LocatorReverseGeocodeResults (as above). All that remains is for you to process this list to obtain the addresses near the supplied location.

Process the first result in the list

GraphicsLayer theGraphicsLayer = new GraphicsLayer(); 
jMap.getLayers().add(theGraphicsLayer);

...
   
// create and populate attribute map
Map<String, Object> address = new HashMap<String, Object>();

//place the address field and values into the HashMap
for (Entry<String, String> entry : theResults.getAddressFields().entrySet()) {
   address.put(entry.getKey(), entry.getValue());
}

// create a graphic at the location
Graphic addressGraphic = new Graphic(
                        theResults.getLocation(),symPoint, address, null);

//add the graphic to the graphicslayer        
theGraphicsLayer.addGraphic(addressGraphic);

Sample code

To view samples related to geocoding, including reverse geocoding, please launch the ArcGIS Runtime for Java sample application that was installed with the ArcGIS Runtime SDK for Java and explore the interactive samples and their code in the Search > Geocoding section.

2/7/2013