Search SDK for Android

Search SDK for Android

Current version: v1.0.0-beta.1

  • Add pre-built UI components to your app
  • Search for places by name, category, or coordinate
  • Save your favorite places
  • Access your search history

The Mapbox Search SDK for Android gives you the tools you need to add a search experience to your application. It takes only a few minutes to drop a pre-built user interface (UI) powered by the Mapbox Geocoding API into your application. We also make the core search logic that powers the UI available to you directly so you can build something truly custom.

Structure of the Search SDK

The Search SDK consists of Search Core and the Search UI SDK.

Search Core

Search Core contains the logic that automatically handles configuring, sending, and parsing responses to requests. This code automatically integrates with the device to access its location and language settings and caches results on-device. It also powers the Search UI SDK.

Search UI SDK

The Search UI SDK is built on top of Search Core and provides ready-made search UI elements that you can use to add a search experience to your app. You can adjust the style of various elements of the pre-configured UI and customize results.

Search types

The Search SDK offers single-box search, which allows you to search by either place name, address, or category. There are two search engines available in single-box search:

  • Search: The SearchEngine class allows you to get the location of places by typing place names or addresses. This is also known as forward geocoding. For example, you can type in Lincoln Memorial and retrieve the geographic location of a place that matches that query (-77.050,38.889).
  • Category search: The CategorySearchEngine class allows you to select a category (for example, restaurants) and retrieve a list of points of interest (POIs) that belong to that category. For example, if you want to display many restaurants within walking distance of a theater on a map, you can use category search with the restaurants category.

Reverse geocoding

The Search SDK also offers the ReverseGeocodingSearchEngine class to perform reverse geocoding. Reverse geocoding allows you to search for place names and addresses by providing geographic coordinates. For example, entering -77.050, 38.889 and retrieve 2 Lincoln Memorial Circle NW.

History and favorites

If a user has searched in your app before, the Search SDK will always suggest results from their search history. If the user also has a list of favorite search results, the SDK will suggest recent results as well as any favorites that match the query.


History is a list of the most recent search results selected on a device. The Search SDK automatically adds to a user’s history every time a result is selected.

The Search UI SDK uses history in two ways:

  • When a user clicks on the empty search bar the SDK will automatically show recent searches in reverse chronological order. When a- user starts to type a query the SDK will use the history to populate the suggestions drop down.

You can also access a device’s history via Search Core by obtaining HistoryDataProvider from MapboxSearchSdk.serviceProvider.historyDataProvider().


Favorites is a list of past searches that a user has explicitly added to the list.

The Search UI SDK uses favorites in two ways:

  • Users can click the star icon in the list of results to open the favorites menu where they can save the place.
  • The user can manage their favorites through the “Favorites” component option where they can remove or rename their favorites.

You can also access a device’s favorites via Search Core by obtaining FavoritesDataProvider from MapboxSearchSdk.serviceProvider.favoritesDataProvider().


The Mapbox Search SDK for Android works with:

  • Android 4.4+ (API 19)
  • Architectures: armeabi-v7a, arm64-v8a, x86, x86_64
  • Kotlin 1.3 or newer

Install the Search SDK

To use the Search SDK, you'll need to configure your credentials and add the SDK as a dependency.

Configure credentials

Before installing the SDK, you will need to gather the appropriate credentials. The SDK requires two pieces of sensitive information from your Mapbox account. If you don't have a Mapbox account: sign up and navigate to your Account page. You'll need:

  • A public access token: From your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token.
  • A secret access token with the Downloads:Read scope.
    1. From your account's tokens page, click the Create a token button.
    2. From the token creation page, give your token a name and make sure the box next to the Downloads:Read scope is checked.
    3. Click the Create token button at the bottom of the page to create your token.
    4. The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and take advantage of Gradle properties to make sure they're only added when your app is compiled. Once this configuration step has been completed, you will be able to reference your credentials in other parts of your app.

