Maps SDK for Android

Current version: v9.2.0 View changelog

  • Map styles
  • Run-time styling
  • Data clusters
  • Camera manipulation
  • Querying the map
  • Gestures
  • Map images

The Mapbox Maps SDK for Android is an open source toolset for displaying maps inside of your Android application.

Mapbox's demo app on the Google Play Store includes many examples of how to use the Mapbox Maps SDK for Android. The demo app and examples page will illustrate the power of the Mapbox Maps SDK for Android.

Upgrade to the most recent version

For information about migrating from older versions of the Mapbox Maps SDK for Android to newer ones, see:

Install the Maps SDK

Before starting to develop your application with the Maps SDK, you'll need to add the SDK as a dependency. You can find the following dependency given below in the MavenCentral repository. Although this document shows you how to insert the stable version of the Maps SDK inside of your project, you can also use the nightly build (i.e. SNAPSHOT) or the beta version, if one is available. Find more information about how to do this inside the project’s GitHub repository.

Begin installation

A step-by-step walkthrough to help you get started with Maps SDK for Android.

If your application is close or exceeds the 65k method count limit, you can mitigate this problem by enabling ProGuard inside your application. ProGuard directives are included in the Android dependencies to preserve the required classes. You can also shrink the file APK file size by making use of APK splitting.

1. Add the dependency

  1. Start Android Studio.
  2. Open up your application's build.gradle file.
  3. Make sure that your project's minSdkVersion is at API 14 or higher.
  4. Under dependencies, add a new implementation dependency line for the latest mapbox-android-sdk.
  5. Find the File in the toolbar and then click on Sync Project with Gradle Files.
repositories {

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.2.0'

Note: You might have mismatching Gradle dependencies once you add the Mapbox Maps SDK for Android. Don't forget that you can use exclude group like below, to remove certain dependencies:

implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:9.2.0'){
    exclude group: 'group_name', module: 'module_name'

Additionally, running gradle app_module_name_here:dependencies in your command line will print a list of dependencies. ./gradlew app:dependencies works if you have a Gradle wrapper. They are helpful for troubleshooting nimble Gradle configurations when various libraries are included in a single project. You can see the dependencies that specific libraries are bringing and where conflicts might be happening.

2. Get an access token

If you don't have a Mapbox account, sign up, and then navigate to your Account page. Copy your default public token to your clipboard. After you've added the Maps SDK as a dependency inside of your Android project, open the R.strings.xml file, create a new String resource, and paste the access token.

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

Then to pass this into the Maps SDK, you'll want to place the access token inside of your application's onCreate() method.

public class MyApplication extends Application {
public void onCreate() {
// Mapbox Access token
Mapbox.getInstance(getApplicationContext(), getString(R.string.mapbox_access_token));

The Maps SDK also provides a setToken() method in case you want to switch the Mapbox access token at runtime. Certain Mapbox APIs require special Mapbox tokens, such as maps in China. Setting a new token enables use of multiple Mapbox tools in conjunction with one another. This method allows you to set a token before a specific Mapbox tool is used instead of setting the token initially and being required to use the same token for all Mapbox-related requests.


3. Setup permissions

Starting with the 5.0 version of the Maps SDK, you can use the Manifest merge feature to reduce the need to include any Maps SDK required things inside of 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" />

4. Add a map

Open the Java file of the activity where you'd like to include the map in and add the code below to the file.

private MapView mapView;
protected void onCreate(Bundle savedInstanceState) {
Mapbox.getInstance(this, getString(R.string.mapbox_access_token);
mapView = (MapView) findViewById(;
mapView.getMapAsync(new OnMapReadyCallback() {
public void onMapReady(@NonNull MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
public void onStyleLoaded(@NonNull Style style) {
// Map is set up and the style has loaded. Now you can add data or make other map adjustments

Open the activity's XML layout file and add the mapView within your layout.


5. Lifecycle methods

The MapView contains its own lifecycle methods for managing Android's OpenGL lifecycle, which must be called directly from the containing Activity. In order for your app to correctly call the MapView's lifecycle methods, you must override the following lifecycle methods in the Activity that contains the MapView and call the respective MapView method. For example, your onStart() method should look like this:

protected void onStart() {

Like the onStart() override above, the following lifecycle methods also need to be overridden and include the matching MapView method:

protected void onResume() {
protected void onPause() {
protected void onStop() {
protected void onSaveInstanceState(Bundle outState) {
public void onLowMemory() {
protected void onDestroy() {

If you're using a fragment, call mapview.onDestroy() inside the fragment's onDestroyView() method rather than inside onDestroy():

public void onDestroyView() {


You must include the Mapbox wordmark and attribution notice on any map that uses the Mapbox Maps SDK for Android. The SDK provides an attribution layout that includes all required information and can be customized either in xml or using the UiSettings object.

You may adjust the position of the Mapbox wordmark and attribution notice, but they must stay visible on the map. You may also change the background and text color of the attribution notice to match your design aesthetics, but all information must be legible.

You may not otherwise alter the Mapbox wordmark or text attribution notice. If you wish to move or to remove the Mapbox wordmark, please contact our sales team to discuss options available under our Enterprise plans.

Attribution guidelines

Learn more about what kinds of attribution Mapbox requires and why.

Telemetry opt out

Mapbox Telemetry is a powerful location analytics platform included in this SDK. By default, the SDK sends anonymized location and usage data to Mapbox whenever the host app causes it to be gathered. The Mapbox Terms of Service require your app to provide users with a way to individually opt out of Mapbox Telemetry, which is provided automatically as part of the attribution control. If you hide the attribution control, you must provide an alternative opt out for your users to use.

MapView XML attributes

XML attributes can be added inside of the XML MapView to further customize map behavior, such as setting the starting camera position, enabling tilt, or adjusting the compass' location on the screen. All MapView XML attributes start with mapbox_ for identification and for removing any potential conflicts with other libraries. Due to the current implementation of Android Studio, you can't autogenerate MapView attributes by typing. View the full list of MapView attributes here.

Some examples of MapView attributes are:


Understanding GeoJSON

Many parts of the Mapbox Maps SDK for Android are based on GeoJSON, an open standard file format for representing map data. Many Maps SDK methods take GeoJSON geometries as a parameter or return GeoJSON features. For example, the Maps SDK has a GeoJSONSource class for adding data to a map style, and one helpful Maps SDK's querying method returns a list of GeoJSON Features.

The Mapbox Java SDK's GeoJSON module provides GeoJSON support to the Maps SDK. Although it's not required to use the Maps SDK, becoming more familiar with GeoJSON will greatly enhance your understanding and usage of the Maps SDK. Make sure to read how to use the Java SDK's GeoJSON module with the Maps SDK.

Was this page helpful?