Recuperar coordenadas geográficas de um endereço usando geocodificação

Seu aplicativo pode usar a classe Geocoder para recuperar as coordenadas geográficas de um endereço. Por exemplo, seu aplicativo pode solicitar ao usuário um endereço e então exibir o endereço em um mapa. O endereço pode estar na forma de uma string sem estrutura, ou um objeto MapLocation. As solicitações de geocodificação podem ser síncronas ou assíncronas.

Especificar um endereço

Quanto mais detalhes você fornecer sobre um endereço, mais exatos poderão ser os resultados. Por exemplo, se você fornecer somente o nome da rua, o servidor de Geocodificação talvez retorne um grande número de resultados. No entanto, se você fornecer contexto geográfico suficiente com sua solicitação, poderá fornecer menos informações sobre o endereço. A string de endereço sem estrutura nem sempre fornece os mesmos resultados que um endereço estruturado.
// 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");

Fornecer contexto geográfico com o endereço

Para ajudar o servidor de geocodificação a retornar os resultados mais relevantes, você deve fornecer contexto geográfico com sua solicitação de geocodificação. Para fornecer contexto, você poderá criar um objeto MapDimensions que contém coordenadas geográficas (por exemplo, a localização atual do usuário do aparelho BlackBerry). Ao fornecer contexto, seu aplicativo poderá receber coordenadas geográficas relevantes mesmo que um usuário forneça somente o nome da rua. Se você não fornecer um objeto MapDimensions, seu aplicativo pode usar a última localização salva no BlackBerry Maps como contexto, o que pode não fornecer os resultados que você deseja.

Como uma prática recomendada, você deve fornecer contexto a partir de seu aplicativo. Se seu aplicativo não fornecer contexto suficiente com uma solicitação, ele pode receber resultados de pesquisa irrelevantes. Quando você cria um objeto MapDimensions para usar com solicitações de geocodificação, os valores de largura, altura, zoom e rotação não são importantes.
MapPoint origin = new MapPoint(43.4815, -80.5407);
MapDimensions context = new MapDimensions(origin, 480, 360, 5, 0);

Enviar uma solicitação assíncrona de geocodificação

Quando você envia uma solicitação assíncrona de geocodificação, você deve passar em uma referência à classe que implementa a interface ServerExchangeCallback (representada pela variável callback no exemplo de código a seguir). Você também deve fornecer o endereço, o contexto geográfico da solicitação (por exemplo, a localização atual do usuário) e o período de tempo antes do qual a solicitação expirará. Quando você chama Geocoder.geocode(), o aplicativo envia a solicitação ao servidor de geocodificação e chama o método ServerExchangeCallback apropriado quando tem um resultado.
MyServerExchangeCallback callback = new MyServerExchangeCallback();
try
{
    Geocoder.getInstance().geocode(callback, address1, context, 0);
} 
catch (GeocodeException e)
{
    // Do something with the exception
}

Para criar uma classe que implementa a interface ServerExchangeCallback, há três métodos que você deve incluir em seu aplicativo: requestSuccess(), requestFailure() e requestHalted(). Quando uma solicitação de geocodificação é concluída, seu aplicativo chama um desses métodos, dependendo do resultado da solicitação.

Uma solicitação bem-sucedida de geocodificação retorna um objeto GeocodeExchange que contém um Vector de resultados de pesquisa que você pode acessar chamando GeocodeExchange.getResults(). Cada índice no Vector contém um objeto net.rim.device.api.lbs.maps.model.MapLocation que apresenta detalhes sobre uma localização, tal como um nome de exibição, uma descrição, as coordenadas e o endereço da rua. Se você receber diversos resultados, o resultado mais relevante estará localizado no primeiro índice do 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
    }
}

Enviar uma solicitação de geocodificação reversa síncrona

Para solicitações síncronas de geocodificação, seu aplicativo não precisa implementar a interface ServerExchangeCallback. Para iniciar uma solicitação síncrona de geocodificação reversa, você deve especificar null em vez de passar uma referência a uma classe que implementa ServerExchangeCallback. Ao executar uma solicitação síncrona de geocodificação, você deve verificar o resultado da solicitação manualmente. Geralmente, você deve executar solicitações síncronas de geocodificação em um thread diferente do thread da UI, senão os usuários não poderão interagir com a UI durante a solicitação.
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
}

Estas informações foram úteis? Gostaríamos de receber seus comentários.