Je mehr Details Sie für eine Adresse angeben, desto genauer können die Ergebnisse sein. Wenn Sie zum Beispiel nur eine Adresse angeben, gibt der Geocoding-Server möglicherweise eine große Zahl von Ergebnissen zurück. Wenn Sie mit Ihrer Anforderung aber ausreichenden geografischen Kontext bereitstellen, kann es ausreichen, wenn Sie weniger Informationen zur Adresse angeben. Die unstrukturierte Adresszeichenfolge stellt nicht immer die gleichen Ergebnisse bereit, wie eine strukturierte Adresse.

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

Als bewährtes Verfahren sollten Sie den Kontext aus Ihrer Anwendung bereitstellen. Wenn Ihre Anwendung keinen ausreichenden Kontext mit einer Anforderung bereitstellt, kann Ihre Anwendung u. U. irrelevante Suchergebnisse empfangen. Wenn Sie ein MapDimensions-Objekt erstellen, das mit Geokodierungs-Anforderungen verwendet wird, sind die Werte für Breite, Höhe, Vergrößerung und Drehung unwichtig.

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

Wenn Sie eine asynchrone Geokodierungs-Anforderung senden, müssen Sie einen Hinweis auf die Klasse übergeben, die die ServerExchangeCallback-Schnittstelle implementiert (im folgenden Codebeispiel durch die callback-Variable dargestellt). Sie müssen auch die Adresse, den geografischen Kontext (z. B. den aktuellen Standort des Benutzers) und die Dauer der Zeitüberschreitung für die Anfrage angeben. Wenn Sie Geocoder.geocode() aufrufen, sendet die Anwendung die Anforderung an den Geokodierungs-Server und ruft die entsprechende ServerExchangeCallback-Methode auf, wenn ein Ergebnis vorliegt.

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

Eine erfolgreiche Geokodierungs-Anforderung gibt ein GeocodeExchange-Objekt zurück, das einen Vector von Suchergebnissen enthält, auf den Sie durch Aufrufen von GeocodeExchange.getResults() zugreifen können. Jeder Index innerhalb des Vector enthält ein net.rim.device.api.lbs.maps.model.MapLocation-Objekt mit Details zu einem Standort, wie z. B. ein Anzeigename, eine Beschreibung, die Koordinaten und die Adresse. Wenn Sie mehrere Ergebnisse empfangen, befindet sich das relevanteste Ergebnis im ersten Index des 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
    }
}

Für synchrone Geokodierungs-Anforderungen muss Ihre Anwendung die ServerExchangeCallback-Schnittstelle nicht implementieren. Um eine synchrone Geokodierungs-Anforderung zu initiieren, müssen Sie null angeben, statt einen Hinweis auf eine Klasse zu übergeben, die ServerExchangeCallback implementiert. Wenn Sie eine synchrone Geokodierungs-Anforderung ausführen, müssen Sie das Ergebnis der Anforderung manuell überprüfen. In der Regel sollten Sie synchrone Geokodierungs-Anforderungen auf einem Thread ausführen, der nicht dem Benutzeroberflächen-Thread entspricht, da andernfalls Benutzer während der Anforderung nicht mit der Benutzeroberfläche interagieren können.

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
}