Get Started with the Maps SDK for Android | Maps SDK | Android Docs

This guide describes the steps to install the most recent version of the Mapbox Maps SDK for Android, configure your Android app to use the SDK, and initialize a map.

Prerequisites

A Mapbox account: Sign up or log into a free account on Mapbox.
Android Studio: This guide includes details specific to the latest version of Android Studio.
Gradle: Make sure you have Gradle installed.

Part 1: Configure your credentials

Before starting to develop your application with the Maps SDK, you'll need to create and configure your credentials.

Step 1: Configure your public token

Your app must have a public access token configured to associate its usage of Mapbox resources with your account.

Follow these steps to add a public access token from your Mapbox account as an Android string resource.

Open your project folder or create a new project in Android Studio.

If creating a new project, we recommend using the Empty Activity project type.

Locate the resource folder:

In the project explorer, open your resource folder located at app/res/values.

Create a new resource file:

Left click on the resource folder
Select New > Values Resource File
Name the file mapbox_access_token.xml
Click the Ok button.

In the new file, copy and paste the code snippet below.

Make sure you are signed in to docs.mapbox.com. This will insert your default public token into the code snippet (a long string that starts with pk.).
If you are not signed in, you will need to replace the placeholder YOUR_MAPBOX_ACCESS_TOKEN with a token from your account's tokens page.

app/res/values/mapbox_access_token.xml


<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string>
</resources>

Your public access token is now available for use in your Android project. You will access it via the string resource you created in your implementation code.

Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime

GUIDE

Access token best practices

Learn how to keep access tokens private in mobile apps.

Adding Tokens at Runtime

You can also implement tokens at runtime, but this requires you to have a separate server to store your tokens. This is helpful if you want to rotate your tokens or add additional security by storing your tokens outside of the APK, but is a much more complex method of implementation.

If you do choose to follow this method, we recommend calling MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN before inflating the MapView, otherwise the app will crash.

Rotating Tokens

For more information on access token rotation, consult the Access Tokens Information page.

Step 2: (Optional) Configure permissions

If you need to access the user's location to show it on the map, follow the steps below. If you do not need to access the user's location, skip to Part 2: Add the dependency.

Open the Android Manifest.
- In the project explorer, go to app > manifests > AndroidManifest.mxl.
Determine the level of location access you need.
- If you only need general user location access, copy the first line of code below - the ACCESS_COARSE_LOCATION permission.
- If you also need access to more precise location data, copy the entire code snippet, including the ACCESS_FINE_LOCATION permission. The ACCESS_FINE_LOCATION will not work without also requesting ACCESS_COARSE_LOCATION access.
Add the permissions you copied to the Android Manifest.
- This code should be added to the top of AndroidManifest.xml, below the opening manifest tag and above the opening <application> tag.

AndroidManifest.xml


 
<!-- Include this permission to grab user's general location -->
 
<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" />

You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager.

Part 2: Add the dependency

Step 1: Add the Mapbox Maven Repository

Now that you have your credentials, add the dependency to your project.

Mapbox provides the Maps SDK via Maven.

To add the Mapbox Maps SDK as a dependency, you will need to configure your build to download the Maps SDK from Mapbox maven repository directly by following these steps:

In the project explorer, go to Gradle Scripts > settings.gradle file under the Gradle Scripts section and open the settings.gradle.kts file.
Add a new maven {...} definition inside the dependencyResolutionManagement.repositories. The hidden sections of the snippet below mimic the settings.gradle.kts file so you can see exactly where to place the snippet below:

Groovy

Kotlin

settings.gradle.kts

Groovy

Kotlin


 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
        }

settings.gradle.kts

Groovy

Kotlin


 
        // Mapbox Maven repository
 
        maven {
 
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
 
        }

Add the Mapbox Maven repository in the correct location

Make sure you configure the Mapbox maven repository inside dependencyResolutionManagement and not inside pluginManagement.

Step 2: Add Maps SDK Dependencies

Open up your module-level (for example app > GradleScripts > build.gradle.kts) Gradle configuration file and make sure that your project's minSdk is 21 or higher:

Groovy

Kotlin

build.gradle.kts

Groovy

Kotlin


android {
  ...
  defaultConfig {
      minSdk 21
      ...
  }
}

build.gradle.kts

Groovy

Kotlin


android {
  ...
  defaultConfig {
      minSdk = 21
      ...
  }
}

Add the Mapbox SDK for Android dependency in the same module-level (for example app > GradleScripts > build.gradle.kts) Gradle configuration file and add the following line to the dependencies section:

Groovy

Kotlin

build.gradle.kts

Groovy

Kotlin


dependencies {
  ...
  implementation 'com.mapbox.maps:android:11.10.2'
  ...
}

build.gradle.kts

Groovy

Kotlin


dependencies {
  ...
  implementation("com.mapbox.maps:android:11.10.2")
  ...
}

About Google Play Services

Starting from v11.8.0, the Mapbox Maps SDK for Android brings a transitive dependency on Google Play Services, from which the SDK gets an HTTP client that supports HTTP/3.

The Google Play Services dependency can be removed, and then the SDK will work without support for HTTP/3. For details about how to manage this dependency, follow the instructions in our Removing Google Play guide.

