HERE Android SDK Developer's Guide

Geocoding and Reverse Geocoding

Geocoding and reverse geocoding APIs from the HERE Android SDK allow application developers to offer search functionality for requesting location information and structured addresses. Geocoding APIs resolve to a GeoCoordinate from a text query, while reverse geocoding APIs resolve to a geographic data, such as Address, from a GeoCoordinate. Address provides textual address information, which includes house number, street name, city, country, and district. It encompasses everything about an address or a point on the map. Location represents a physical point on the map where additional attributes can be retrieved. These additional attributes include a unique identifier, label, Address, GeoCoordinate positions, and GeoBoundingBox for the Location.

The GeocodeRequest Class

GeocodeRequest represents an extended Request. GeocodeRequest can be created using a one-box (free-formatted text) search using a combination of a text query string and geographical area arguments. The following shows the method used to create a one-box request:

GeocodeRequest request = new GeocodeRequest(String).setSearchArea(GeoCoordinate, int)

The preceding method returns a GeocodeRequest object. To begin the search, call GeocodeRequest.execute(). This method requires a ResultListener as an argument. When the search is completed, the ResultListener.onCompleted() method is called with a result status and a list of found locations.

After a request is invoked, it can be canceled using the GeocodeRequest.cancel() method, which returns true if the request was cancelled successfully. For GeocodeRequest, a list of Location objects are expected at the completion of the request.

The following code example demonstrates how to perform a GeocodeRequest:

// Implementation of ResultListener
class GeocodeListener implements ResultListener<List<Location>> {
  @Override
  public void onCompleted(List<Location> data, ErrorCode error) {
    if (error != ErrorCode.NONE) {
      // Handle error
      ...
    } else {
      // Process result data
      ...
    }
  }
}

// Instantiate a GeoCoordinate object
GeoCoordinate vancouver = new GeoCoordinate( 49.2849,- 123.1252);

// Example code for creating a OneBox Request
ResultListener<List<Location>> listener = new GeocodeListener();
GeocodeRequest request = new GeocodeRequest("Granville").setSearchArea(vancouver, 5000);
if (request.execute(listener) != ErrorCode.NONE) {
  // Handle request error
  ...
}

The ReverseGeocodeRequest Class

The ReverseGeocodeRequest class represents an extended Request used to retrieve Address data. The request is created using a GeoCoordinate as shown below:

new ReverseGeocodeRequest(GeoCoordinate)

The above method returns a ReverseGeocodeRequest object. To invoke the request, you can then call the execute() method of the returned ReverseGeocodeRequest object and pass in a ResultListener to retrieve the information about the completion of the request. Once a request is invoked, the request can be cancelled via the ReverseGeocodeRequest.cancel() method. cancel() returns true if the request was cancelled successfully. For ReverseGeocodeRequest, a structured Address is expected at the completion of the request.

The following is an example of creating ReverseGeocodeRequest using new ReverseGeocodeRequest(GeoCoordinate):

// Implementation of ResultListener
class ReverseGeocodeListener implements ResultListener<Address> {
  @Override
  public void onCompleted(Address data, ErrorCode error) {
    if (error != ErrorCode.NONE) {
      // Handle error
      ...
    } else {
      // Process result data
      ...
    }
  }
}

// Instantiate a GeoCoordinate object
GeoCoordinate vancouver = new GeoCoordinate( 49.2849,- 123.1252);

// Example code for creating ReverseGeocodeRequest
ResultListener<Address> listener = new ReverseGeocodeListener();
ReverseGeocodeRequest request = new ReverseGeocodeRequest(vancouver);
if (request.execute(listener) != ErrorCode.NONE) {
  // Handle request error
  ...
}