Pour des résultats plus précis, veillez à fournir le plus d'informations possible. Par exemple, si vous fournissez uniquement un nom de voie, le serveur de géocodage risque de renvoyer de nombreux résultats. Toutefois, si vous fournissez un contexte géographique suffisant pour votre requête, vous n'êtes pas obligé de fournir beaucoup d'informations relatives à l'adresse. La chaîne d'une adresse non structurée ne fournit pas toujours les mêmes résultats qu'une adresse structurée.

// 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");

Il vous est donc recommandé de fournir le contexte depuis votre application. Si votre application ne fournit pas de contexte suffisant pour la requête, elle risque de recevoir des résultats de recherche non pertinents. Lorsque vous créez un objet MapDimensions à utiliser avec les requêtes de géocodage, les valeurs de largeur, hauteur, zoom et rotation sont insignifiantes.

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

Lorsque vous envoyez une requête de géocodage asynchrone, vous devez transmettre une référence à la classe qui met en œuvre l'interface ServerExchangeCallback, représentée par la variable callback dans l'échantillon de code suivant. Vous devez également fournir l'adresse, le contexte géographique de la requête (par exemple, la position actuelle de l'utilisateur) et le délai avant arrivée à expiration de la requête. Lorsque vous appelez Geocoder.geocode(), l'application envoie la requête au serveur de géocodage et appelle la méthode ServerExchangeCallback appropriée en la présence d'un résultat.

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

Lorsqu'une requête de géocodage aboutit, elle renvoie un objet GeocodeExchange contenant un objet Vector de résultats de recherche, auquel vous pouvez accéder en appelant GeocodeExchange.getResults(). Chaque index de l'objet Vector contient un objet net.rim.device.api.lbs.maps.model.MapLocation disposant d'informations concernant une position, telles que le nom affiché, une description, les coordonnées et l'adresse. Si vous recevez plusieurs résultats, le résultat le plus pertinent se trouve dans le premier index de l'objet 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
    }
}

Pour les requêtes de géocodage synchrone, votre application n'est pas contrainte de déployer l'interface ServerExchangeCallback. Pour établir une requête de géocodage synchrone, vous devez indiquer null au lieu de transmettre une référence à une classe déployant ServerExchangeCallback. Lorsque vous exécutez une requête de géocodage synchrone, vous devez en vérifier le résultat manuellement. Généralement, vous devez exécuter les requêtes de géocodage synchrone sur un thread autre que le thread d'interface utilisateur. Sinon, les utilisateurs ne pourront pas interagir avec l'interface utilisateur pendant la requête.

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
}