ArcGIS Runtime SDK for Java

Geocoding is the process of transforming a description of a location - such as an address or place name - to a geographical location on a map. In the ArcGIS Runtime SDK for Java you can perform geocoding on both local or online services using a Locator instance. If you wish to find addresses at a specific location, a process known as reverse geocoding, then please refer to Reverse geocoding.

Geocoding

You can geocode by entering one location description at a time or by providing many of them at once in a list, the latter known as batch geocoding. The location description can for example be a place name, a point of interest, or what is most common, an address which can be separated into components. Using the ArcGIS Runtime for Java API, you can geocode using a single input field search string or using an address split into its components. In both cases, you use a locator by creating a Locator instance and calling methods on it to obtain results for a set of parameters.

Locator

The locator is the major component in the geocoding process and contains all the data necessary to match addresses and place names to locations such as a latitude, longitude pair. A locator is created based on a specific address locator style. Once created, a 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 locator also contains a set of address parsing and matching rules that directs the geocoding engine to perform address standardization and matching.

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

Geocoding with a single line

A service which supports single line geocoding can be used to find locations for addresses, as well as place names and points of interest. For such a service the location description is passed in to the locator as a single line of text. One example of such a service is the ArcGIS Online World Geocoding Service, accessible as a REST endpoint at http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer. To use this service, create a Locator using this URL, then follow the instructions below to geocode with a single line text input.

Geocoding with address fields

Other services only support geocoding using addresses separated into their compoment parts, such as house number, street name, street type, and postal or zip code. While around the world addresses are represented in a range of different formats, each address consists of elements presented in a particular address format recognized by those in the region.

When using such a service, the location description needs to be an address passed in to the locator as attribute-value pairs, for example "Street" as the attribute and "400 Market street" as the value. Certain address fields may be required by the service while others may be optional, though in general providing a locator with more information as input will result in better ouput, that is more accurate locations found.

Performing geocoding using a Locator

In general to perform geocoding, use the key steps below:

In the
ArcGIS Runtime SDK for Java
you can perform reverse geocoding operations on both local and online services using a Locator instance. Instantiate the Locator class and provide the URL of the online or local geocoding service to the locator's constructor.
Specify input parameters for the locator.
Execute the geocoding task synchronously or asynchronously by calling a method on the locator instance.
Listen for the completion of the task and process the results.

Obtain the URL to the geocoding service

First, obtain the URL of the online or local geocoding service that will be used to perform the geocoding. The URL for an online service is just the REST endpoint, whereas 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 and successfully started.

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(); 
     } 
});

 
// example URL of a geocoding service which uses address fields:
String theGeocodeServiceURL = 
  "http://tasks.arcgisonline.com/ArcGIS/rest/services/Locators/TA_Streets_US/GeocodeServer";

// example URL of a geocoding service which does single line geocoding:
String singleLineGeocodeURL = 
  "http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer";

Instantiate the Locator

Instantiate the Locator class, passing in the geocode service's URL to the locator's constructor.

Instantiate the Locator passing in the local or online service URL

Locator locator = new Locator(theGeocodeServiceURL);

Geocode with a single line text input

If you are using a service which supports single line geocoding, you can provide a single line of text as the search string for a Locator's find (synchronous) or findAsync (asynchronous) method. For example, the single line search string could be an address such as "380 New York St, Redlands, CA 92373", the name of a place such as "Seattle, Washington", a point of interest like "Disneyland Paris", and more. This text input does not get passed directly to the Locator instance, but instead to a LocatorFindParameters instance. The code sample below shows how to create such an instance using the search string, how to set some additional parameters, and how to call the findAsync (or find for a synchronous call) on the locator:

 
LocatorFindParameters parameters = new LocatorFindParameters("380 New York St, Redlands, CA"); // search string
parameters.setMaxLocations(10); // number of results to return
parameters.setOutSR(map.getSpatialReference()); // the map's spatial reference

// call for single line geocoding: find or findAsync method
locator.findAsync(parameters, new CallbackListener<List<LocatorGeocodeResult>>() {
 
      @Override 
      public void onError(final Throwable e) {
        // handle the error
      }
 
      @Override
      public void onCallback(final List<LocatorGeocodeResult> results) {
						  // process the results
      };
});

You can also set as additional parameters a search point and a search distance, or neither. If these parameters are set, the locator will return results which are within the given distance away from the given point.

Geocode with address fields

If you are using a service which requires address components as input, create a HashMap containing the address fields and values that you wish to locate. Pass these address elements to the locator's addressToLocations (synchronous) or addressToLocationsAsync (asynchronous) method along with:

an array of the output field names. Passing an empty array will return all the output fields defined for the service.
the Well-Known ID (WKID) of a spatial reference that the location candidates will be projected to. If this is not set the locations will be returned in the spatial reference of the geocoding service. [Optional].

If you use the synchronous addressToLocations method, it will return the locations that match the address pattern in a List of LocalGeocodeResults. If you instead want to perform geocoding asynchronously, in the background, using the addressToLocationsAsync method, you need to include a CallbackListener in the method's parameters to capture and process the success or failure of the geocoding. The code sample below shows how you would use the asynchronous method:

 
Map<String, String> addressElements = new HashMap<String, String>(); 
addressElements.put("Street", "400 Market Street"); 
addressElements.put("City", "San Francisco"); 
addressElements.put("State", "CA"); 
addressElements.put("Zip", "94111");

// call for geocoding with address fields
locator.addressToLocationsAsync(addressElements, new ArrayList<String>(),
                                map.getSpatialReference().getLatestID(), 
                                new CallbackListener<List<LocatorGeocodeResult>>() { 
 
      @Override 
      public void onError(final Throwable e) { 
          // handle the error
      } 
 
      @Override 
      public void onCallback(final List<LocatorGeocodeResult> results) { 
						    // process the results
      }; 
           
});

Process the geocoding results

The results of all the Locator's geocoding methods discussed above are returned in a List of LocatorGeocodeResult objects. All that remains is for you to process this list to obtain the geographic location and the address at that location. The result with the highest score (the best match found for the input given) will be the first item in the List. The code sample below shows how to retrieve the highest scored result from the result list and use it to create a graphic to add to a graphics layer:

Process the first reult in the list

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

...

LocatorGeocodeResult highestScoreResult = results.get(0);

// create a graphic at this location 
Graphic addressGraphic = new Graphic(highestScoreResult.getLocation(), pointSymbol, attributes, null); 
 
theGraphicsLayer.addGraphic(addressGraphic);

Sample code

To view sample applications related to 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