Migrate from Java SDK's Geocoder

Additional Developer Resources

The Mapbox Search SDK for Android is the recommended way to access the Mapbox Geocoding API on the Android platform. If you've used the Java SDK's Geocoder to integrate search functionality into an existing application, you should switch to Search SDK.

This guide describes the steps required for seamless migration from the Java SDK's Geocoder to the Search SDK v1.

Batch geocoding is not supported in the Search SDK

If your application relies on the Geocoder's batch geocoding functionality, you should continue using the Java SDK's Geocoder.

Requirements

You can find the Search SDK requirements in the Requirements section of the guides.

Installation

You can find the definitive instructions on how to configure the Search SDK in your project in the Search SDK installation guide.

Forward geocoding

Forward geocoding converts location text into geographic coordinates, for example turning "2 Lincoln Memorial Circle NW" into -77.050,38.889.

Java SDK's Geocoder

To retrieve a geographic coordinate based on location text using the Java SDK's Geocoder:


// Set up a MapboxGeocoding object with a Mapbox access token
// and a String query
MapboxGeocoding geocoding = MapboxGeocoding.builder()
    .accessToken(MAPBOX_ACCESS_TOKEN)
    .query("Washington")
    .limit(5)
    .build();
// Execute the forward geocoding request
geocoding.enqueueCall(callback);

Search SDK for Android

To retrieve a geographic coordinate using the Search SDK, start by searching for suggestions with a SearchEngine.search(query: String, options: SearchOptions, executor: Executor, callback: SearchSuggestionsCallback) call:

Java

Kotlin

Java

Kotlin



SearchEngine searchEngine = SearchEngine.createSearchEngine(settings);
SearchOptions options = new SearchOptions.Builder()
    .limit(5)
    .build();
searchEngine.search("Washington", options, searchCallback);

Java

Kotlin



val searchEngine = SearchEngine.createSearchEngine(settings)
val options = SearchOptions(
    limit = 5
)
searchEngine.search("Washington", options, searchCallback)

A list of suggestions will be passed to the searchCallback.onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) callback method. If you want to retrieve information about the location of specific suggestion, then you should additionally invoke SearchEngine.select():

Java

Kotlin

Java

Kotlin



final SearchSelectionCallback searchCallback = new SearchSelectionCallback() {

    // ...

    @Override
    public void onSuggestions(
        @NonNull List<? extends SearchSuggestion> suggestions, 
        @NonNull ResponseInfo responseInfo
    ) {
        if (suggestions.isEmpty()) {
            Log.i("SearchApiExample", "No suggestions found");
        } else {
            SearchSuggestion suggestion = suggestions.get(0);
            Log.i(TAG, "Search suggestion: " + suggestion)
            task = searchEngine.select(suggestion, this);
        }
    }

    @Override
    public void onResult(
        @NonNull SearchSuggestion suggestion, 
        @NonNull SearchResult result, 
        @NonNull ResponseInfo info
    ) {
        Point location = result.getCoordinate();
        Log.i(TAG, "Search result's location: " + location);
    }

    @Override
    public void onError(@NonNull Exception e) {
        Log.i(TAG, "Search error: ", e);
    }
};

Java

Kotlin



val searchCallback = object : SearchSelectionCallback {

    // ...

    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
        val suggestion = suggestions.firstOrNull()
        if (suggestions.isEmpty()) 
            Log.i(TAG, "No search suggestions found")
        } else {
            val suggestion = suggestions.first()
            Log.i(TAG, "Search suggestion: $suggestion")
            searchEngine.select(suggestion, this)
        }
    }

    override fun onResult(
        suggestion: SearchSuggestion,
        result: SearchResult,
        responseInfo: ResponseInfo
    ) {
        val location = result.coordinate
        Log.i(TAG, "Search result's location: $location")
    }

    override fun onError(e: Exception) {
        Log.i(TAG, "Search error", e)
    }
}

EXAMPLE

Search example

Forward geocoding allows you to search for places by name.

Reverse geocoding

Reverse geocoding turns geographic coordinates into place names, for example turning -77.050, 38.889 into "2 Lincoln Memorial Circle NW". These location names can vary in specificity, from individual addresses to states and countries that contain the given coordinates.

Java SDK's Geocoder

To retrieve one or more place names at a geographic coordinate using the Java SDK's Geocoder:


// Set up a MapboxGeocoding object with a Mapbox access token
// and a Point query
MapboxGeocoding geocoding = MapboxGeocoding.builder()
    .accessToken(MAPBOX_ACCESS_TOKEN)
    .query(Point.fromLngLat(2.294434, 48.858349))
    .limit(1)
    .build();
// Execute the reverse geocoding request
geocoding.enqueueCall(callback);

Search SDK for Android

To retrieve one or more location names at a geographic coordinate using the Search SDK, use a SearchEngine.search(options: ReverseGeoOptions, executor: Executor, callback: SearchCallback) call:

Java

Kotlin

Java

Kotlin



SearchEngine searchEngine = SearchEngine.createSearchEngine(settings);
ReverseGeoOptions options = new ReverseGeoOptions.Builder(Point.fromLngLat(2.294434, 48.858349))
    .limit(1)
    .build();
searchEngine.search(options, reverseGeoCallback);

Java

Kotlin



val searchEngine = SearchEngine.createSearchEngine(settings)
val options = ReverseGeoOptions(
    center = Point.fromLngLat(2.294434, 48.858349),
    limit = 1
)
searchEngine.search(options, reverseGeoCallback)