Geocoding and Reverse Geocoding

Geocoding and Reverse Geocoding Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/.

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, ResultListener.onCompleted() method is called with a result status and a list of found locations.

After a request is invoked, it can be canceled via 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<GeocodeResult>> {
  @Override
  public void onCompleted(List<GeocodeResult> 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<GeocodeResult>> 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 Location 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 canceled via the ReverseGeocodeRequest.cancel() method. cancel() returns true if the request was canceled successfully. For ReverseGeocodeRequest a structured Location 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<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 ReverseGeocodeRequest
ResultListener<Location> listener = new ReverseGeocodeListener();
ReverseGeocodeRequest request = new ReverseGeocodeRequest(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();
ReverseGeocodeRequest request = new ReverseGeocodeRequest(geoCoord, RETRIEVE_ADDRESSES, bearing);
if (request.execute(listener) != ErrorCode.NONE)
{
  // Handle request error ...
}

Offline Geocoding

Applications developed with SDK for Android 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 has already been downloaded and cached.