Beta
Search SDK for Android

Migrate from Geocoder

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

  • Android SDK 5.0+ (API 21+)
  • Kotlin 1.4 or newer
  • Java 8 language features support should be declared in project's build.gradle file (Geocoder targets Java 7 as minimum supported language version)
android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8.toString()
    }
}

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

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

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

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)
searchRequestTask = 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);
}
};
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 ReverseGeocodingSearchEngine.search() call:

ReverseGeocodingSearchEngine reverseEngine = MapboxSearchSdk.getReverseGeocodingSearchEngine();
ReverseGeoOptions options = new ReverseGeoOptions.Builder(Point.fromLngLat(2.294434, 48.858349))
.limit(1)
.build();
reverseEngine.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.