Retrieving an address for geographic coordinates by using reverse geocoding

Development Guide

Search This Document

Download PDF

Your application can use the ReverseGeocoder class to retrieve a human-readable name for a location, such as a street address, city, or country, by using a set of geographic coordinates.

When you send a reverse geocoding request, you can specify the administrative boundary that you want to receive information for (for example, street address, city, or country). The ReverseGeocodeExchange class contains the following constants that you can use to specify the level of administrative boundary.

ADDRESS: Returns the street address.
CITY: Returns the city.
COUNTRY: Returns the country.
MCC: Returns the mobile country code.
POSTAL: Returns the postal code or zip code.
PROVINCE_STATE: Returns the province or state.
TIME_ZONE_ID: Returns the time zone.

In situations that prwhereecision is essential, you might want to request a street address. In other situations, you might only need the city or country name.

There might be cases where your application sends a reverse geocoding request but doesn't receive the expected data in return. For example, if your application sends a request using the ADDRESS administrative boundary, and the geographic location is outside the city limits, the reverse geocoding server might not be able to locate a specific street address. In this case, only the state or province name might be returned to the application.

The results of reverse geocoding requests are added to a cache on the device, except when the request was for a precise street address. When you initiate a reverse geocoding request, the application checks the cache for previous search results before it makes a call to the server, except in those cases that you request a specific address. Reverse geocoding requests can be synchronous or asynchronous.

Specifying the geographic coordinates for a location

To retrieve a location name for geographic coordinates, you need to create a MapPoint object that contains the geographic coordinates.

MapPoint location = new MapPoint(43.4815, -80.5407);

Sending an asynchronous reverse geocoding request

When you send an asynchronous reverse geocoding request, you must pass in a reference to a class that implements the ServerExchangeCallback interface (represented by the callback variable in the following example). You must also specify the coordinates of the location, the administrative boundary, the bearing of the device, and the length of time before the request times out. When you invoke ReverseGeocoder.reverseGeocode(), the application sends the request to the geocoding server and calls the appropriate ServerExchangeCallback method when it has a result.

int bearing = 1;
int timeout = 0;
MyServerExchangeCallback callback = new MyServerExchangeCallback();

try
{
    ReverseGeocoder.getInstance().reverseGeocode(callback, location, 
            ReverseGeocodeExchange.ADDRESS, bearing, timeout);
} 
catch (ReverseGeocodeException e)
{
    // Do something with the exception
}

To create a class that implements the ServerExchangeCallback interface, there are three methods that you must include: requestSuccess(), requestFailure(), and requestHalted(). When a reverse geocoding request is completed, your application invokes one of these methods depending on the result of the request.

A successful reverse geocoding request returns a ReverseGeocodeExchange object which contains a Vector of search results that you can access by invoking ReverseGeocodeExchange.getResults(). The Vector contains a net.rim.device.api.lbs.maps.model.MapLocation object that has details about a location, such as the location name, a description, and the coordinates. For the complete list of properties, see the MapLocation class.

public class MyServerExchangeCallback implements ServerExchangeCallback
{
    public void requestSuccess(ServerExchange exchange)
    {
        if(exchange instanceof ReverseGeocodeExchange)
        {
            // Casts the Exchange object to a ReverseGeocodeExchange 
            // object and retrieves the Vector of results.
            ReverseGeocodeExchange reverseGeocodeExchange = 
                    (ReverseGeocodeExchange)exchange;
            Vector results = reverseGeocodeExchange.getResults();

            // Do something with the results
        }
    }

    public void requestFailure(ServerExchange exchange)
    {
        // Inform the user of the failure
    }

    public void requestHalted()
    {
        // Invoked when the request is stopped
    }
}

Sending a synchronous reverse geocoding request

For synchronous reverse geocoding requests, your application does not have to implement the ServerExchangeCallback interface. To initiate a synchronous geocoding request, you must specify null as the argument instead of passing in a reference to a class that implements ServerExchangeCallback. When you run a synchronous geocoding request, you must verify the result of the request manually. Typically, you should run synchronous geocoding requests on a thread other than the UI thread, otherwise users won't be able to interact with the UI during the request.

try
{ 
    ReverseGeocodeExchange exchange = ReverseGeocoder.getInstance().reverseGeocode(
            callback, location, ReverseGeocodeExchange.ADDRESS, bearing, timeout);
                    
    // Check if the request was successful
    if(exchange.getExceptionList().size() == 0)
    {
        if(exchange instanceof ReverseGeocodeExchange)
        {
            // Casts the Exchange object to a ReverseGeocodeExchange 
            // object and retrieves the Vector of results.
	           ReverseGeocodeExchange reverseGeocodeExchange = 
                    (ReverseGeocodeExchange)exchange;
            Vector results = reverseGeocodeExchange.getResults();

            // Do something with the results
        }
    }
    else
    {
        // Inform the user of the failure
    }
}
catch(GeocodeException e)
{
    // Do something with the exception
}

Next topic: Code sample: Retrieving geographic coordinates for an address by using geocoding

Previous topic: Code sample: Retrieving an address by using geospatial coordinates and reverse geocoding

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation