Installation

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 gradle.properties 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/gradle.properties. You can read more about Gradle properties in the official Gradle documentation.
2. Add your secret token your gradle.properties file:

MAPBOX_DOWNLOADS_TOKEN=PASTE_YOUR_SECRET_TOKEN_HERE

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.

Add search to an app

import android.app.Application
import com.mapbox.search.MapboxSearchSdk
import com.mapbox.search.location.DefaultLocationProvider
 
class SearchApplication : Application() {
 
override fun onCreate() {
super.onCreate()
MapboxSearchSdk.initialize(
this,
getString(R.string.mapbox_access_token),
DefaultLocationProvider(this)
)
}
}

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<application
android:name=".SearchApplication"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme"
>
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>

<?xml version="1.0" encoding="utf-8"?>
<androidx.coordinatorlayout.widget.CoordinatorLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
>
 
<com.mapbox.search.ui.view.SearchBottomSheetView
android:id="@+id/search_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:elevation="8dp"
/>
 
</androidx.coordinatorlayout.widget.CoordinatorLayout>

import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat
import com.mapbox.search.ui.view.SearchBottomSheetView
 
class MainActivity : AppCompatActivity() {
 
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
 
val searchBottomSheetView = findViewById<SearchBottomSheetView>(R.id.search_view)
searchBottomSheetView.initializeSearch(savedInstanceState, SearchBottomSheetView.Configuration())
 
if (!isPermissionGranted(Manifest.permission.ACCESS_FINE_LOCATION)) {
ActivityCompat.requestPermissions(
this,
arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
PERMISSIONS_REQUEST_LOCATION
)
}
}
 
private companion object {
private const val PERMISSIONS_REQUEST_LOCATION = 0
 
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: