Skip to main content

Migrate from Java SDK's Geocoder

Join the Mapbox Developers Discord Communityarrow-right

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:

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():

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.

chevron-right

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:

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

Reverse geocoding allows you to enter a geographic coordinate and receive the name of one or more places that exist at that location.

chevron-right
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?