All docschevron-rightSearch SDK for Androidchevron-rightarrow-leftGuideschevron-rightGet Started

Get Started

To use any of the Search SDK components, 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, replacing YOUR_MAPBOX_ACCESS_TOKEN with your public Mapbox API token:

<string name="mapbox_access_token">YOUR_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

If you plan to display the user's location on the map or get the user's location information you will need to add the ACCESS_COARSE_LOCATION permission in your application's AndroidManifest.xml. You also need to add ACCESS_FINE_LOCATION permissions if you need access to precise location. You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager.

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Access token best practices

Learn how to keep access tokens private in mobile apps.


Add the dependency

Mapbox Maps SDK and Navigation SDK compatibility

If you want to use the Search SDK with Mapbox Maps and Navigation SDKs, all these SDKs should have the same versions of the Common SDK. Common SDK versions used in Mapbox SDKs you can find in the corresponding release notes on the GitHub:

Mapbox provides the Search SDK components via Maven.

To add a Search SDK component as a dependency, you will need to configure your build to download the 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 21 or higher.

    android {
      defaultConfig {
          minSdkVersion 21
  5. Add the dependency under dependencies. Depending on which SDK component you need, the options are:

    • Address Autofill: To use the Address Autofill, add the autofill dependency.

      dependencies {
        implementation ""
    • Discover: To use the Discover, add the discover dependency.

      dependencies {
        implementation ""
    • Place Autocomplete: To use the Place Autocomplete, add the place-autocomplete dependency.

      dependencies {
        implementation ""
    • Offline Search: To use the Offline Search, add the offline dependency.

      dependencies {
        implementation ""
    • Search Engine: To use the Search Engine, add the mapbox-search-android dependency.

      dependencies {
        implementation ""
    • Search UI: To use the Search UI with pre-built UI components, add the mapbox-search-android-ui dependency. This will also include Address Autofill, Place Autocomplete, Offline, Search Engine automatically.

      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.

That's it, now you can start using Search SDK components. See more documentation to add search to an app: