Maps SDK for Android

Current version: v9.3.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 a 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 configure your credentials and add the SDK as a dependency. This document describes the steps to install the stable version of the Maps SDK, but 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.

If your application is close to 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.

Configure credentials

Before installing the Mapbox Maps SDK for Android, you will need to gather the appropriate credentials. The Maps 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. If you plan to install the Maps SDK via direct download, you do not need to configure a secret token and can skip this step.

    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

Note
If you plan to install the Maps SDK via direct download, you do not need to configure a secret token and can skip to the next step.

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.

Add the dependency

Mapbox provides the Maps SDK via Maven and direct download. You can choose whichever you prefer.

To add the Mapbox Maps SDK as a dependency, you will need to configure your build to download the Maps 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. Make sure that your project's minSdkVersion is at API 14 or higher.

    android {
      ...
      defaultConfig {
          minSdkVersion 14
      }
    }
    
  4. Under dependencies, add a new build rule for the latest mapbox-android-sdk.

    dependencies {
      implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.3.0'
    }
    
  5. 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 Maps SDK dependency, you must authenticate your request with a valid username and password. In the previous section, you added these to a gradle.properties file in your Gradle user home folder.

    allprojects {
      repositories {
        maven {
          url 'https://api.mapbox.com/downloads/v2/releases/maven'
          authentication {
              basic(BasicAuthentication)
          }
          credentials {
              username = 'mapbox'
              // Use the secret token you stored in gradle.properties as the password
              password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
          }
        }
      }
    }
    
  6. Because you've edited your Gradle files, Android Studio will ask you whether you want to sync the Gradle files. You can sync now.

Note: You might have mismatching Gradle dependencies once you add the Mapbox Maps SDK for Android. If necessary, you can use exclude group to remove certain dependencies:

implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:9.3.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.

Configure 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" />

Add a map

Open the activity you'd like to add a map to and use the code below.

private MapView mapView;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Mapbox.getInstance(this, getString(R.string.mapbox_access_token));
setContentView(R.layout.activity_main);
mapView = (MapView) findViewById(R.id.mapView);
mapView.onCreate(savedInstanceState);
mapView.getMapAsync(new OnMapReadyCallback() {
@Override
public void onMapReady(@NonNull MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
@Override
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.

<com.mapbox.mapboxsdk.maps.MapView
  android:id="@+id/mapView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  />

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:

@Override
protected void onStart() {
super.onStart();
mapView.onStart();
}

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

@Override
protected void onResume() {
super.onResume();
mapView.onResume();
}
@Override
protected void onPause() {
super.onPause();
mapView.onPause();
}
@Override
protected void onStop() {
super.onStop();
mapView.onStop();
}
@Override
protected void onSaveInstanceState(Bundle outState) {
super.onSaveInstanceState(outState);
mapView.onSaveInstanceState(outState);
}
@Override
public void onLowMemory() {
super.onLowMemory();
mapView.onLowMemory();
}
@Override
protected void onDestroy() {
super.onDestroy();
mapView.onDestroy();
}

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

@Override
public void onDestroyView() {
super.onDestroyView();
mapView?.onDestroy();
}

Attribution

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.

guide
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:

<com.mapbox.mapboxsdk.maps.MapView
  mapbox:mapbox_cameraTargetLat="-36.84"
  mapbox:mapbox_cameraTargetLng="174.76"
  mapbox:mapbox_cameraZoom="10"
  mapbox:mapbox_cameraBearing="34.33"
  mapbox:mapbox_cameraTilt="50.25"
  mapbox:mapbox_cameraZoomMax="12.41"
  mapbox:mapbox_cameraZoomMin="6"
  mapbox:mapbox_uiRotateGestures="false"/>

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?