Cuantos más detalles proporcione acerca de una dirección, más precisos serán los resultados. Por ejemplo, si sólo proporciona la dirección de una calle, es posible que el servidor de codificación geográfica devuelva un número alto de resultados. Sin embargo, si proporciona suficiente contexto geográfico en la solicitud, podrá proporcionar menos datos acerca de la dirección. La cadena de dirección no estructurada no siempre proporciona los mismos resultados que una dirección estructurada.

// Structured address
MapLocation address1 = new MapLocation();
address1.addData(MapLocation.LBS_LOCATION_CITY_KEY, "waterloo");
address1.addData(MapLocation.LBS_LOCATION_COUNTRY_KEY, "canada");
address1.addData(MapLocation.LBS_LOCATION_STREET_ADDRESS_KEY, "419 phillip st");
address1.addData(MapLocation.LBS_LOCATION_POSTAL_CODE_KEY, "N2L3X2");
// Unstructured address
String address2 = new String("419 phillip st, waterloo, canada, N2L3X2");

Es recomendable que proporcione el contexto desde su aplicación. Si su aplicación no proporciona contexto suficiente en una solicitud, la aplicación podría recibir resultados de búsqueda irrelevantes. Cuando crea un objeto MapDimensions para su uso en solicitudes de codificación geográfica, los valores de anchura, altura, zoom y rotación no son importantes.

MapPoint origin = new MapPoint(43.4815, -80.5407);
MapDimensions context = new MapDimensions(origin, 480, 360, 5, 0);

Al enviar una solicitud de codificación geográfica asíncrona, debe pasar una referencia a la clase que implementa la interfaz ServerExchangeCallback (representada por la variable callback en el siguiente ejemplo de código). Asimismo, debe proporcionar la dirección, el contexto geográfico de la solicitud (por ejemplo, la ubicación actual del usuario) y el tiempo que puede transcurrir antes de que la solicitud caduque. Al invocar Geocoder.geocode(), la aplicación envía la solicitud al servidor de codificación geográfica y llama al método ServerExchangeCallback apropiado cuando obtiene un resultado.

MyServerExchangeCallback callback = new MyServerExchangeCallback();
try
{
    Geocoder.getInstance().geocode(callback, address1, context, 0);
} 
catch (GeocodeException e)
{
    // Do something with the exception
}

Una solicitud correcta de codificación geográfica devuelve un objeto GeocodeExchange que contiene un Vector de resultados de búsqueda a los que pude acceder invocando GeocodeExchange.getResults(). Cada uno de los índices de Vector contiene un objeto net.rim.device.api.lbs.maps.model.MapLocation con detalles acerca de una ubicación, como un nombre para mostrar, una descripción, las coordenadas y la dirección. Si recibe varios resultados, el resultado más relevante se encuentra en el primer índice de Vector.

public class MyServerExchangeCallback implements ServerExchangeCallback
{
    public void requestSuccess(ServerExchange exchange)
    {
        if(exchange instanceof GeocodeExchange)
        {
            GeocodeExchange geocodeExchange = (GeocodeExchange)exchange;
            Vector results = geocodeExchange.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
    }
}

Para las solicitudes de codificación geográfica síncronas, no es necesario que su aplicación implemente la interfaz ServerExchangeCallback. Para iniciar una solicitud de codificación geográfica síncrona, debe especificar null en lugar de pasar una referencia a una clase que implemente ServerExchangeCallback. Cuando ejecute una solicitud de codificación geográfica síncrona, deberá comprobar el resultado de la solicitud manualmente. Normalmente, deberá ejecutar las solicitudes de codificación geográfica síncronas en un subproceso diferente del subproceso de la interfaz de usuario ya que, de lo contrario, los usuarios no podrán interactuar con la interfaz de usuario durante la solicitud.

GeocodeExchange exchange = Geocoder.getInstance().geocode
        (null, address2, context, 0);
// Check if the request was successful
if(exchange.getExceptionList().size() == 0)
{
    // Do something with the result of the request
}
else
{
    // Inform the user of the failure
}