(Optional) If you are using Jetpack Compose to build your app, you will need to add the following to your app/build.gradle.kts configuration file:

Add compose = true to the build features section if it's not already there as seen in the code below.
Add the Mapbox SDK Jetpack Compose Extension to dependencies section as seen in the code below..

Groovy

Kotlin

build.gradle.kts

Groovy

Kotlin


android {
  buildFeatures {
    compose true
  }
  composeOptions {
    kotlinCompilerExtensionVersion = "1.3.2"
  }
}
dependencies {
  ...
  // If you're using compose also add the compose extension
  implementation 'com.mapbox.extension:maps-compose:11.10.2'
  ...
}

build.gradle.kts

Groovy

Kotlin


android {
  buildFeatures {
    compose = true
  }
}
dependencies {
  ...
  // If you're using compose also add the compose extension
  implementation("com.mapbox.extension:maps-compose:11.10.2")
  ...
}

Because you've edited your Gradle files, click File > Sync Project with Gradle Files in Android Studio.

Troubleshooting

Make sure you placed the maven code inside dependencyResolutionManagement and not pluginManagement. Placing the code here will prevent the Mapbox SDK from being accessible and throw errors later down the line. See Part 2: Add the dependency - Step 1: add the Mapbox Maven dependency for more details.
Check app/res/values/mapbox_access_token.xml has a token and does not say YOUR_MAPBOX_ACCESS_TOKEN.
Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.
You might have conflicting transitive dependencies. If necessary, you can use exclude group to remove certain dependencies (see Exclude transitive dependencies)

Part 3: Add a map

Now add a map to your application. This can be accomplished by either using Jetpack Compose or in Android View:

Jetpack Compose

Android View

With the Maps SDK for Android compose extension, you can add a map to your composable:

Make sure you added the Mapbox compose extension to your dependencies (see optional Step #6 above)
Go to app > kotlin+java and open the top folder.
Inside the folder, open the MainActivity.kt file.
Delete everything inside the file except the package import on the first line.
Lastly, copy and paste the following code block from below and delete the package import line from the example.

This code will create an interactable globe centered over the United States and set the view's zoom level to 2.

Kotlin

MainActivity.kt


package com.mapbox.maps.demo

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.geojson.Point
import com.mapbox.maps.extension.compose.MapboxMap
import com.mapbox.maps.extension.compose.animation.viewport.rememberMapViewportState

public class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContent {
      MapboxMap(
        Modifier.fillMaxSize(),
        mapViewportState = rememberMapViewportState {
          setCameraOptions {
            zoom(2.0)
            center(Point.fromLngLat(-98.0, 39.5))
            pitch(0.0)
            bearing(0.0)
          }
        },
      )
    }
  }
}

Breaking Changes When Using the Jetpack Compose Extension

When using the Mapbox Jetpack Compose Extension, some map plugins—including Compass, Scalebar, Logo, Attribution, and Lifecycle—are replaced by their Jetpack Compose counterparts.

As a result, APIs such as mapView.compass, mapView.scalebar, mapView.logo, mapView.attribution, and mapView.lifecycle will not function and may result in runtime exceptions. To avoid these issues, use the corresponding Compose APIs instead.

Learn more by seeing our Using Jetpack Compose Guide.

Instantiate a Mapbox map in your Android Activity:

Go to app > kotlin+java and open the top folder.
Inside the folder, open the MainActivity.kt file.
Delete everything inside the file except the package import on the first line.
Lastly, copy and paste the following code block from below and delete the package import line from the example.

This code will create that will fill the container with an interactable globe, centered over the United States and set to a zoom level 2.

Kotlin

MainActivity.kt


package com.mapbox.maps.demo

import android.os.Bundle
import androidx.activity.ComponentActivity
import com.mapbox.geojson.Point
import com.mapbox.maps.CameraOptions
import com.mapbox.maps.MapView

class MainActivity : ComponentActivity() {
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Create a map programmatically and set the initial camera
        mapView = MapView(this)
        mapView.mapboxMap.setCamera(
            CameraOptions.Builder()
                .center(Point.fromLngLat(-98.0, 39.5))
                .pitch(0.0)
                .zoom(2.0)
                .bearing(0.0)
                .build()
        )
        // Add the map view to the activity (you can also add it to other views as a child)
        setContentView(mapView)
    }
}

Now save your work and start the emulator. Once the emulator is finished loading, you should see an interactable globe:

If your implementation is not working as expected, view the following troubleshooting section:

Troubleshooting

Click on File > Save All to make sure you haven't missed any changes.
Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.
Make sure you are using the correct import package line. If you see package com.mapbox.maps.demo in your MainActivity.kt, you need to replace with your project's import line. This will typically follow the format of package.com.example.PROJECT_NAME.
If the mapbox library isn't being imported, check the following:
- Check app/res/values/mapbox_access_token.xml has a token and does not say YOUR_MAPBOX_ACCESS_TOKEN.
- Make sure you've added the required dependencies to the settings.gradle.kts file and build.gradle.kts match the example snippets seen in Part 2: Add the dependency.
Check you've imported the right libraries into the MainActivity file as seen in the example code.
Switch virtual devices if you can't get your map to show on the default pixel fold.
Check if you have conflicting transitive dependencies. If necessary, you can use exclude group to remove certain dependencies (see Exclude transitive dependencies)_