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 ReverseGeocodeRequest2 Class

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

new ReverseGeocodeRequest2(GeoCoordinate)

The above method returns a ReverseGeocodeRequest2 object. To invoke the request, you can then call the execute() method of the returned ReverseGeocodeRequest2 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 canceled via the ReverseGeocodeRequest2.cancel() method. cancel() returns true if the request was cancelled successfully. For ReverseGeocodeRequest2, a structured Location is expected at the completion of the request.

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

// Implementation of ResultListener
class ReverseGeocodeListener implements ResultListener<Location> {
  @Override
  public void onCompleted(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 ReverseGeocodeRequest2
ResultListener<Location> listener = new ReverseGeocodeListener();
ReverseGeocodeRequest2 request = new ReverseGeocodeRequest2(vancouver);
if (request.execute(listener) != ErrorCode.NONE) {
  // Handle request error
  ...
}

By default, the reverse geocode request above searches for the closest street address. Alternatively, you can also create a reverse geocoding request in one of the following modes (ReverseGeocodeMode):

  • RETRIEVE_ADDRESSES - Search for the closest street address or addresses (same as above)
  • RETRIEVE_AREAS - Retrieve the administrative area information for the position provided in the request
  • RETRIEVE_LANDMARKS - Search for landmarks like parks and lakes in the proximity provided in the request
  • RETRIEVE_ALL - Search for streets, administrative areas and landmarks. This mode aggregates the results of the previous three modes in one call
  • TRACK_POSITION - Retrieve street and address information based on a position and bearing

See the following for an example of how to use this type of request. Note that the bearing parameter is only used when you use TRACK_POSITION.

ResultListener<Location> listener = new ReverseGeocodeListener();
ReverseGeocodeRequest2 request = new ReverseGeocodeRequest2(geoCoord, null, RETRIEVE_ADDRESSES, bearing);
if (request.execute(listener) != ErrorCode.NONE)
{
  // Handle request error ...
}

Offline Geocoding

Applications developed with the HERE Android SDK can perform offline geocoding, which allows geocode and reverse geocode requests to be performed without an active data connection. This is performed automatically when an active data connection is not available and when the map and database information have already been downloaded and cached.