Configure your secret token

To avoid exposing your secret token, add it as an environment variable:

  1. Find or create a file in your Gradle user home folder. The folder can be found at «USER_HOME»/.gradle. Once you have found or created the file, its path should be «USER_HOME»/.gradle/ You can read more about Gradle properties in the official Gradle documentation.
  2. Add your secret token your file:

Configure your public token

There are many ways to configure your public access token. Many of the examples and code snippets on this site assume your token is stored in a file in your project with other string values. If you would like to manage your public access token this way, open your project's R.strings.xml file and add the following string resource:

<string name="mapbox_access_token">MAPBOX_ACCESS_TOKEN</string>

If you ever need to rotate your access token, you will need to update the token value in your R.strings.xml file.

Configure permissions

You can use the Manifest merge feature to reduce the need to include any SDK requirements in your application's manifest file. You'll need to add either the Fine or Coarse location permission if you plan to display a user's location on the map or get the user's location information. The user location permission should also be checked during runtime using the PermissionsManager.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Add the dependency

Mapbox provides the Search SDK via Maven.

To add the Search SDK as a dependency, you will need to configure your build to download the Search SDK from Mapbox directly. This requires a valid username and password.

  1. Open your project in Android Studio.

  2. Open up your module-level build.gradle file.

  3. The Search SDK uses Java 8 features. To enable Java 8 in your project, add the following compileOptions:

    android {
      // Configure only for each module that uses Java 8
      // language features (either in its source code or
      // through dependencies).
      compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
      // For Kotlin projects
      kotlinOptions {
        jvmTarget = "1.8"
  4. Make sure that your project's minSdkVersion is at API 19 or higher.

    android {
      defaultConfig {
          minSdkVersion 19
  5. Add the dependency under dependencies. There are two options:

    • Option 1: To use the Search SDK with pre-built UI components, add the Search UI SDK (mapbox-search-android-ui) dependency. This will also include Search Core (mapbox-search-android) automatically.

      dependencies {
        implementation ""
    • Option 2: To use the Search SDK without pre-built UI components, add the Search Core (mapbox-search-android) dependency.

      dependencies {
        implementation ""
  6. Open up your project-level build.gradle file. Declare the Mapbox Downloads API's v2/releases/maven endpoint in the repositories block. To download the Search SDK, you must authenticate your request with a valid username and password. In the previous section, you added your secret token as a password in the file in your Gradle user home folder.

    allprojects {
      repositories {
        maven {
          url ''
          authentication {
          credentials {
            // Do not change the username below.
            // This should always be `mapbox` (not your username). 
            username = "mapbox"
            // Use the secret token you stored in as the password
            password =['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
  7. Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

Add search to an app

Create a new Application in your Android Studio project and add the code below:

class SearchApplication : Application() {
override fun onCreate() {

Open the activity's XML manifest file. Set permissions and reference the name of the Application you created in the last step:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<activity android:name=".MainActivity">
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />

Open the activity's XML layout file and add the following view:

<?xml version="1.0" encoding="utf-8"?>

Create a new Activity or open an existing Activity and add the code below:

import android.Manifest
import android.content.Context
import android.os.Bundle
import androidx.core.content.ContextCompat
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
val searchBottomSheetView = findViewById<SearchBottomSheetView>(
searchBottomSheetView.initializeSearch(savedInstanceState, SearchBottomSheetView.Configuration())
if (!isPermissionGranted(Manifest.permission.ACCESS_FINE_LOCATION)) {
private companion object {
fun Context.isPermissionGranted(permission: String): Boolean {
return ContextCompat.checkSelfPermission(this, permission) == PackageManager.PERMISSION_GRANTED

Run your application and you will see a functional search UI. Begin typing in the search bar to see results:


Search SDK usage is measured in Temporary Geocoding API requests. See our pricing page for more details.

Was this page helpful?